Trail-Code (Graft) — The Self-Learning Context Layer for Coding Agents

TL;DR

Trail-Code (previously Graft) is an open-source MIT-licensed CLI that augments third-party coding agents (Claude Code, Cursor, Codex, Gemini) with two local artifacts: a graft map — a tree-sitter-parsed graph of every file, function, and caller — plus learnings, short markdown files capturing per-repo decisions (“keep retries at 4”), personal setup notes, and team conventions saved from past agent conversations. The map is pointed at agent prompts via MCP tools and Claude Code hooks; learnings travel through git. Reported SWE-Bench Verified on 50 instances: Claude Sonnet 5 solved 33/50 (66%) with the map vs 27/50 (54%) baseline, at 23% fewer tokens, 32% less wall-clock, and 25% fewer tool calls. Notable for Luma as a concrete production instance of the harness-as-first-class-capability thesis — the “harness > model” claim from Benchmarking Coding Agents on Databricks' Multi-Million Line Codebase rendered as an installable per-repo tool.

Key claims

The system has two parts: (1) a tree-sitter-built graph of every file, function, and caller across 24 languages, refreshed incrementally against the working tree on each query — no model, no network, no embeddings; and (2) learnings — markdown files in .trail/learnings/ committed with code, plus personal learnings in ~/.trail/ kept local [README §How it works].
SWE-Bench Verified on 50 instances with Claude Sonnet 5 on both arms, same Docker images, same turn limits, official swebench 4.1.0 grader on native x86_64: 33/50 solved (66%) with the graft map vs 27/50 (54%) without, +12 pts; 109.4M vs 142.0M tokens (23% fewer); $42.43 vs$ 52.34 cost (19% lower); 1,031 vs 1,370 tool calls (25% fewer); 8,922s vs 13,094s wall-clock (32% less) [README §SWE-Bench Verified].
Controlled 162-run sweep across two repos (3 trials, mixed single/multi-file tasks) under an Opus 4.8 judge with required-keyword floor and cache-aware cost model (reads ≈0.1×, writes 1.25×): the push variant (bundle up front) cut mean per-task cost from $0.0429 to$ 0.0292 (32% lower), uncached input tokens from 8,070 to 4,650 (42% fewer), tool calls from 4.2 to 2.3 (46% fewer), latency from 39.8s to 15.8s (60% less), with correctness tied at 93% [README §Benchmark].
A pull variant (expose trail_find_code + trail_file_api MCP tools so context is paid for only when queried) is reported to never regress correctness vs cold on any corpus and to lift correctness from 93% → 98% on the sweep’s two repos — 5 pts above cold [README §Benchmark].
On a 15-task Pocketbase benchmark (10 developer questions + 5 real merged PRs re-implemented from the base commit): $11.02 vs$ 13.91 (-21% cost), 1,762s vs 2,044s (-14% latency), and 5/5 PRs reproduced touching the same files the maintainers did; the hardest cross-file question (“how does auth work across OAuth2 providers”) dropped from $2.19 to$ 0.84 — a 2.6× cost reduction concentrated on multi-file reasoning [README §Tested on popular repos].
Learnings are plain markdown with frontmatter (title, author, date, cost: { tokens: N }, touches: [files]) — the touches field is how the next session on client.go finds Maya’s learning; the cost field records what the saving session spent, which is how “saved ~27k tokens” is computed (session cost minus read cost) [README §A learning is a file].
A pre-PR trail check command runs changes against learnings and flags conflicts with the author’s name and date (“Maya · Oct 9: Keep defaultRetryMax = 4”) so an agent is forced to override and explain in the commit rather than silently undo a prior decision [README §One decision, two teammates].
trail init seeds learnings on day one from (a) the user’s own prompts in past Claude Code transcripts that appeared in ≥2 sessions (read under the user’s own Claude login, scrubbed of secrets), and (b) PR review comments on the last 50 merged PRs via gh under the user’s GitHub login [README §Your agent does the saving, §What stays on your machine].
Branch-level conflict detection: right after an edit, the hook reads other locally-checked-out branches and warns if a teammate’s pushed-but-unmerged branch is also modifying the same symbol with the opposite direction (Maya lowering defaultRetryMax, Kumar raising it) [README §One decision, two teammates].

