agent-recorder

Agent Recorder

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.

The Problem

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.

---

Highlights

• Zero-config for Claude Code — install as a plugin, recording starts automatically
• Works with any MCP client — Claude Desktop, Cursor, VS Code via STDIO proxy
• Hierarchical event tree — agent → subagent → skill → tool relationships preserved
• Interactive TUI — browse sessions and inspect events in your terminal
• Export anywhere — JSON, JSONL, HAR (browser devtools), OpenTelemetry (Jaeger/Zipkin)
• Privacy-first — no prompts, no chain-of-thought, automatic key redaction
• 100% local — SQLite + localhost daemon, your data never leaves your machine

---

Quick Start

Claude Code Plugin (recommended)

# 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

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

docker compose up -d
# or
docker run -d -p 8787:8787 -v agent-recorder-data:/data agent-recorder

---

How It Works

Agent Recorder supports three recording methods depending on your setup:

1. Hooks (Claude Code)

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.

2. STDIO Proxy (Claude Desktop, Cursor, VS Code)

Wraps any stdio-based MCP server to capture JSON-RPC traffic transparently.