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.

Quickstart¶

Install Kolo:
```
pip install kolo
```
Run any Python program with KOLO=1 set:
```
KOLO=1 python example.py
```
When the program exits, Kolo saves the trace and prints the path to .kolo/kolo.txt.

Read the trace:

kolo cat --returns

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

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:

grep -rn "fibonacci" .kolo/traces/

How it works¶

Capture. Kolo records your code as it runs. See the ways to capture a trace below.
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.
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. 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 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`	Any Python process, start to finish. The simplest option.
`kolo run`	One command, without setting an environment variable. One trace per test with `--one-trace-per-test`.
`kolo.enable`	One function or block of code.
`KoloMiddleware`	One trace per Django request.
`kolo attach`	A process that is already running (CPython 3.14+).

Use Kolo with an AI agent¶

Install the Kolo skill. 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 needs CPython 3.14 or newer.

Support¶

Questions or trouble getting set up? Get in touch: