agtrace 0.5.2

agtrace monitors AI agent sessions in real-time and lets agents query their own execution history via MCP.

• Zero instrumentation — Auto-discovers provider logs
• 100% local — Privacy by design, no cloud dependencies
• Universal timeline — Unified view across all providers

Quick Start

npm install -g @lanegrid/agtrace
cd my-project
agtrace init      # Initialize workspace (one-time setup)
agtrace watch     # Launch live dashboard

MCP: Let Agents Query Their Own History

Connect your AI assistant to search past sessions via Model Context Protocol:

Claude Code:

claude mcp add agtrace -- agtrace mcp serve

Codex (OpenAI):

codex mcp add agtrace -- agtrace mcp serve

Claude Desktop: Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "agtrace": {
      "command": "agtrace",
      "args": ["mcp", "serve"]
    }
  }
}

Your agent can now:

• Search past sessions for tool calls and errors
• Retrieve tool calls and results from previous work
• Analyze failure patterns

Example queries:

• "Show me sessions with failures in the last hour"
• "Search for tool calls that modified the database schema"
• "Analyze the most recent session for performance issues"

For detailed setup and examples, see the MCP Integration Guide.

CLI Commands

Debug and inspect agent behavior manually:

agtrace watch              # Live TUI dashboard
agtrace session list       # Browse session history
agtrace lab grep "error"   # Search across sessions

Building with the SDK

Embed agent observability into your own tools (vital-checkers, IDE plugins, dashboards).

[dependencies]
agtrace-sdk = "0.5"

use agtrace_sdk::{Client, Lens, types::SessionFilter};

let client = Client::connect_default().await?;
let sessions = client.sessions().list(SessionFilter::all())?;
if let Some(summary) = sessions.first() {
    let handle = client.sessions().get(&summary.id)?;
    let report = handle.analyze()?.through(Lens::Failures).report()?;
    println!("Health: {}/100", report.score);
}

See SDK Documentation, Examples, and SDK README.

Supported Providers

• Claude Code (Anthropic)
• Codex (OpenAI)
• Gemini (Google)

Documentation

• Getting Started - Detailed installation and usage guide
• MCP Integration - Connect agents to their execution history
• Architecture - Platform design and principles
• Why agtrace? - Understanding the problem and solution
• Full Documentation - Commands, FAQs, and more

License

Dual-licensed under the MIT and Apache 2.0 licenses.