agtrace

The Observability Platform for AI Agents.

Local-first OpenTelemetry for Claude, Codex, and Gemini.

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.

🚀 Quick Start (CLI)

The reference implementation of the agtrace platform.

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

🛠️ Building with the SDK

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

[dependencies]
agtrace-sdk = "0.2"

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

• Why agtrace? - Understanding the problem and solution
• Getting Started - Detailed installation and usage guide
• Architecture - Platform design and principles
• SDK Documentation - Building custom tools
• Full Documentation - Commands, FAQs, and more

🔌 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.