AgentTrace

AgentTrace is a local-first debugger, recorder, profiler, and observability platform for AI coding agents.

When an agent changes a repository, AgentTrace records the evidence needed to inspect what actually happened: model interactions where exposed, tool activity, shell commands, terminal output, file changes, Git activity, browser activity when explicitly exposed, MCP activity, subagents, context changes, retries, failures, timing/latency, token/cost samples, raw harness events, and stored artifacts.

AgentTrace does not force ten different runtimes into a fictional common API. Product-facing capability reports enumerate all supported adapter capability categories and mark each one native, inferred, derived, or unavailable. Researched upstream integration surfaces are not advertised as implemented until AgentTrace has a real collector/control path for them.

Status: pre-1.0. The schema-v2 protocol, local storage, artifacts, redaction profiles, ten initial adapters, CLI, replay engine, local API, adapter contract fixtures, benchmark suite, and Tauri/React inspector are implemented on the current development line. Compatibility may still change before the first stable release.

Telemetry truth model

Every normalized event carries provenance:

• native — emitted directly by the harness or a documented integration surface;
• inferred — observed from a side effect with an explicit inference rule;
• derived — deterministically calculated from recorded evidence;
• unavailable — not exposed reliably enough to claim.

AgentTrace never upgrades missing telemetry into a guess. Unknown structured records are preserved conservatively where safe so normalization can improve later without pretending an older collector observed something it did not.

Protocol schema v2 reserves browser.navigation, browser.action, browser.network, and browser.console, and adds optional typed latency_ns. Browser events are emitted only from verified browser evidence. Latency is kept separate from duration and remains absent unless the upstream surface exposes an explicit latency-like measurement; Claude Code's native duration_api_ms is one verified example.

Supported harnesses

The initial product registry contains:

• OpenAI Codex
• Claude Code
• OpenCode
• Pi
• Gemini CLI
• Aider
• Goose
• Cline
• Roo Code
• Continue

Integration modes differ by harness. Structured streams are preferred where implemented; imports and conservative process wrapping are used where that is the strongest implemented path. See docs/harnesses.md for the evidence-backed matrix and researched follow-on surfaces.

Build

The core workspace requires Rust 1.85 or newer.

cargo build --workspace

Install the command-line binaries directly from the repository:

cargo install --path crates/agenttrace-cli
cargo install --path crates/agenttrace-server

agenttrace serve is the primary local-API workflow. The standalone agenttrace-server binary remains available for service-oriented deployments and packaging.

Quick start

agenttrace harnesses
agenttrace capabilities codex
agenttrace doctor
agenttrace run --harness codex -- codex exec "fix the failing test"
agenttrace inspect <run-id>
agenttrace export <run-id> --output trace.jsonl
agenttrace compare <left-run-id> <right-run-id>

Export re-applies the active redaction policy. Raw-source payloads are omitted by default; include raw source explicitly only when needed:

agenttrace export <run-id> --raw --output trace-with-raw.jsonl

Import supported existing traces/sessions:

agenttrace import --harness codex ./codex-run.jsonl

The default database is .agenttrace/agenttrace.db. Use global --db to point commands at another database.

Custom redaction

Built-in safe rules are always enabled. Add organization-specific patterns, JSON keys, and sensitive path fragments with an additive JSON profile:

agenttrace --redaction-config ./agenttrace-redaction.json \
  run --harness codex -- codex exec "fix the failing test"

{
  "patterns": [
    {"name": "internal_ticket", "regex": "AT-[0-9]{6}"}
  ],
  "sensitive_json_keys": ["customer_reference"],
  "sensitive_path_fragments": [".agenttrace-private"]
}

The same profile can be used for inspection/export/API serving so newer rules can be re-applied to stored events. See docs/cli.md and docs/security.md.

Replay

Replay is deliberately narrower than “rerun the agent.” Only recorded shell.command events are eligible, and replay is dry-run-first:

agenttrace replay <run-id> --repo /path/to/repository

The dry-run plan attaches conservative risk tags such as filesystem_mutation, git_mutation, network_access, external_service, and credential_sensitive when recognizable. These tags are visibility for the exact command being reviewed; they are not a claim of OS-level isolation.

Execution requires --execute plus an exact command or sequence allowlist:

