TraceGit

Core Git for AI agent executions.

TraceGit is a Git-like object database for agent runs. It stores every run as a content-addressed execution graph, then gives you refs, commits, packs, bundles, diff, replay, blame, bisect, fsck, and gc for agent behavior.

It is not an agent framework, hosted dashboard, eval platform, or automation wrapper. Those can integrate with TraceGit. The core project is lower-level: durable execution history for agents.

tracegit init
tracegit record -- python support_agent.py --ticket 123
tracegit show HEAD
tracegit diff HEAD~1 HEAD
tracegit replay HEAD --mock-io
tracegit policy check HEAD
tracegit bundle create HEAD -o incident.tracegit

Install

TraceGit is currently a Rust reference implementation.

cargo install --path .

For local development:

cargo run -- --help
cargo test
cargo run -- compat test fixtures

Why This Exists

Production agents are stateful, tool-using programs. A single run can include model calls, tool calls, retrieved documents, persistent memory, approvals, resource installation, browser/file actions, and external side effects.

Today that history is scattered across logs, callback traces, dashboards, screenshots, eval rows, and ad hoc JSON. That makes agent failures hard to reproduce, compare, verify, bisect, redact, or share.

TraceGit makes an agent run a first-class engineering artifact.

What You Can Do

Workflow	Command
Store a run	tracegit record -- <command>
Inspect a run	tracegit show HEAD
Inspect raw objects	tracegit cat-file -p <object>
Compare behavior	tracegit diff good bad
Replay without live APIs	tracegit replay bad --mock-io
Find first bad run	tracegit bisect-trace
Attribute a regression	tracegit blame-trace bad --against good
Inspect external writes	tracegit side-effects HEAD
Validate integrity	tracegit fsck
Compact history	tracegit gc
Share an incident	tracegit bundle create HEAD -o incident.tracegit

Quickstart

Record an agent run:

tracegit init
tracegit record -- python examples/python_agent.py
tracegit show HEAD

Compare two runs:

tracegit diff HEAD~1 HEAD

Export a reproducible incident:

tracegit policy check HEAD
tracegit bundle create HEAD -o incident.tracegit
tracegit bundle verify incident.tracegit

Validate the implementation and compatibility fixtures:

cargo test
cargo run -- compat test fixtures

Core Model

TraceGit uses Git-style storage semantics:

blob       prompt, model output, tool payload, retrieved document, file snapshot
event      typed execution step referencing blobs
edge       sequence, parent, causal, approval, side_effect
trace      event graph root, similar in spirit to a Git tree
commit     immutable run snapshot with parents and metadata
ref        mutable name pointing to a commit
pack       compact archive of reachable execution objects
bundle     portable pack plus manifest and redaction metadata

The command set has the same split:

plumbing    hash-object, cat-file, write-trace, commit-trace, update-ref, fsck
porcelain   record, log, show, diff, replay, blame-trace, bisect-trace, bundle

The Aha Moment

An agent denies a valid refund because an unverified memory item influenced the decision.

tracegit diff good bad

Changed inputs
  + memory mem_42
    authority: unverified
    value: "customer is high risk"

Path diff
  = retrieval_query refund_policy
  + memory_read mem_42
  ~ llm_call refund_decision output changed
  - tool_call refund.review
  + tool_call refund.deny

Policy
  FAIL TG003 unverified memory influenced irreversible decision

Then replay the same run without the suspect memory:

tracegit replay bad --without-memory mem_42

Original outcome: deny_refund
Replay outcome:   review_refund
Result:           behavior changed

This is the core value: the run is not a screenshot or dashboard link. It is a portable, verifiable execution object.

Who Uses It

Small teams use TraceGit to debug and share failing agent runs without building custom observability infrastructure.

Large companies use TraceGit to keep replayable, redaction-aware execution records for agent incidents, security review, policy enforcement, and regression analysis.

Framework maintainers use TraceGit bundles as reproducible bug reports.

Security teams use TraceGit to inspect whether an agent took an unsafe path: unverified memory, untrusted resource installation, PII sent to external models, or irreversible side effects without approval.

Unique Technical Primitives

TraceGit is designed to be technically deeper than a trace viewer:

• Execution Merkle DAG: event hashes roll up into a trace root.
• Replay manifest: recorded model/tool outputs become deterministic mocks.
• Trace slicing: export the causal subgraph behind a failure.
• Provenance proofs: prove one side effect descends from a specific path.
• Determinism score: measure how replayable a run actually is.
• Replay coverage: show which calls are mocked, live-only, or missing.
• Resource provenance: track repos, packages, MCP servers, skills, and binaries before execution.
• Side-effect ledger: record external writes, idempotency keys, approvals, and compensation metadata.
• Compatibility fixtures: make the format implementable outside the reference CLI.

