agent-trace

Local evidence and replay for coding agents.

agent-strace records what a coding agent did in a session (prompts, tool calls, file operations, commands, failures) as local files, then does three jobs:

1. Replay what happened. replay shows the session in order. explain summarizes it in phases.
2. See what the trace could not prove. health rates the evidence healthy, partial, unknown, or invalid, with observed gaps and known provider capture limits.
3. Attach safe evidence to review. review checks a PR's reviewability from its authoring session. share writes a privacy-minimized HTML evidence packet; share --dry-run previews what it would disclose.

uv tool install agent-strace
agent-strace setup --cli copilot   # or claude, codex, gemini, cursor; then use the agent
agent-strace replay                # latest session
agent-strace health                # what the capture missed
agent-strace review                # reviewability of this branch

Works with Claude Code, Codex, Copilot CLI, Gemini CLI, Cursor, and any MCP server, plus partial Copilot cloud agent capture. Python 3.10+ standard library only. Secret redaction is on by default. Start with the docs index, provider guides, and PR evidence workflow.

[!WARNING] Experimental. Do not treat it as a production security boundary without your own threat model, controls, and testing.

Try it without setup: which skills never load

uvx agent-strace skills --from-claude

This reads the Claude Code transcripts already on your machine (~/.claude/projects), writes no persistent trace store (it uses a temporary directory deleted on exit), and reports each skill as available, loaded, followed, and what happened after the load. It reports counts, not a score, and only for what the sessions recorded. For other agents, record sessions first, then run agent-strace skills. A never-loaded skill is a lead, not a verdict: no task may have needed it. Test it with skills eval. Guide: docs/skills.md.

Sample output (139 recorded sessions, trimmed):

Skills across 139 sessions since 2025-11-09. Availability reflects the filesystem now, not session time.
skill                   avail loaded load rate user/model median t pre-edit  follow  tests
------------------------------------------------------------------------------------------
frontend-design           139      2     2/139    0/3         3.1h      1/2     0/2    0/2
grilling                  139      0     0/139    0/0            -        -       -      -
web-design-guidelines     139      0     0/139    0/0            -        -       -      -

Never loaded (available in >= 5 sessions, loaded in 0):
  grilling (available in 139 sessions)
  web-design-guidelines (available in 139 sessions)

Quick start

Option 1: CLI hooks. Captures prompts, responses, and hook-visible tool calls

agent-strace setup             # Claude Code hooks for ~/.claude/settings.json
agent-strace setup --cli claude --verify # check Claude Code hooks + CLI, not live capture
agent-strace setup --cli codex # OpenAI Codex hooks in ~/.codex/hooks.json
agent-strace setup --cli codex --verify # check Codex user hooks + CLI, not live capture
agent-strace setup --cli gemini # Gemini CLI extension under ~/.gemini/extensions
agent-strace setup --cli cursor # Cursor project hooks in .cursor/hooks.json
agent-strace setup --cli copilot # GitHub Copilot CLI hooks in ~/.copilot/hooks
agent-strace list              # list sessions

Provider coverage and known gaps: docs/capture-matrix.md

Claude Code plugin

After installing agent-strace, install the repository as a native Claude Code plugin to enable tracing hooks plus the shared trace analyst agent and skill:

claude plugin marketplace add Siddhant-K-code/agent-trace
claude plugin install agent-strace@agent-trace

See the Claude Code plugin guide for verification, updates, uninstall steps, privacy boundaries, provider gaps, and release publication.

GitHub Copilot CLI plugin

After installing agent-strace, install the repository as a Copilot CLI plugin to enable tracing hooks plus the trace analyst agent and skill:

copilot plugin marketplace add Siddhant-K-code/agent-trace
copilot plugin install agent-strace@agent-trace

Restart Copilot CLI, then use /agent to select agent-strace:trace-analyst. Traces are written to .agent-traces/ in the repository you opened. Do not also run agent-strace setup --cli copilot, which would register duplicate hooks.

See the Copilot CLI plugin guide for verification, updates, and usage.

Option 2: MCP proxy. Wraps any MCP server, works with Cursor, Windsurf, and Copilot Desktop MCP servers

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()

Sessions go to $AGENT_TRACE_DIR when set, else .agent-traces; an explicit start_session(trace_dir=...) wins.

