agtrace 0.4.0

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 provides a unified timeline and analysis layer for fragmented AI agent logs. Use the CLI for instant visualization, or build custom monitoring tools with the SDK.

🌟 Core Value

  1. Universal Normalization: Converts diverse provider logs (Claude, Gemini, etc.) into a standard AgentEvent model.
  2. Schema-on-Read: Resilient to provider updates. No database migrations needed.
  3. Local-First: 100% offline. Privacy by design.
  4. Zero-Instrumentation: Automatically detects and watches logs from standard locations (~/.claude/projects, ~/.codex/sessions, ~/.gemini/tmp). No code changes required.

🚀 Quick Start (CLI)

The reference implementation of the agtrace platform.

npm install -g @lanegrid/agtrace
cd my-project
agtrace init      # initialize workspace (system data directory)
agtrace watch     # live dashboard

🤖 AI-Native Observability (MCP)

New in v0.4.0: Enable AI agents to query their own execution history.

agtrace exposes a Model Context Protocol (MCP) server that allows AI assistants like Claude Desktop to:

  • Browse session history and analyze failures
  • Search event payloads across thousands of sessions
  • Run diagnostic analysis (failures, loops, bottlenecks)
  • Debug agent behavior without manual CLI commands

Setup with Claude Desktop

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

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

After restarting Claude Desktop, ask questions like:

  • "Show me sessions from the last 2 hours that had failures"
  • "Search for all tool calls containing 'write_file'"
  • "Analyze the most recent session for performance issues"

Available MCP Tools

  • list_sessions - Browse session history with filtering
  • get_session_details - Get session overview, turns, or full details
  • analyze_session - Run diagnostic analysis (failures, loops)
  • search_events - Search event payloads across sessions
  • get_project_info - List all indexed projects

See also: Run agtrace mcp serve --help for details.

🛠️ 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.