Status

TraceGit is a reference MVP for the core storage layer. The object store, refs, history navigation, diff/replay flow, pack/bundle exchange, Merkle inclusion proofs, policy evidence, redaction manifests, Python emitter, OTel bridge, and compatibility fixtures are operational.

The project is still early. The next adoption work is ecosystem depth: dedicated framework adapters, richer replay engines, signing/attestation, remote object stores, and broader fixture coverage.

Implemented command surface

• init
• hash-object
• write-object
• write-blob
• write-event
• write-resource
• redact-object
• cat-file
• write-trace
• commit-trace
• update-ref
• symbolic-ref
• rev-parse
• ls-trace
• log --graph
• show
• diff
• replay --mock-io, default mocked replay, and --expect-no-divergence
• fsck
• index rebuild/verify
• pack-objects with explicit output or default .tracegit/packs output
• index-pack
• verify-pack
• unpack-objects
• bundle create/verify/import with explicit or default create output
• gc safe pack compaction, optional unreachable loose-object pruning, and SQLite index rebuild
• determinism
• replay-coverage
• replay-manifest
• side-effects
• prove
• slice with causal edge support
• blame-trace
• bisect-trace status plus start/good/bad/run
• policy check with optional revision defaulting to HEAD
• compat test
• otel import/export
• Python SDK JSONL emitter
• dependency-free Python callback adapter for LangChain-style frameworks
• first-class resource objects for verifiable repositories, packages, MCP servers, and artifacts
• built-in schema validation for core object types
• blob redaction writes distinct redacted objects and redaction manifests, with optional profile rules for drop, mask, hash, tokenize, and keep
• rebuildable SQLite index.sqlite for local object/commit/event/edge lookup
• pack index sidecars for pack verification
• replay manifest generation and command-backed divergence checks
• replay-manifest --attach creates immutable replay audit commits whose manifest objects are reachable through refs, packs, and bundles
• prove includes attached policy-result evidence when proving policy-covered events
• slice carries relevant policy-result evidence without exporting the original parent history
• diff --name-only and diff --json expose scriptable behavior comparisons
• fsck validation for loose objects, refs, packs, and pack indexes
• fsck --strict validates resource provenance objects and side-effect parentage
• fsck --strict --min-replay-coverage warns on low replayability for refs
• bundle manifests mark raw sensitive data from sensitivity labels or credential-like keys
• bundle create/verify can fail on raw sensitive data for safer exports
• policy check --write-results writes content-addressed policy result objects
• policy check --attach-results creates immutable policy audit commits whose result objects are reachable through refs, packs, and bundles
• built-in TG021 policy detects PII reads before external model calls
• built-in TG031 policy detects expensive paths missing budget override
• compat test validates expected object IDs, fixture ingest, fsck, pack/index, bundle import, replay manifests, policies, and diff behavior
• otel import/export bridges OTLP-style span JSON with TraceGit event graphs
• TraceGitCallbackHandler emits TraceGit JSONL from common callback method names

Format And Compatibility

TraceGit keeps the wire format explicit:

• JSON schemas live under schemas/jsonschema.
• Fixtures live under fixtures.
• tracegit compat test fixtures validates object IDs, fixture ingest, fsck, pack/index behavior, bundle import, replay manifests, policy checks, and diff behavior.

The intended contract is simple: other tools should be able to produce and consume TraceGit objects without embedding the reference CLI.

Build roadmap

Recommended build order:

1. Loose object store: hash-object, write-object, cat-file, fsck. Done.
2. Trace commits: write-trace, commit-trace, refs, log, show. Done.
3. Developer workflows: record, diff, replay --mock-io. Initial version done.
4. Novel execution primitives: determinism, replay-coverage, prove, slice. Initial version done.
5. History operations: blame-trace, bisect-trace. Initial version done.
6. Policy checks: built-in path policies for resource installation, unverified memory before irreversible side effects, and approval checks. Initial version done.
7. Exchange: packfiles, bundles, gc, compatibility fixtures. Initial pack, bundle, safe gc, and compat test support done.
8. Producers: Python SDK JSONL emitter, callback adapter, and OpenTelemetry span bridge. Initial version done.

Project Layout

src/                  Rust reference CLI and storage implementation
schemas/jsonschema/    Core object schemas
fixtures/              Compatibility fixtures
python/                Dependency-free Python emitter and callback adapter
examples/              Minimal producer examples
docs/                  Design notes and deeper project docs

License

Apache-2.0 is the recommended license so agent frameworks, observability tools, security scanners, and commercial platforms can embed the format and runtime without licensing friction.