# agent-strace

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.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 108 repo stars
- Author: Siddhant-K-code
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/Siddhant-K-code/agent-trace
- Updated: 2026-11-16
- Security check: automated, 2026-11-17 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/mcp/agent-strace

## What it 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.

## Requirements
- Needs: Python and uv (commands run via uvx)
- Environment variables: `AGENT_TRACE_DIR` — keys and tokens: ask the human for the values, never commit them or put them in shared files.

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add --env AGENT_TRACE_DIR=<AGENT_TRACE_DIR> --transport stdio agent-strace -- uvx agent-strace
```
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>

### Codex

**Platform CLI**
```bash
codex mcp add agent-strace --env AGENT_TRACE_DIR=<AGENT_TRACE_DIR> -- uvx agent-strace
```
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>

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "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>

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "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>

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add -e AGENT_TRACE_DIR=<AGENT_TRACE_DIR> agent-strace uvx agent-strace
```
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>

## When to use it
- 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
- 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

## Similar
- [orca-replay](https://affpapa.org/en/nevibecode/skills/orca-replay.md) — skill · ★ 1109 repo stars
- [strace-ltrace](https://affpapa.org/en/nevibecode/skills/strace-ltrace.md) — skill · 782 installs
- [trace](https://affpapa.org/en/nevibecode/skills/trace.md) — skill · 861 installs
- [grounding-before-coding](https://affpapa.org/en/nevibecode/skills/grounding-before-coding.md) — skill · 25600 installs
- [principle-attack-the-premise](https://affpapa.org/en/nevibecode/skills/principle-attack-the-premise.md) — skill · 10100 installs
- [debug-trace](https://affpapa.org/en/nevibecode/commands/debug-trace.md) — command · ★ 42780 repo stars

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
