agents-traces

Append-only JSONL session traces. Assemble rebuilds the chat payload for one request.
Cost/token metrics and session inspect tools. Shared across Cursor, Claude Code, Antigravity, and Zed.

Quickstart

1-Step Setup

pip install agents-traces && agents-traces init

Scaffolds ~/.agents/traces/, autowires MCP configurations into your installed IDEs, and registers assistant skills.

2. Agent-Driven Setup (Zero Friction)

[!TIP] 🤖 Agent-Driven Setup (Zero Friction):
Simply tell your coding agent: "Install and set up agents-traces for me."
The agent installs the package, runs agents-traces init, and automatically diagnoses tool failures using get_recent_errors.

Source checkouts can also be installed and managed using vand.

Why .agents/traces?

Existing observability platforms (LangSmith, Langfuse, Arize Phoenix) require:

• Heavy Docker stacks (PostgreSQL, ClickHouse, Redis, webservers)
• Cloud accounts, API keys, network latency, and SaaS subscriptions
• Intrusive SDK wrappers that add execution overhead to fast agent loops

agents-traces replaces 500 MB containers with lightweight, append-only JSON lines (~/.agents/traces/):

• Sub-0.05ms Append Speed: Pure atomic file appends with zero lock contention.
• Zero Daemon / Zero Database: Plain daily JSONL logs (~/.agents/traces/YYYY-MM-DD.jsonl).
• Autonomous Self-Healing: Exposes MCP tools (get_last_session_trace, get_recent_errors) so agents can inspect their own errors and fix failing loops.
• Rich Terminal Timeline: LangSmith-style visual timeline directly in your terminal.

Architecture & Flow

 ┌─────────────────────────────────────────────────────────────┐
 │                     CODING AGENT / IDE                      │
 │    Cursor · Antigravity · Claude Code · Custom Agents       │
 └──────────────────────────────┬──────────────────────────────┘
                                │  Append in <0.05ms
                                ▼
 ┌─────────────────────────────────────────────────────────────┐
 │                  LOCAL DAILY TRACE STORE                    │
 │          ~/.agents/traces/YYYY-MM-DD.jsonl                  │
 └──────────────┬───────────────────────────────┬──────────────┘
                │                               │
                ▼                               ▼
 ┌─────────────────────────────┐ ┌─────────────────────────────┐
 │     TERMINAL TIMELINE       │ │     MCP SELF-HEALING        │
 │  agents-traces stats        │ │  get_last_session_trace     │
 │  agents-traces inspect      │ │  get_recent_errors          │
 │  agents-traces tail -f      │ │  Autonomous Loop Repair     │
 └─────────────────────────────┘ └─────────────────────────────┘

CLI Reference

MCP Tools Reference

Supported Ecosystem

• Claude Code: Bound via MCP server and .agents/skills/trace-inspect.
• Google Antigravity: Integrated via .gemini/config rules and agents-traces MCP.
• Cursor: Automatically configures .cursor/mcp.json and agent rules.
• Zed: Configures context_servers and mirrors assistant skills.
• VS Code / Windsurf: Autowires Cline / Roo-Code MCP configuration.

Open ABI Specification

Detailed architectural specifications live in abi/:

• abi/WHY.md — Rationale & why lightweight JSONL beats heavy Docker stacks.
• abi/LAYOUT.md — Daily partition taxonomy in ~/.agents/traces/.
• abi/SCHEMA.md — Full JSON schema for trace events and spans.
• abi/MCP.md — Tool surface definitions and schemas.
• abi/CLI.md — Terminal commands and formatting specification.

Testing & Verification

Run the test suite across all engines:

python tests/run_all_tests.py

License

MIT License. See LICENSE for details.