ADI CLI

Agent-centric Debugging Interface for Python programs.

Current release: 2.6.0.

Install

npm install -g @adi-tools/py

ADI requires Python 3.9 or newer on your PATH.

Quick Start

adi --help
adi list-frames "python script.py" "script.py:main"
# Copy the `target:` value printed by list-frames:
adi break "python script.py" "script.py:main#1"
adi exec "python script.py" "script.py:main#1" -s "print(locals())"
adi call-tree "python script.py" "script.py:main#1"

list-frames prints both target: and line-target:. Prefer target: for break, exec, and call-tree; keep line-target: as a fallback when you specifically want line-number targeting.

If your Python executable is not named python3 or python, set ADI_PYTHON:

ADI_PYTHON=/path/to/python adi --help

ADI_PYTHON controls the Python used to run ADI itself. The Python used for your debug target is the executable inside the command you pass to ADI.

Concurrent Agents

ADI can be launched from multiple terminals or agents. Runtime tracer files are created in a per-run temp directory. CLI state used by continue, state, list, and step-out is isolated by this priority in @adi-tools/py>=2.6.0:

1. ADI_STATE_DIR
2. ADI_DATA_DIR
3. ADI_SESSION_ID
4. CODEX_THREAD_ID
5. workspace-scoped temp fallback

For agent runtimes without a stable session environment variable, set ADI_STATE_DIR explicitly for each agent/session.

Notes

• The npm package is a thin launcher around the Python ADI implementation.
• Run ADI inside the same environment where your target Python command works.
• Use --allow-external when targeting stdlib/site-packages frames.
• MCP support is optional and not included in this npm MVP.

2.6.0 highlights

• Terminal-first agent workflow: list-frames -> target: -> break/exec/call-tree.
• Global npm install smoke tested with no repo PYTHONPATH and arbitrary cwd.
• Multi-agent state isolation smoke tested with ADI_DATA_DIR, ADI_STATE_DIR, and ADI_SESSION_ID.
• line-target: remains available as a fallback for line-number targeting.