A community-driven registry for Claude, Cursor, Windsurf, Cline & more. Not affiliated with Anthropic.
Are you the author? Sign in to claim
Know what your AI agent actually did. Agent Recorder logs every tool call across your MCP servers — locally, to SQLite,
Flight recorder for AI coding agents — see every tool call, MCP request, and subagent spawn
Ever wondered what your AI agent is actually doing? Agent Recorder captures every tool call, MCP server interaction, and subagent spawn into a local SQLite database — giving you a full, searchable timeline of agent execution. No prompts captured. No chain-of-thought leaked. Just observable boundaries.
AI coding agents (Claude Code, Cursor, etc.) call dozens of tools per session — file reads, shell commands, MCP servers, subagents — but there's no easy way to see what happened after the fact. Debugging agent behavior means scrolling through terminal output or guessing what went wrong.
Agent Recorder fixes this. It sits transparently between your agent and its tools, recording a structured timeline you can search, filter, export, and inspect — without ever capturing sensitive prompts or reasoning.
# In Claude Code:
/plugin install agent-recorder@EdytaKucharska/agent_recorder
That's it. The plugin installs a PostToolUse hook — every tool call is recorded automatically.
| Command | Description |
|---|---|
/agent-recorder:start | Start the recording daemon |
/agent-recorder:stop | Stop the recording daemon |
/agent-recorder:open | Open the TUI to browse sessions |
/agent-recorder:status | Check if daemon is running |
/agent-recorder:export | Export session to JSON/HAR/OTLP |
npm install -g agent-recorder
agent-recorder install # Configure data directory + Claude Code
agent-recorder start --daemon # Start recording
agent-recorder hooks install # Install Claude Code hooks
# Restart Claude Code — tool calls are now recorded!
agent-recorder tui # Browse recordings
docker compose up -d
# or
docker run -d -p 8787:8787 -v agent-recorder-data:/data agent-recorder
Agent Recorder supports three recording methods depending on your setup:
Claude Code's native hooks fire on every tool call. Zero overhead, zero config.
┌─────────────────┐ PostToolUse hook ┌─────────────────┐
│ Claude Code │ ───────────────────────► │ Agent Recorder │
│ │ │ Service │
│ (any MCP │ SessionStart/End │ (localhost) │
│ transport) │ ───────────────────────► │ │
└─────────────────┘ └─────────────────┘
Captures: All tool calls (Bash, Read, Write, Edit, Glob, Grep, MCP tools, etc.) with input/output details, MCP server name, method, and truncated I/O summaries.
Wraps any stdio-based MCP server to capture JSON-RPC traffic transparently.
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ MCP Client │ stdin │ agent-recorder │ stdin │ MCP Server │
│ (Claude Desktop │ ──────► │ -proxy │ ──────► │ (e.g. github) │
│ Cursor, etc.) │ ◄────── │ │ ◄────── │ │
└─────────────────┘ stdout └────────┬────────┘ stdout └─────────────────┘
│ records events
▼
┌─────────────────┐
│ Agent Recorder │
│ Service │
└─────────────────┘
Claude Desktop config example:
{
"mcpServers": {
"github": {
"command": "agent-recorder-proxy",
"args": [
"-e",
"http://localhost:8787/api/stdio",
"--",
"npx",
"-y",
"@modelcontextprotocol/server-github"
]
}
}
}
Aggregate multiple MCP servers behind one endpoint. All traffic is recorded and routed.
agent-recorder upstream add github https://api.github.com/mcp
agent-recorder upstream add tessl https://tessl.io/mcp --header "Authorization: Bearer $TOKEN"
agent-recorder upstream list
Browse sessions and inspect events interactively:
agent-recorder tui
┌─ Sessions ──────────────────────────────────────────────────────────┐
│ ID Status Events Last Active Duration │
│ a3f1b2c active 47 2s ago 12m 34s │
│ d8e4f5a completed 132 1h ago 45m 12s │
│ b7c9d1e completed 23 3h ago 5m 08s │
└─────────────────────────────────────────────────────────────────────┘
↑/↓ navigate Enter view / search r refresh q quit
┌─ Events (session a3f1b2c) ──────────────────────────────────────────┐
│ Seq Type Name Server Duration Status │
│ 1 tool_call Read claude-code 12ms success │
│ 2 tool_call search_repos github 340ms success │
│ 3 subagent Explore claude-code 1.2s success │
│ 4 tool_call Bash claude-code 89ms success │
│ 5 tool_call Edit claude-code 15ms success │
└─────────────────────────────────────────────────────────────────────┘
i input o output j raw JSON Tab filter f follow Esc back
agent-recorder start [--daemon] # Start the recording service
agent-recorder stop [--force] # Stop the service (--force for SIGKILL)
agent-recorder restart # Restart the service
agent-recorder status # Check service status + provider health
agent-recorder logs [--tail 50] # View daemon logs
agent-recorder hooks install # Install hooks into Claude Code
agent-recorder hooks uninstall # Remove hooks
agent-recorder hooks status # Show hook installation status
agent-recorder tui # Interactive terminal UI
agent-recorder sessions list # List all sessions (--status active/completed/error)
agent-recorder sessions show <id> # Show session details
agent-recorder sessions current # Get active session ID
agent-recorder sessions view <id> # View events with header (--follow, --tail)
agent-recorder sessions tail <id> # Tail events like tail -f (--interval, -n)
agent-recorder sessions stats <id> # Event counts, tool distribution
agent-recorder sessions grep <id> # Search events (--tool, --status, --error, --json)
agent-recorder sessions summarize <id> # Metadata summary (--format text|json)
agent-recorder export <id> # Export to JSONL (default)
agent-recorder export <id> --format json # Pretty-printed JSON
agent-recorder export <id> --format har # HTTP Archive (browser dev tools)
agent-recorder export <id> --format otlp # OpenTelemetry (Jaeger, Zipkin)
agent-recorder export <id> -o session.har # Export to file
| Format | Use Case |
|---|---|
| jsonl | Streaming, piping to other tools |
| json | Human-readable inspection |
| har | Import into browser dev tools, Charles Proxy, Postman |
| otlp | Send to Jaeger, Zipkin, Grafana Tempo, any OpenTelemetry tool |
agent-recorder upstream add <name> <url> # Add upstream MCP server
agent-recorder upstream add <name> <url> \
--header "Authorization: Bearer $TOKEN" # With auth headers
agent-recorder upstream remove <name> # Remove upstream
agent-recorder upstream list # List all upstreams
agent-recorder add <name> <url> # Add MCP provider (hub mode)
agent-recorder remove <name> # Remove provider
agent-recorder list # List providers
agent-recorder install # Set up data directory + Claude config
agent-recorder doctor # Full health check and diagnostics
agent-recorder diagnose mcp # Focused MCP proxy diagnostics
agent-recorder discover # Find MCP configs across all tools
agent-recorder configure claude # Configure Claude Code MCP settings
agent-recorder configure wrap [--all] # Wrap MCP servers with proxy
agent-recorder configure wrap --undo # Unwrap proxied servers
The discover command scans six config sources: Claude Code (v2 + legacy), Cursor IDE, VS Code, project-level .claude/, project-level .cursor/.
| Guarantee | Detail |
|---|---|
| No prompt capture | Only tool call boundaries are recorded |
| No reasoning capture | Chain-of-thought is never stored |
| Automatic redaction | Keys like api_key, token, authorization, password, secret are stripped from payloads |
| Payload truncation | Large payloads are truncated to prevent storage bloat |
| Localhost only | Daemon binds to 127.0.0.1, never 0.0.0.0 |
| Opt-in telemetry | Anonymous, content-free PostHog analytics — disabled by default |
| Fail-open | Recording/telemetry errors never block the MCP proxy |
All endpoints are localhost-only (127.0.0.1).
| Method | Endpoint | Description |
|---|---|---|
| GET | /api/sessions | List sessions |
| POST | /api/sessions | Create session |
| GET | /api/sessions/current | Active session |
| GET | /api/sessions/:id | Session details |
| POST | /api/sessions/:id/end | End session |
| GET | /api/sessions/:id/events | List events |
| GET | /api/sessions/:id/events/count | Event count |
| GET | /api/sessions/:id/events/latest-tool-call | Latest tool call |
| POST | /api/events | Insert event |
| POST | /api/hooks | Receive hook events |
| GET | /api/health | Daemon health |
| Variable | Default | Description |
|---|---|---|
AR_LISTEN_PORT | 8787 | REST API / hooks port |
AR_MCP_PROXY_PORT | 8788 | MCP proxy port |
AR_UI_PORT | 8789 | Web UI port (reserved) |
AR_DB_PATH | ~/.agent-recorder/*.sqlite | SQLite database path |
AR_DOWNSTREAM_MCP_URL | (none) | Upstream MCP server (legacy) |
AR_REDACT_KEYS | (none) | Comma-separated keys to redact |
AR_DEBUG_PROXY | 0 | Enable proxy debug logging |
AGENT_RECORDER_TELEMETRY | off | Telemetry: on or off |
packages/
├── types/ # Portable type definitions (zero deps)
├── core/ # Event model, redaction, SQLite storage
├── service/ # Fastify daemon: MCP proxy + recorder + REST API
├── cli/ # CLI commands + TUI (Ink)
├── hooks/ # Claude Code hook handlers
├── stdio-proxy/ # STDIO proxy for MCP server observability
├── ui/ # React + Vite web UI
└── dist/ # Distribution bundler for npm publishing
Dependency flow: types → core → service / hooks / stdio-proxy → cli → dist
Tech stack: TypeScript (strict) · Node.js 20+ · Fastify · SQLite (better-sqlite3) · Commander.js · Ink (TUI) · React + Vite (web UI)
git clone https://github.com/EdytaKucharska/agent_recorder
cd agent_recorder
pnpm install
pnpm build # Build all packages
pnpm test # Run tests
pnpm lint # Lint
pnpm build:dist # Build distribution package
pnpm smoke:dist # Smoke test the distribution
| Binary | Description |
|---|---|
agent-recorder | Main CLI |
agent-recorder-hook | Hook handler (called by Claude Code) |
agent-recorder-proxy | STDIO proxy wrapper for MCP servers |
agent-recorder hooks status # Check hook installation
agent-recorder doctor # Full diagnostics
agent-recorder status # Verify daemon is running
If hooks show as null in ~/.claude/settings.json, reinstall with agent-recorder hooks install and restart Claude Code.
agent-recorder statusagent-recorder logs --tail 100agent-recorder doctoragent-recorder discover --verbose # Scan all MCP config sources
agent-recorder diagnose mcp # MCP-specific diagnostics
Contributions are welcome! Please open an issue first to discuss what you'd like to change.
pnpm install && pnpm build && pnpm test # Verify everything passes before submitting
MIT © Edyta Kucharska
If Agent Recorder helped you debug an agent session, consider giving it a ⭐
mcp-language-server gives MCP enabled clients access semantic tools like get definition, references, rename, and diagnos
Run Claude Code as an MCP server so any agent can delegate coding tasks to it
MCP server integration for DaVinci Resolve Studio
@microsoft✓ OfficialBrowser automation using accessibility snapshots instead of screenshots