agenttrace replay <run-id> \
  --repo /path/to/repository \
  --execute \
  --allow "cargo test"

The exact approval applies only to that recorded command or sequence. Replay runs in a temporary detached Git worktree with a scrubbed environment and a per-command timeout. This protects normal repository state, but it is not an operating-system sandbox. See docs/replay.md.

Local API

agenttrace --db .agenttrace/agenttrace.db serve

The standalone binary exposes the same server library:

agenttrace-server --db .agenttrace/agenttrace.db

The default bind is 127.0.0.1:4319. Non-loopback binding is rejected unless --allow-remote is explicit. Event/export endpoints re-apply the active redaction policy and hide raw source by default.

Current endpoints include health, harness detection, complete capability evidence, run listing/detail, event retrieval, JSONL export, and deterministic run statistics.

Storage and artifacts

SQLite is the local system of record. Event ingestion is incremental, WAL-backed, indexed, migration-driven, and zstd-compresses sufficiently large event payloads.

Run-scoped artifacts can be stored with optional event linkage, SHA-256 content identity, original size, media type, and compression metadata. Artifact bytes remain local and are not automatically uploaded or included in sanitized JSONL exports.

Desktop inspector

apps/desktop contains a Tauri v2 + React DevTools-style inspector with:

• run history and live active-run refresh;
• native file-picker trace/session import through the real adapter registry;
• searchable/filterable timeline, including schema-v2 browser.* events when actually present;
• complete capability evidence indicators;
• observed-only token, explicit API-latency, event-distribution, and duration charts;
• payload, raw, execution, terminal, diff, and relations inspectors;
• unified and side-by-side diff rendering only when actual patch text is exposed;
• span/subagent/context views only when corresponding trace evidence exists;
• deterministic run comparison;
• sanitized JSONL export;
• artifact metadata;
• System, Dark, and Light themes;
• observed usage/cost/retry/error fields without fake precision.

cd apps/desktop
npm install
npm run tauri dev

Set AGENTTRACE_DB to inspect an existing CLI database and optionally AGENTTRACE_REDACTION_CONFIG for an additive desktop redaction profile. The Tauri crate is isolated from the core workspace so its newer runtime MSRV does not raise the core MSRV. See docs/desktop.md.

Architecture

The Rust core is split into small crates for the protocol, adapter contract, process supervision, collection, storage/artifacts, redaction, adapter registry, replay, CLI, local API, cross-adapter contracts, and benchmarks. Harness adapters live under crates/adapters/.

Key documents:

• docs/architecture.md
• docs/trace-format.md
• docs/adapter-authoring.md
• docs/harnesses.md
• docs/research/reference-adapters.md
• docs/security.md
• docs/testing.md
• SECURITY.md

Performance benchmarks

The deterministic large-trace suite expands fixtures/benchmarks/large-trace.json into 100,000 schema-v2 events and measures ingestion, full-trace loading, JSONL export, Rust-heap deltas, and Codex normalization throughput:

cargo run --release -p agenttrace-benchmarks

A smaller storage microbenchmark is also available:

cargo run --release -p agenttrace-storage --example ingest_benchmark -- 10000

Benchmarks print measurements for the current machine; AgentTrace does not hard-code performance claims from one environment.

Development

cargo fmt --all -- --check
cargo clippy --workspace --all-targets --all-features -- -D warnings
cargo test --workspace --all-features
cargo check --workspace --all-targets

CI is configured to run core checks across Linux/macOS/Windows, build the React frontend, check the Tauri shell on Windows, and run dependency auditing. Tagged v* releases package agenttrace and agenttrace-server for Linux, macOS, and Windows with SHA-256 checksum files.

See CONTRIBUTING.md before changing adapters or telemetry claims. A full local validation sequence is documented in docs/testing.md.

Security and privacy

Redaction is applied before normal event persistence and again on sharing/read surfaces; custom profiles can only add protections. Environment capture is deny-by-default, the API is loopback-first, replay is exact-allowlisted, and no automatic cloud upload exists. Trace databases, artifacts, exports, and screenshots can still contain sensitive engineering data.

Application-level encrypted storage is not currently implemented; see docs/security.md.

License

Apache-2.0. See LICENSE.