Agent Recorder

Local-first flight recorder for Claude Code. Captures a persistent, human-readable timeline of execution including subagents, skills, and MCP tool calls.

Install

``bash
npm install -g agent-recorder
`

Quick Start

`bash


Set up ~/.agent-recorder/ directory

agent-recorder install

Start the background daemon

agent-recorder start --daemon

Configure Claude Code integration

agent-recorder configure claude

Verify everything is working

agent-recorder doctor
`

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 testing

Environment 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 proxy

How 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 :8788

Force stop and restart

agent-recorder stop --force
agent-recorder start --daemon
`

$3

`bash


Check configuration

agent-recorder configure show

Re-configure if needed

agent-recorder configure claude

Restart Claude Code after configuration changes

`

$3

`bash


Run full diagnostics

agent-recorder doctor

Check MCP proxy specifically

agent-recorder diagnose mcp

Test 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
``

License

MIT