Skip to content

WinnCook/agentcasebook

BranchesTags

Repository files navigation

agentrace 🔍 — Your agent's black box recorder

npm version CI License: MIT Node.js

Universal agent session tracing, replay, and analysis. Think "OpenTelemetry for AI agents" but lightweight and opinionated.

Quick Start

npx agentrace list --scan        # Discover and list all agent sessions
npx agentrace stats --last 7d   # Show analytics for last week
npx agentrace replay <session>   # Step-by-step session replay
npx agentrace export <session> --format markdown  # Export session report

Works out of the box with Claude Code, Codex, OpenClaw, and more.

Features

🎯 Zero config — Auto-detects agent sessions from known paths 🔍 Universal tracing — Supports Claude Code, Codex, OpenClaw, Cursor 📊 Rich analytics — Cost tracking, pattern detection, success rates 🎬 Session replay — Step-by-step visualization with file changes 💰 Cost analysis — Token usage and spend tracking by model/agent 🔄 Pattern detection — Identifies loops, failures, and inefficiencies 📁 File tracking — Monitor code changes across sessions 🚀 MCP server — Query your session history programmatically 📝 Export formats — Markdown, JSON, HTML reports 🗃️ Local-first — SQLite storage, no cloud dependencies

Installation

npx (Recommended)

npx agentrace --help

npm

npm install -g agentrace
agentrace --help

Homebrew (Coming soon)

brew install agentrace

CLI Reference

agentrace list [options]

List and discover agent sessions.

agentrace list                           # Last 7 days
agentrace list --last 30d               # Last 30 days
agentrace list --agent claude-code      # Filter by agent
agentrace list --status completed       # Filter by status
agentrace list --scan                   # Scan for new sessions first
agentrace list --json                   # JSON output

Options:

  • --agent <name> - Filter by agent: claude-code, codex, openclaw, cursor
  • --last <duration> - Time period: 7d, 2w, 1m (default: 7d)
  • --status <status> - Filter by: running, completed, failed, abandoned
  • --limit <number> - Max sessions to show (default: 50)
  • --working-dir <path> - Filter by working directory
  • --scan - Scan filesystem for new sessions first
  • --json - Output as JSON

agentrace watch [options]

Watch a live or recent session in real-time.

agentrace watch                          # Watch most recent active session
agentrace watch --agent claude-code     # Watch latest claude-code session
agentrace watch --session abc123        # Watch specific session

Options:

  • --agent <name> - Filter by agent type
  • --session <id> - Watch specific session ID
  • --follow - Follow updates in real-time (default: true)
  • --interval <ms> - Polling interval (default: 2000ms)

agentrace replay <session-id> [options]

Step-by-step replay with rich terminal output.

agentrace replay abc123                  # Normal speed replay
agentrace replay abc123 --speed 5       # 5x speed
agentrace replay abc123 --step           # Manual stepping
agentrace replay abc123 --filter tool_call  # Filter event types

Options:

  • --speed <1-10> - Playback speed multiplier (default: 3)
  • --filter <type> - Filter events: tool_call, message, error, etc.
  • --from <timestamp> - Start from specific time
  • --to <timestamp> - End at specific time
  • --step - Manual stepping (press Enter)
  • --detailed - Show full event content

agentrace stats [options]

Analytics dashboard with session statistics.

agentrace stats                          # Last 7 days overview
agentrace stats --last 30d --costs      # Include cost breakdown
agentrace stats --agent claude-code     # Agent-specific stats
agentrace stats --by model --patterns   # Group by model, show patterns

Options:

  • --last <duration> - Time period (default: 7d)
  • --agent <name> - Filter by agent type
  • --by <grouping> - Group by: day, week, agent, model (default: agent)
  • --costs - Include detailed cost breakdown
  • --patterns - Include pattern analysis (loops, failures)
  • --json - Output as JSON

agentrace diff <session-a> <session-b>

Side-by-side comparison of two sessions.

agentrace diff abc123 def456             # Compare two sessions
agentrace diff abc123 def456 --files    # Include file changes
agentrace diff abc123 def456 --json     # JSON output

Options:

  • --metrics-only - Show only metrics, not detailed events
  • --events - Include detailed event comparison
  • --files - Include file change comparison
  • --json - Output as JSON

agentrace export <session-id> [options]

Export session as shareable document.

agentrace export abc123                  # Export as Markdown
agentrace export abc123 --format html   # Export as HTML
agentrace export abc123 --format json --detailed  # Detailed JSON
agentrace export abc123 --output report.md  # Custom filename

Options:

  • --format <format> - Output format: markdown, json, html (default: markdown)
  • --output <file> - Output file path
  • --include-costs - Include cost analysis
  • --include-patterns - Include pattern analysis
  • --include-timeline - Include detailed timeline
  • --detailed - Include full event content

agentrace serve [options]

Start MCP server for programmatic access.

agentrace serve                          # Start on port 3000
agentrace serve --port 8080             # Custom port
agentrace serve --auto-scan             # Auto-discover sessions

Options:

  • --port <port> - Port to listen on (default: 3000)
  • --auto-scan - Scan for sessions on startup
  • --scan-interval <minutes> - Auto-scan interval (default: 0/disabled)

