<p align="center">
<h1 align="center">Agent Recorder</h1>
<p align="center">
<strong>Flight recorder for AI coding agents — see every tool call, MCP request, and subagent spawn</strong>
</p>
<p align="center">
<a href="https://github.com/EdytaKucharska/agent_recorder/actions/workflows/ci.yml"><img src="https://github.com/EdytaKucharska/agent_recorder/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
<a href="https://www.npmjs.com/package/agent-recorder"><img src="https://badge.fury.io/js/agent-recorder.svg" alt="npm version"></a>
<a href="https://github.com/EdytaKucharska/agent_recorder/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License: MIT"></a>
<a href="https://www.npmjs.com/package/agent-recorder"><img src="https://img.shields.io/npm/dm/agent-recorder.svg" alt="npm downloads"></a>
<a href="https://nodejs.org/"><img src="https://img.shields.io/badge/node-%3E%3D20-brightgreen.svg" alt="Node.js >= 20"></a>
<a href="https://github.com/EdytaKucharska/agent_recorder/pulls"><img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg" alt="PRs Welcome"></a>
</p>
</p>
<br>
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.
<br>
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.