# Kolo

Kolo is a text-based Python debugger for AI agents. Run your code with Kolo on and it records every function call in your project, with its arguments, local variables and return value, along with the SQL queries and HTTP requests your code makes. The result is written to plain-text files in `.kolo/traces/`, ready to grep.

[![downloads](https://img.shields.io/pypi/dm/kolo)](https://pypi.org/project/kolo/) [![Chat on Discord](https://img.shields.io/discord/899363528660635738?label=Chat%20on%20Discord)](https://discord.com/invite/FsTVcFwYUn)

[![PyPI version](https://img.shields.io/pypi/v/kolo?label=python%20package)](https://pypi.org/project/kolo/) [![supported python versions](https://img.shields.io/pypi/pyversions/kolo)](https://pypi.org/project/kolo/)

## Quickstart

1. Install Kolo:

   ```bash
   pip install kolo
   ```

2. Run any Python program with `KOLO=1` set:

   ```bash
   KOLO=1 python example.py
   ```

   When the program exits, Kolo saves the trace and prints the path to `.kolo/kolo.txt`.

3. Read the trace:

   ```bash
   kolo cat --returns
   ```

   This prints a short header followed by the call tree, with arguments (`↪`) and return values (`↩`):

   ```text
   0 __main__.<module> (0-13) 31μs
     1 __main__.main (7-9) 17μs
       ↪
       ↩ None
       2 __main__.fibonacci (1-4) 6μs
         ↪ n: 3
         ↩ 2
         3 __main__.fibonacci (1-4) 4μs
           ↪ n: 2
           ↩ 1
   ...
   ```

   Or search the trace files directly:

   ```bash
   grep -rn "fibonacci" .kolo/traces/
   ```

## How it works

1. **Capture.** Kolo records your code as it runs. See [the ways to capture a trace](#ways-to-capture-a-trace) below.
2. **Emit.** After each trace is saved, Kolo writes the five most recent traces to `.kolo/traces/` as text, in the background. Each trace is a directory that mirrors the call tree. A function call gets a `call.py` and a `return.py` (or a single `.py` file if it calls nothing else) holding its arguments, locals and return value. SQL queries are `.sql` files and HTTP requests and log messages are `.txt` files. Calls made on background threads are in `thread_<n>_<name>/` subdirectories. To emit an older trace, run [`kolo trace emit TRACE_ID`](reference/cli.md#kolo-trace-emit).
3. **Read.** Grep `.kolo/traces/` and open the files that match. For an overview, read `.kolo/kolo.txt` (recent traces plus the call tree of the latest one) or run [`kolo cat`](reference/cli.md#kolo-cat). [`kolo trace list`](reference/cli.md#kolo-trace-list) lists stored traces, newest first.

By default Kolo records code in your project and skips the standard library and third-party packages. [Filters](reference/config.md#filters) change that.

`.kolo/` is gitignored automatically. `.kolo/traces/` stays visible to ripgrep and tools built on it through a `.ignore` file.

## Ways to capture a trace

| How                                                           | Use it for                                                                                            |
| ------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| [`KOLO=1`](howto/trace-function-or-script.md#kolo1)           | Any Python process, start to finish. The simplest option.                                             |
| [`kolo run`](howto/trace-function-or-script.md#kolo-run)      | One command, without setting an environment variable. One trace per test with `--one-trace-per-test`. |
| [`kolo.enable`](howto/trace-function-or-script.md#koloenable) | One function or block of code.                                                                        |
| [`KoloMiddleware`](howto/trace-django-requests.md)            | One trace per Django request.                                                                         |
| [`kolo attach`](howto/attach-running-process.md)              | A process that is already running (CPython 3.14+).                                                    |

## Use Kolo with an AI agent

Install the [Kolo skill](howto/skill.md). It teaches coding agents such as Claude Code, Codex and Cursor to run code with `KOLO=1` and grep the trace files.

## Python support

Kolo runs on CPython 3.8 to 3.15 and on PyPy.

- On CPython 3.12 and newer, Kolo traces with `sys.monitoring`, implemented in Rust. This is the default and the fastest backend.
- On CPython 3.8 to 3.11, Kolo uses a Rust profiler built on `sys.setprofile`.
- On PyPy, Kolo uses a pure Python profiler.
- [`kolo attach`](howto/attach-running-process.md) needs CPython 3.14 or newer.

## Support

Questions or trouble getting set up? Get in touch:

- [Talk to us on Discord](https://discord.com/invite/FsTVcFwYUn)
- [Create an issue](https://github.com/koloai/kolo/issues/new/choose)
- [Email us](mailto:support@kolo.app)
- [Schedule a meeting with us to help get Kolo set up](https://calendly.com/wilhelmklopp)

```{toctree}
:maxdepth: 2
:hidden:

Quickstart <self>
```

```{toctree}
:maxdepth: 2
:hidden:
:caption: How to

Trace a function or script <howto/trace-function-or-script>
howto/trace-django-requests
Attach to a running process <howto/attach-running-process>
howto/skill
```

```{toctree}
:maxdepth: 2
:hidden:
:caption: Reference

reference/config
reference/cli

```

```{toctree}
:hidden:
:caption: Misc

changelog/index.md
Playground <https://play.kolo.app>
Set up VSCode <howto/vscode>
Model Context Protocol (MCP) <howto/mcp>
misc/docker
misc/share-traces
misc/plugins
```