agent-trace

strace for AI agents.

Why

A coding agent rewrites 20 files in a background session. You get a pull request. You do not get the story. Which files did it read first? Why did it call the same tool three times? What failed before it found the fix?

Most tools trace LLM calls. That is one layer. The gap is everything around it: tool calls, file operations, decision points, error recovery, the actual commands the agent ran. agent-strace captures the full session and lets you replay it later. Export to Datadog, Honeycomb, New Relic, or Splunk for production observability. Set rules to stop the agent: cost ceiling, wrong file touched, too many tool calls. The agent stops. No prompt, no retry, no damage.

Install

# With uv (recommended)
uv tool install agent-strace

# Or with pip
pip install agent-strace

# Or run without installing
uvx agent-strace replay

Zero dependencies. Python 3.10+ standard library only.

Quick start

Option 1: Claude Code hooks — captures everything (prompts, responses, every tool call)

agent-strace setup   # prints hooks config — add to .claude/settings.json
agent-strace list    # list sessions
agent-strace replay  # replay the latest

Full config and JSON: docs/setup.md

Option 2: MCP proxy — wraps any MCP server, works with Cursor and Windsurf

agent-strace record -- npx -y @modelcontextprotocol/server-filesystem /tmp
agent-strace replay

Option 3: Python decorator — no MCP required

from agent_trace import trace_tool, start_session, end_session

start_session(name="my-agent")

@trace_tool
def search_codebase(query: str) -> str:
    return search(query)

end_session()

Full setup guide: docs/setup.md

What you can do

Understand a session

Command	What it does
agent-strace replay <id>	Replay a session in the terminal or as HTML
agent-strace explain <id>	Plain-English phase summary, no LLM required
agent-strace timeline <id>	Phase-by-phase view with costs and retries
agent-strace why <id> <event>	Causal chain for a specific decision
agent-strace diff <id-a> <id-b>	Structural or semantic session comparison
agent-strace compare <id-a> <id-b>	Regression report with verdict

Control and protect

Command	What it does
agent-strace watch	Live monitor with kill-switch rules
agent-strace watch --timeout 30m --budget $5	Watchdog mode — kills on limit, writes post-mortem
agent-strace audit <id>	Audit tool calls against a policy file
agent-strace record --redact	Strip secrets from traces before storage
agent-strace export --anonymize	Remove PII at export time

Analyse across sessions

Command	What it does
agent-strace dashboard	Multi-session overview
agent-strace budget-report	Weekly spend digest
agent-strace lint <id>	Flag bad behaviour patterns (loops, spirals, waste)
agent-strace drift	Detect behavioural drift over time
agent-strace standup	Plain-English summary of yesterday's sessions
agent-strace eval <id>	Score a session against behavioural baselines
agent-strace eval ci	Fail CI on behavioural regression

Export and integrate

Command	What it does
agent-strace export --format otlp-genai	Export to Datadog, Honeycomb, Grafana, Jaeger
agent-strace server	Server-side collector for multi-agent, multi-machine
agent-strace share <id>	Generate a shareable HTML replay
agent-strace sample	Export worst sessions as JSONL for eval datasets

Full flag reference: docs/commands.md

VS Code extension

Install agent-strace from the Extensions panel to see live session activity without leaving the editor.

Feature	Description
Status bar	Live cost, tool call count, and active tool name. Click to open the event stream.
Gutter annotations	Blue border on files the agent read, amber on files it modified.
Event stream panel	Live feed: every tool call, file op, LLM request, and error.
Pause button	Stops the agent mid-session via SIGSTOP.

pip install agent-strace   # 1. install
agent-strace setup         # 2. add hooks to Claude Code
# 3. open project in VS Code — extension activates when .agent-traces/ exists
# 4. start Claude Code — status bar appears immediately

Full docs: docs/vscode.md

Production

OTLP export — sessions become traces, tool calls become spans:

agent-strace export <session-id> --format otlp-genai \
  --endpoint http://localhost:4318

Per-backend setup (Datadog, Honeycomb, Grafana, New Relic, Splunk, Langfuse): docs/production.md

Server-side collector — for containers, CI, and multi-machine setups:

agent-strace server --port 4317 --storage ./traces
AGENT_STRACE_ENDPOINT=http://collector:4317 python my_agent.py

Full guide: docs/server.md

Auto-instrumentation — no code changes required:

from agent_trace.integrations import instrument_langchain
instrument_langchain()

Supported: OpenAI Agents SDK, LangChain, LiteLLM, Anthropic SDK, OpenAI SDK, AWS Strands. Guide: docs/integrations.md

How it works

Claude Code hooks — Claude Code fires hook events at every stage of its agentic loop. agent-strace registers as a handler, reads JSON from stdin, and writes trace events. Each hook runs as a separate process; session state in .agent-traces/.active-session correlates PreToolUse and PostToolUse for latency measurement.

MCP stdio proxy — sits between the agent and the MCP server, reads JSON-RPC messages (Content-Length framed or newline-delimited), classifies each one, and writes a trace event. Messages are forwarded unchanged. The agent and server do not know the proxy exists.

MCP HTTP/SSE proxy — same idea, different transport. Listens on a local port, forwards POST and SSE requests to the remote server, captures every JSON-RPC message in both directions.

Python decorator — @trace_tool logs a tool_call event before execution and a tool_result after. Errors and timing are captured automatically. @trace_llm_call does the same for LLM calls.

Running tests

python -m pytest tests/ -v

License

MIT. Use it however you want.

---

Sponsor · ADRs · Security · PyPI