agent-strace — Claude Code MCP server: what it does, how to install
agent-strace — an MCP server for Claude Code captures agent prompts, tool calls, and errors to disk for ordered replays. It inspects capture completeness and validates branch reviewability before PR reviews.
MIT ★ 108 updated 2026-11-16
claude mcp add --env AGENT_TRACE_DIR=<AGENT_TRACE_DIR> --transport stdio agent-strace -- uvx agent-straceWhat agent-strace does
The server stores the full trail of an assistant session inside local files. Captured records preserve prompts, shell commands, file edits, and tool exceptions. You can inspect the run step by step or read an phased overview, while secret redaction masks tokens by default.
Beyond replaying runs, it grades audit evidence from healthy to invalid, highlighting capture gaps caused by provider limits. It also checks authoring context to confirm whether a pull request is ready for inspection and builds a redacted HTML summary bundle.
Operation relies on Python 3.10+ standard library and uvx. The project remains experimental, meaning it cannot serve as an airtight security boundary without custom threat evaluation.
What it helps with
- replay agent session execution step by step to debug failed commands
- audit capture completeness and identify missed tool interactions
- compile redacted session evidence packages for pull request reviews
- detect skills and tools that were available but never invoked across sessions
Example prompts for the agent
- Replay the latest assistant session in order and summarize what happened
- Inspect the health of our recorded trace and identify any provider gaps
- Check whether this branch is reviewable based on the local session log
How to install agent-strace
Platform CLI
claude mcp add --env AGENT_TRACE_DIR=<AGENT_TRACE_DIR> --transport stdio agent-strace -- uvx agent-straceReplace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from agent-strace <command>
Platform CLI
codex mcp add agent-strace --env AGENT_TRACE_DIR=<AGENT_TRACE_DIR> -- uvx agent-straceReplace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from agent-strace <command>
Config file
{
"mcpServers": {
"agent-strace": {
"command": "uvx",
"args": [
"agent-strace"
],
"env": {
"AGENT_TRACE_DIR": "<AGENT_TRACE_DIR>"
}
}
}
}Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from agent-strace <command>
Config file
{
"servers": {
"agent-strace": {
"type": "stdio",
"command": "uvx",
"args": [
"agent-strace"
],
"env": {
"AGENT_TRACE_DIR": "<AGENT_TRACE_DIR>"
}
}
}
}Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from agent-strace <command>
Platform CLI
gemini mcp add -e AGENT_TRACE_DIR=<AGENT_TRACE_DIR> agent-strace uvx agent-straceReplace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from agent-strace <command>
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about agent-strace
How to install agent-strace in Claude Code?
Run claude mcp add agent-trace -- uvx agent-strace in your terminal.
What does agent-strace do?
It records agent interactions, tool calls, and diffs to local storage, lets you replay actions sequentially, and evaluates trace completeness.
What is required to run agent-strace?
You need Python 3.10 or newer, uvx available in your path, and an optional AGENT_TRACE_DIR environment variable to define custom storage paths.