Method

The graft map is produced by trail init, which walks the repository with tree-sitter and emits a graph of symbols (files, functions, class methods) connected by call edges. The index lives in graft/ (gitignored like node_modules) and self-refreshes on each query by diffing the working tree, so answers reflect uncommitted edits. It is wired into agents three ways: Claude Code via statusline + prompt-time hooks that inject matching files and functions ahead of each prompt and compute a “blast radius” (reverse-call closure) after each edit; Cursor, Codex, and other MCP-compatible agents via trail_find_code and trail_file_api tools plus instruction-file entries. There is no embedding store, no vector index, no daemon — everything is files and the graft map is a derived cache.

Learnings are the second artifact. When the user tells the agent “save this as a learning,” it writes a short markdown file to .trail/learnings/ (repo-scoped, committed) or ~/.trail/ (personal, never committed). The agent never saves on its own and never edits an existing learning — on conflict it writes a new one and names the override in the commit message. Before each session, learnings matching the current task are injected; before a PR, trail check compares the diff against all repo-level learnings and flags conflicts. The trail team command surfaces the last 7 days of team learnings and overlap detection (where two developers are modifying the same file across branches). An optional Trail workspace layer is sketched for cross-repo team view but had not shipped at filing time.

Results

SWE-Bench Verified (50 instances, Claude Sonnet 5): +12 pts correctness (54% → 66%), −23% tokens, −32% wall-clock, −25% tool calls, −19% cost. Case-level pattern: baseline patches 1 file of a multi-file fix (django-11532: 1/5 files, 18 regressions; django-16263: 1/4 files, 102/103 tests) — the graft map’s reverse-call closure finds the other files [README §SWE-Bench Verified].
Controlled 162-run sweep (push variant): −32% cost, −42% uncached input tokens, −46% tool calls, −60% latency at equal 93% correctness [README §Benchmark].
Controlled 162-run sweep (pull variant): correctness 93% → 98%, no corpus regressions, with trade-off: smaller speed gain than push [README §Benchmark].
PocketBase (Claude Opus, 15 tasks): −21% cost, −14% wall-clock, 5/5 PRs reproduced touching the same files as the merged PRs; 2.6× cheaper on the single hardest cross-file question [README §Tested on popular repos].
Reported teammate-session scenario (hashicorp/go-retryablehttp): second developer’s agent answered Maya’s open question in 11s / $0.10 using her saved learning instead of re-exploring; trail check caught Kumar’s defaultRetryMax = 4 → 10 override before PR and quoted Maya’s reasoning [README §One decision, two teammates].

Why it’s interesting

Trail-Code is the clearest production datapoint on file for the “harness is a first-class capability” thesis that Benchmarking Coding Agents on Databricks' Multi-Million Line Codebase established empirically (“per-token pricing is a poor cost proxy; harness choice moves per-task cost by >2× at fixed model+quality”) and that AutoDesign: Meta-Harness Optimization for Long-Horizon Agentic Design formalized (“learned meta-harness optimizer” improves 7 code-agent + model pairs by +12.4 pts on a visual-design deliverable). Trail-Code is the same thesis but at the opposite end of the automation spectrum: a hand-engineered, model-free, per-repo cache layer that nevertheless matches the reported magnitude of effect from Databricks’ empirical cost-per-task finding and the SWE-Bench Verified lift from recent harness-focused agentic-SWE work (comparable to the Pi vs Claude Code gap on the same benchmark).

The learnings substrate is a concrete engineering realization of what Agentic Context Management: Solving Agent Memory and Cost by Treating Them as Lifecycle and Architecture Problems‘s Agentic Context Management framework prescribes: external-text + experiential + evolution-heavy memory with explicit compacting & consolidation (one learning = one decision + what-was-tried + watch-outs) and explicit scoping (personal / repo / team) baked into the file layout. Where ACM proposes the discipline, Trail-Code ships a working git-native implementation. It also sits adjacent to Training-Free Group Relative Policy Optimization‘s experience-library pattern — Trail’s touches field is the file-system analog of TF-GRPO’s natural-language experience library, with the key difference that Trail scales via per-file matching rather than full-library retrieval, which is why it works on a repo of thousands of files without an embedding index.