Local-first flight recorder for Claude Code
npm install agent-recorderLocal-first flight recorder for Claude Code. Captures a persistent, human-readable timeline of execution including subagents, skills, and MCP tool calls.
``bash`
npm install -g agent-recorder
`bashSet up ~/.agent-recorder/ directory
agent-recorder install
After configuration, restart Claude Code to apply changes.
Requirements
- Node.js >= 20
- macOS or Linux
Commands
$3
-
agent-recorder start [--daemon] - Start the recording daemon
- agent-recorder stop - Stop the daemon
- agent-recorder restart - Restart the daemon
- agent-recorder status - Check if daemon is running$3
-
agent-recorder doctor - Comprehensive health check
- agent-recorder diagnose mcp - MCP proxy diagnostics
- agent-recorder logs - View daemon logs$3
-
agent-recorder install - Set up directories and show config
- agent-recorder configure claude - Configure Claude Code MCP settings
- agent-recorder configure show - Show current configuration$3
-
agent-recorder sessions list - List all recorded sessions
- agent-recorder sessions show - Show session details
- agent-recorder sessions view - View session events
- agent-recorder sessions tail - Follow session events in real-time
- agent-recorder tui - Interactive session explorer$3
-
agent-recorder export - Export session to JSON/JSONL$3
-
agent-recorder mock-mcp - Start a mock MCP server for testingEnvironment Variables
-
AR_LISTEN_PORT - REST API port (default: 8787)
- AR_MCP_PROXY_PORT - MCP proxy port (default: 8788)
- AR_DB_PATH - SQLite database path
- AR_DOWNSTREAM_MCP_URL - URL of the downstream MCP server to proxyHow It Works
Agent Recorder acts as a transparent MCP proxy between Claude Code and your MCP servers. It records:
- Tool calls (tools/list, tools/call)
- Timing and duration
- Success/error status
- Metadata (redacted for privacy)
It does not record prompts, chain-of-thought, or sensitive content.
Troubleshooting
$3
`bash
Check if port is already in use
lsof -i :8787
lsof -i :8788Force stop and restart
agent-recorder stop --force
agent-recorder start --daemon
`$3
`bash
Check configuration
agent-recorder configure showRe-configure if needed
agent-recorder configure claudeRestart Claude Code after configuration changes
`$3
`bash
Run full diagnostics
agent-recorder doctorCheck MCP proxy specifically
agent-recorder diagnose mcpTest with mock MCP server
agent-recorder mock-mcp --port 9999
In another terminal:
export AR_DOWNSTREAM_MCP_URL="http://127.0.0.1:9999/"
agent-recorder restart
``MIT