Full setup guide: docs/setup.md. Machine-wide install for platform teams: docs/platform-install.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 replay <id-a> --diff <id-b>	Side-by-side session comparison with tool args and output delta
agent-strace health <id>	Evidence health with observed gaps and capture-matrix provider limitations
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
agent-strace compaction <id>	Inspect context loss and behavior changes after compaction

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 and heartbeats sessions for postmortems
agent-strace mcp-scan	Scan runtime MCP poisoning indicators
agent-strace audit <id>	Audit tool calls against a policy file
agent-strace policy backtest	Test policy impact against historical sessions
agent-strace approval list	Human-in-the-loop approval queue
agent-strace rbac assign	Org and workspace-scoped role assignments
agent-strace auth login	SSO/OIDC login to a hosted collector
agent-strace telemetry status	Inspect, disable, or re-enable anonymous CLI telemetry, which is on by default
agent-strace apply	Apply .agent-strace.yaml config to local store or collector
agent-strace workspace new	Create an isolated workspace
agent-strace compliance export	Export compliance reports (EU AI Act, SOC 2, HIPAA)
agent-strace record	Strip secrets from traces before storage by default
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 team-report	Team spend by author, branch, or PR
agent-strace org-report	Monthly organization usage and estimated-cost digest
agent-strace compliance-report	Privacy-minimized framework evidence crosswalk
agent-strace cost --breakdown provider	Offline spend by provider and model
agent-strace tenant report	Per-customer cost, export, and erasure workflows
agent-strace backfill-meta	Write missing metadata for older subagent session dirs (dry run by default)
agent-strace cognitive-debt	Unreviewed agent-written code by session
agent-strace context-score	Compare efficiency stats (cost, tool calls, lint, scope) across AGENTS.md/CLAUDE.md versions. Not an outcome score
agent-strace skills	Skill adoption: available → loaded → followed → outcome (no score)
agent-strace skills eval	Experimental: run should/shouldn't-trigger tasks and count skill loads
agent-strace lint <id>	Flag bad behaviour patterns (loops, spirals, waste)
agent-strace drift	Detect behavioural drift over time
agent-strace fingerprint	Baseline an agent's behavioural profile
agent-strace tree	Show parent/child session hierarchy
agent-strace freeze	Freeze a tool-call sequence for regression checks
agent-strace standup	Plain-English summary of one session (latest by default)
agent-strace eval <id>	Gate a session on named quality criteria and baselines
agent-strace eval ci	Run the legacy normalized-score CI workflow

Export and integrate

Command	What it does
agent-strace export --format otlp-genai	Export to Datadog, Honeycomb, Grafana, Jaeger
agent-strace export --format temporal	Nest agent spans under Temporal activities
agent-strace export --format eu-ai-act	Generate Article 12/13 audit packages
agent-strace export --metrics	Export per-session behavioral metrics as OTLP gauges
agent-strace identity show	Machine identity: sign and verify sessions
agent-strace mcp	MCP server: query sessions, health, skill, and PR reviewability reports from Claude Code, Copilot CLI, Codex, or Gemini CLI
agent-strace server	Server-side collector for multi-agent, multi-machine
agent-strace share <id>	Generate a shareable HTML replay
agent-strace share --assignment <id>	Create a privacy-minimized assignment submission ZIP
agent-strace score submission.zip	Apply a deterministic process-telemetry rubric
agent-strace pr-comment	Post or update a session summary on the current PR
agent-strace review	Check PR reviewability: rationale, scope, validation, stewardship, evidence health
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.

Anonymous extension usage telemetry is enabled by default and can be disabled from the Command Palette or agentTrace.telemetry.enabled setting. No prompts, trace contents, paths, session IDs, command arguments, or repository data are sent.

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.
Evidence review	Ordered events, evidence health, gaps, relationships, annotations, raw fields, and reviewer filters.
Local review actions	Compare sessions, save a privacy-minimized HTML review, or download OTLP JSON without uploading.
Pause button	Stops the agent mid-session via SIGSTOP.

pip install agent-strace   # 1. install
agent-strace setup         # 2. add hooks to Claude Code; use --cli codex, gemini, cursor, or copilot for other CLIs
# 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
export AGENT_STRACE_ENDPOINT=http://collector:4317   # read by hook commands and Python integrations

Full guide: docs/server.md

Auto-instrumentation: no code changes required:

agent-strace auto --detect -- python my_agent.py

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

GitHub Actions: run evals in CI, post results to the step summary, fail on regression:

- uses: Siddhant-K-code/agent-trace@v0.93.1
  with:
    config: .agent-evals.yaml
    baseline: .agent-evals-baseline.json
    tolerance: "0.05"

Marketplace listing · Action reference

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 unittest discover -s tests -v

License

MIT. Use it however you want.

---

Sponsor · ADRs · Security · Contributing · Release guide · PyPI