Supported Agents

Claude Code

Status: ✅ Full support Location: ~/.claude/projects/*/sessions/ Format: JSONL files with tool_use blocks

Codex

Status: ✅ Full support Location: ~/.codex/sessions/ Format: JSON conversation logs

OpenClaw

Status: ✅ Full support Location: ~/.openclaw/sessions/, ./data/sessions Format: JSON log files

Cursor

Status: 🚧 Placeholder (format TBD) Location: ~/.cursor/logs/ Format: Log format not yet documented

Want to add support for your agent? See the adapter guide.

MCP Server

Start the MCP server to query session data programmatically:

agentrace serve --port 3000

Available Tools

query_sessions - Search and filter sessions

{
  "name": "query_sessions",
  "arguments": {
    "agent": "claude-code",
    "status": "completed",
    "since": "2024-01-01",
    "limit": 10
  }
}

get_timeline - Get session event timeline

{
  "name": "get_timeline",
  "arguments": {
    "session_id": "abc123",
    "include_content": false
  }
}

get_stats - Aggregate statistics

{
  "name": "get_stats",
  "arguments": {
    "agent": "claude-code",
    "since": "2024-01-01",
    "include_patterns": true
  }
}

get_file_changes - File modification history

{
  "name": "get_file_changes",
  "arguments": {
    "session_id": "abc123",
    "change_type": "modify"
  }
}

scan_for_sessions - Discover new sessions

{
  "name": "scan_for_sessions",
  "arguments": {
    "agent": "claude-code",
    "force_rescan": false
  }
}

Full MCP documentation

Database Schema

agentrace uses SQLite with the following schema:

Sessions - High-level session metadata

CREATE TABLE sessions (
  id TEXT PRIMARY KEY,
  agent TEXT NOT NULL,
  started_at TEXT NOT NULL,
  ended_at TEXT,
  status TEXT DEFAULT 'running',
  prompt TEXT,
  working_dir TEXT,
  total_tokens INTEGER DEFAULT 0,
  estimated_cost_usd REAL DEFAULT 0,
  model TEXT
);

Events - Individual session events (tool calls, messages, etc.)

CREATE TABLE events (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  session_id TEXT NOT NULL,
  timestamp TEXT NOT NULL,
  type TEXT NOT NULL,  -- 'tool_call', 'message', 'error', etc.
  name TEXT,
  content TEXT,
  duration_ms INTEGER,
  tokens INTEGER
);

File Changes - Code modifications tracked per session

CREATE TABLE file_changes (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  session_id TEXT NOT NULL,
  file_path TEXT NOT NULL,
  change_type TEXT NOT NULL,  -- 'create', 'modify', 'delete'
  diff TEXT,
  lines_added INTEGER DEFAULT 0,
  lines_removed INTEGER DEFAULT 0
);

Data is stored in ~/.agentrace/agentrace.db by default.

Examples

Weekly Development Report

# Generate comprehensive weekly report
agentrace stats --last 7d --costs --patterns > weekly-report.txt
agentrace list --last 7d --json > sessions.json

Cost Analysis

# Track spend by agent and model
agentrace stats --by model --costs
agentrace stats --agent claude-code --last 30d --costs

Debug Failed Sessions

# Find and analyze failures
agentrace list --status failed --last 30d
agentrace replay <failed-session-id> --filter error
agentrace export <failed-session-id> --format markdown

Compare Approaches

# Compare two different implementation approaches
agentrace diff session-A session-B --files

Real-time Monitoring

# Monitor active session
agentrace watch --follow

Configuration

No configuration files needed! agentrace auto-detects agent installations and uses sensible defaults.

Environment Variables:

  • AGENTRACE_DB_PATH - Custom database location
  • AGENTRACE_LOG_LEVEL - Logging: debug, info, warn, error

Troubleshooting

No sessions found

# Force scan for new sessions
agentrace list --scan

# Check if agent directories exist
ls ~/.claude/projects/
ls ~/.codex/sessions/

Performance issues

# Limit query scope
agentrace list --last 7d --limit 20

# Use JSON for faster processing
agentrace stats --json | jq '.basic_stats'

Database issues

# Reset database (WARNING: deletes all data)
rm ~/.agentrace/agentrace.db
agentrace list --scan

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Adding Agent Support

To add support for a new agent, implement the AgentAdapter interface:

export class MyAgentAdapter implements AgentAdapter {
  name = 'my-agent';

  detect(): boolean {
    // Return true if agent is installed
  }

  findSessions(): string[] {
    // Return array of session file paths
  }

  parseSession(sessionPath: string): ParsedSession | null {
    // Parse session file into standard format
  }
}

Full adapter development guide

Related Projects

License

MIT License - see LICENSE file for details.

Built with ❤️ by the agentrace team Making AI agents observable, one session at a time.

🐛 Report Bug • 💡 Request Feature • 📚 Docs • 💬 Discussions

About

Local-first review desk for Claude Code and Codex sessions.

Topics

agent cli typescript ai sqlite mcp tracing observability

Resources

Readme

License

MIT license
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages