Skip to main content
Glama

tracegit — Git for AI Agent Execution Traces

TraceGit CI Python 3.13 C++20 Native MCP Ready Coverage 97.55% Release v1.0.0 License: MIT

A small, local prototype for versioning and comparing AI agent tool-call traces. tracegit stores agent trajectories as commits in a SQLite database (with a SHA-256 Merkle root over steps), and offers log-, diff- and bisect-style commands built on an edit-distance step alignment (C++20 helper with a pure-Python fallback), a simple n-gram repeated-call detector, a rule-based CI regression gate, and a minimal stdio MCP server exposing these as tools.


Live Trajectory Diff, Bisect & Loop-Thrash Workbench

tracegit Live Workbench — Native C++20 Wagner–Fischer Step Alignment, First-Divergence Bisect & Loop-Thrash CI Gate


Related MCP server: horizon-ledger

Why Developers Install tracegit

  1. GitHub-PR-Style Step Alignment (diff + bisect): Powered by a native C++20 (clang++ -O3) Wagner–Fischer dynamic-programming aligner over 64-bit blake2b step hashes (MATCH, SUBSTITUTE, DELETE_BASE, INSERT_CANDIDATE), pinpointing the exact first divergent tool call between a working run and a failing run.

  2. Runaway Retry Loop (Loop-Thrash) Detector: Sliding-window n-gram (p = 1, 2, 3) cycle detector quantifies exact wasted steps and tokens when an agent gets stuck re-reading or re-grepping the same file.

  3. Content-Addressable SQLite + SHA-256 Merkle DAG: Stores normalized Claude Code JSONL, OpenAI/OpenRouter tool traces, and local Ollama runs in .tracegit/tracegit.db with tamper-evident SHA-256 step Merkle roots—100% local, zero cloud lock-in.

  4. Drop-In MCP Server for Claude Code & Cursor: Exposes 4 tools over stdio JSON-RPC 2.0 (tracegit_list_commits, tracegit_diff_commits, tracegit_bisect_failure, tracegit_evaluate_gate) so your coding agent can debug its own trajectory regressions.


Drop-In Claude Code / Cursor .mcp.json Setup (30 Seconds)

Add this to .mcp.json in your repository (or run tracegit mcp-stdio):

{
  "mcpServers": {
    "tracegit": {
      "command": "uvx",
      "args": ["tracegit", "mcp-stdio", "--db", ".tracegit/tracegit.db"]
    }
  }
}

Measured Benchmarks

Every metric below is reproducibly measured via CLI (tracegit ...) and pytest + Hypothesis (97.55% line coverage):

Benchmark

Measured Result

Engineering Guarantee

C++20 Wagner-Fischer Diff

Baseline 3aaf3dbc9382 (5 steps) vs Regressed bfba399ad924 (8 steps): 4 edit ops (50.0% match)

Exact C++20-vs-Python parity & metric symmetry (Hypothesis-verified)

bisect & Loop-Thrash

First divergence: step #2 (read_file); 2 wasted thrash steps (610 tok) detected

CI Gate BLOCKs regressed candidate (4 violations) & PASSes repaired bf3386185537

Live qwen3.5:4b Audit

6 multi-step coding/K8s/CI agent tasks: v1: 0.0% -> v2 Guarded: 100.0% verified (20.6% token cut)

Zero duplicate retries; mandatory read -> edit -> run_pytest completion (benchmarks/real_qwen_tracegit.json)


Scope & Limitations

  • Small codebase: ~1.5k lines of Python in src/ plus a ~180-line C++20 helper (csrc/tracegit_kernels.cpp, loaded via ctypes, with an equivalent pure-Python fallback). It is a prototype, not a production-hardened tool.

  • Diff/bisect results are on demo traces: the 5-step vs 8-step diff and the thrash/gate numbers above come from the hand-built traces seeded by tracegit demo, not from real-world agent logs.

  • The qwen3.5:4b audit is a small, self-constructed check: 6 hand-written tasks run against a small local 4B model via Ollama (single machine, no GPU cluster). The model only emits a JSON tool-call plan; tools are not executed, and "verified" means the plan passes a structural heuristic (read → edit → test on the target file). The v1 vs v2 difference reflects two prompt styles, and per-step token counts are derived from the model's total output tokens.

  • Simplified storage & alignment: step hashes are 64-bit blake2b digests of tool name, status and argument summary; alignment is plain O(n·m) Wagner–Fischer; loop detection is a sliding n-gram (n = 1–3) repeat counter. There is no remote sync, branching/merge semantics, or multi-user concurrency.

  • Integrations are minimal: the trace importers and MCP server (4 tools over stdio JSON-RPC) cover the formats exercised in the tests; they have not been validated against every Claude Code / Cursor / OpenAI trace variant.


Quickstart

# 1. Install Python 3.13 deps & compile C++20 alignment kernel
uv sync --python 3.13 --all-extras

# 2. Run strict lint, typing & Hypothesis test suite (97.55% coverage)
uv run ruff check src tests
uv run mypy src tests
uv run pytest --cov=tracegit --cov-report=term-missing --cov-fail-under=95

# 3. Run demo diff/gate + live Ollama trace audit
uv run tracegit demo
uv run tracegit eval-ollama

# 4. Build interactive Diff Workbench UI & launch server on :8100
cd ui && npm ci && npm run build && cd ..
uv run tracegit serve --host 127.0.0.1 --port 8100

Author & License

Designed and engineered by Nagarjuna Kamireddy (@nagarjunak-pixel). Released under the MIT License.


Author & Canonical Portfolio

Engineered by Nagarjuna Reddy Kamireddy (Principal / Lead AI Architect · Dubai, UAE).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      C
      maintenance
      Enables AI coding agents to retrieve cited git-history explanations for files and tickets, compile a Team Engineering Contract from repository artifacts, and follow guided Understand/Build workflows over MCP stdio. It lets clients such as Grok, Claude Code, Codex, Kiro, and Cursor share the same tools for evidence-backed repository understanding.
      1
      8 npm
      Apache 2.0
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI coding agents to read and manage a Git-native decision ledger, providing tools for querying decisions, evidence, cross-repository workspaces, validation, and commit tracing, all operating locally and without a cloud service.
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI coding agents to snapshot workspace states, binary-search recorded trajectory steps, rewind to a prior good step, and retrieve per-step diffs for autonomous regression debugging. It supports self-healing debugging workflows through MCP tools.
      3
      MIT
    • A
      license
      A
      quality
      A
      maintenance
      Lets AI agents query, search and read wiki pages and raw transcripts of past coding sessions, so they can look up prior decisions and fixes before redoing work. It also exposes linting, sync, export and dashboard tools over stdio, with path-traversal guards and no SDK dependency.
      6
      441 PyPI
      2
      MIT