agtrace 0.4.1

The official CLI for agtrace, built on top of agtrace-sdk. Visualize and analyze AI agent execution traces.
Documentation

npm crates.io

agtrace watch demo

agtrace is an observability platform for AI agent execution traces. Local-first, privacy-preserving, and zero-instrumentation.

Two Ways to Use agtrace

1. 🔍 Live Monitoring with watch

Real-time TUI dashboard for agent sessions. Like top + tail -f for AI agents.

  • 100% local and offline — Privacy by design, no cloud dependencies
  • Auto-discovery — Finds logs from Claude Code, Codex, and Gemini automatically
  • Zero instrumentation — No code changes or configuration needed
  • Universal timeline — Unified view across all providers

2. 🤖 Agent Self-Reflection via MCP

Connects to AI coding assistants via Model Context Protocol, enabling agents to query their own execution history.

  • Query past sessions — "Show me sessions with failures in the last hour"
  • Search across traces — Find specific tool calls, events, or patterns
  • Analyze performance — Detect loops, failures, and bottlenecks
  • Debug behavior — Inspect reasoning chains and tool usage

Supported MCP clients: Claude Code, Codex (OpenAI), Claude Desktop Note: Gemini CLI support is planned (requires Content-Length framing implementation)

🚀 Quick Start

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

🔌 MCP Integration

Enable agent self-reflection in your AI coding assistant:

Claude Code:

claude code 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"]
    }
  }
}

Example queries after setup:

  • "Show sessions from the last hour with failures"
  • "Search for tool calls containing 'write_file'"
  • "Analyze the most recent session for performance issues"

For detailed setup instructions and troubleshooting, see the MCP Integration Guide.

🛠️ Building with the SDK

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

[dependencies]
agtrace-sdk = "0.3"

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 also: SDK Documentation | Examples | SDK README

📚 Documentation

🔌 Supported Providers

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

📦 Architecture

graph TD
    CLI[agtrace-cli] --> SDK[agtrace-sdk]
    YourApp[Your Tool] --> SDK
    SDK --> Core[Core Engine & Providers]
  • Core SDK: agtrace-sdk, agtrace-engine, agtrace-providers
  • Applications: agtrace-cli (Reference Implementation)

License

Dual-licensed under the MIT and Apache 2.0 licenses.