kolo

Kolo - Text Based Python Debugger for AI agents

The core workflow

1. Execute code with Kolo activated (KOLO=1)
2. Grep the trace data kolo emits in .kolo/traces — search for a function name, URL fragment, SQL table, or error string, then read the matching files
   • If you can't find the desired trace, view all recent traces with kolo trace list, then emit the desired trace manually with kolo trace emit <trace_id>
   • If you are not sure what to grep for or want to see an overview of everything that executed during a trace look at .kolo/kolo.txt or run kolo cat <trace_id>
3. Make desired code changes, then re-run (back to step 1)

Installing Kolo

• pip install kolo - install kolo from PyPI as per the project's conventions and only if it's not already installed

Enabling Kolo

• Set the KOLO=1 environment variable.
  • Any python process that starts up will be traced with Kolo (this is powered by the .pth mechanism in Python)
  • This is the recommended and simplest way to activate Kolo
• Other ways to activate
  • kolo run - activate kolo for a specific python program or script: e.g. kolo run python my_script.py
  • kolo.enable - activate kolo for a specific code block. use as context manager: with kolo.enable() or as decorator: @kolo.enable()

Using Kolo

Use the kolo cli to view trace data.

• Run bare kolo to see useful commands, recent traces and the location of kolo.txt.
• Use kolo trace list to list traces (most recent first). Specify number of traces to list with --count <count> (optional)

Key insight: grep the traces directly

By default kolo will emit the 5 most recently captured traces in .kolo/traces/. Each trace is a directory containing the full trace data as plain text files with human-readable section headers — read one directly to see everything captured for a given call, no special parser needed.

Simply grepping for function names or HTTP request fragments will find the relevant data. The files contain:

• Full call stacks (how functions were invoked)
• Complete HTTP request/response (headers, body, status, timing)
• Function arguments and return values
• Execution timing for each call

Manually emit a trace using kolo trace emit <trace_id>. If you'd like to emit it to an output directory other than .kolo/traces specify it with --output-dir

kolo.txt

kolo.txt is the "homepage" of kolo output. Read it with head - it contains useful commands, a list of recent traces, and the full compact (kolo cat) representation of the latest trace. Kolo automatically updates this file as new traces are captured.

Other useful commands

• kolo cat — prefer Grep first, not cat. cat dumps an entire trace to stdout and can easily exceed your context window on real applications. Only reach for cat after you've narrowed to a specific small trace.
  • bare kolo cat outputs the most recent trace in compact format
  • kolo cat TRACE_ID outputs a specific trace
  • kolo cat TRACE_ID --returns includes input/return values
• kolo trace node <trace_id> <node_index> — fetch full details of a specific node (args, locals, return value) without grepping. Faster than cat when you already know the node index from the trace summary.

Config

The kolo config file lives at .kolo/config.toml

Filters

By default Kolo traces all code the project directory and ignores standard library or third party code. Filters customize this behavior.

Ignore Frames

ignore_frames is a list of file path fragments:

# .kolo/config.toml
[filters]
ignore_frames = ["ignore_me.py", "/ignore_directory/"]

This will ignore any file called ignore_me.py or any file with /ignore_directory/ in its path.

Include Frames

# .kolo/config.toml
[filters]
include_frames = ["json", "django/db"]

This will include any frames from the json module of the standard library and from Django's database code in django.db.

Note: Including standard library and third party code can generate a lot of extra data, which may slow down execution. If you notice slow execution, adjust ignores and includes to capture fewer frames.

More config options: https://docs.kolo.app/reference/config

Further documentation

https://docs.kolo.app

Skill version: v0.1