Trail-Code

<div align="center"> <picture> <source media="(prefers-color-scheme: dark)" srcset="assets/trail-code-banner-dark.png"> <img src="assets/trail-code-banner.png" alt="Trail-code (previously graft), by Trail. A map of a codebase, with one team decision pinned to it: keep retries at 4." width="100%"/> </picture>

Turbocharge Claude Code, Cursor, Codex, Gemini & every coding agent: faster, cheaper, with contextual understanding specific to your codebase.

<a href="https://trendshift.io/repositories/92209?utm_source=trendshift-badge&utm_medium=badge&utm_campaign=badge-trendshift-92209" target="_blank" rel="noopener noreferrer"><img src="https://trendshift.io/api/badge/trendshift/repositories/92209/daily?language=TypeScript" alt="trailhq/Graft | Trendshift" width="250" height="55"/></a>

<p> <a href="https://github.com/NanoNets/Graft"><img src="https://img.shields.io/github/stars/NanoNets/Graft?style=for-the-badge&logo=github&logoColor=white&label=Star%20on%20GitHub&color=FFC83D" /></a> <a href="https://trailhq.com/graft"><img src="https://img.shields.io/badge/website-trailhq.com/graft-E5484D?style=for-the-badge" /></a> <a href="https://discord.gg/zxmKweAA29"><img src="https://img.shields.io/badge/Discord-join-5865F2?style=for-the-badge&logo=discord&logoColor=white" /></a> <a href="https://www.npmjs.com/package/@nanonets/graft"><img src="https://img.shields.io/npm/v/%40nanonets%2Fgraft?style=for-the-badge&logo=npm&logoColor=white&label=npm" /></a> <a href="https://www.npmjs.com/package/@nanonets/graft"><img src="https://img.shields.io/npm/dm/%40nanonets%2Fgraft?style=for-the-badge&logo=npm&logoColor=white&label=downloads" /></a> <a href="https://nodejs.org"><img src="https://img.shields.io/node/v/%40nanonets%2Fgraft?style=for-the-badge&logo=nodedotjs&logoColor=white" /></a> <img src="https://img.shields.io/badge/TypeScript-strict-3178C6?style=for-the-badge&logo=typescript&logoColor=white" /> <img src="https://img.shields.io/badge/License-MIT-20C997?style=for-the-badge" /> <a href="TELEMETRY.md"><img src="https://img.shields.io/badge/telemetry-anonymous%2C%20opt--out-546FFF?style=for-the-badge" /></a> <a href="https://scorecard.dev/viewer/?uri=github.com/NanoNets/Graft"><img src="https://img.shields.io/ossf-scorecard/github.com/NanoNets/Graft?style=for-the-badge&label=openssf%20scorecard" /></a> <a href="https://app.trailhq.com/get-started?step=repo"><img src="https://img.shields.io/badge/Trail-try%20it-E5484D?style=for-the-badge&logoColor=white" /></a> </p>

Up to 4× cheaper and 3× faster, with better or no loss of correctness.

| Metric | Cold Claude Code | Claude Code with graft | |---|---|---| | Tool-call reduction | Baseline | +46% | | Token savings | Baseline | +42% | | Time savings | Baseline | +60% | | Correctness | 54% | 66% (+12 pts) |

</div> <p align="center"> <b>Stop repeating yourself to your coding agent.</b><br/> You correct it, and by the next session it has forgotten. Trail manages your CLAUDE.md and AGENTS.md so it doesn't. </p> <p align="center"> &bull;&nbsp; Every correction you make becomes a rule your agent keeps.<br/> &bull;&nbsp; The ones that can't break get a hook that blocks it, not a note it ignores. </p> <p align="center"> <a href="https://app.trailhq.com/get-started?step=repo"><img src="https://img.shields.io/badge/Try%20it%20on%20your%20repo%20%E2%86%92-E5484D?style=for-the-badge" alt="Try it on your repo" height="34"/></a> </p> <p align="center"> <img src="assets/graft-comparison-demo.gif" alt="Side-by-side comparison of a coding agent working with and without graft" width="820"/> </p>

---

Contents

• Trail quick start: learnings your agent leaves for the next session, and your team's
• Quick start
• The problem
• What Graft does
• Benchmark
• SWE-bench Verified
• How the graph gets built
• Supported languages
• What's in a node
• What runs where
• Agent integration — MCP server · Claude Code (deep integration)
• CLI
• Search & orient (graft grep / graft map)
• Monorepos & multi-repo folders
• Visualize it (graft viz)
• Tested on your popular repos
• Development
• License

---

Trail quick start

npm install -g @trailhq/trail
trail init
claude

Install once. trail init asks which agents your team uses, builds the code map and wires up Claude Code. Then work the way you always do.

When a session works something out, your agent saves a learning: what it decided, what it ruled out, and what to watch out for. It goes in the repo's .trail/learnings/, and you commit it with the change. The next session on that code, yours or a teammate's, gets it back before it starts digging, and ends with a line saying what it saved, like 📝 Started from Anirudh's learning · saved ~27k tokens. Teammates' Claude reads the learnings even before they install trail, and learnings on a teammate's pushed branch show up before it merges, along with any overlap with your work.

Before a PR, trail check compares your change with what the team has learned and flags anything that goes against it. It runs on your machine; nothing to sign in to.

When you want the team's view across repos, your agent offers a link at the end of a reply. Sign in, create a workspace, tick the repos it gets, and invite your team with a link. The team page shows who is learning what, how often learnings are reused, and where work overlaps.

Trying this branch before @trailhq/trail is published:

git clone -b feat/trail-cloud https://github.com/trailhq/Graft.git trail && cd trail
npm install && npm run build && node scripts/pack-trail.mjs
npm install -g ./build/trail

---

Quick start

npm install -g @nanonets/graft   # install the CLI, once
graft init                       # build the graph + wire it into Claude Code

That is the whole setup. graft init asks which of your coding agents to wire up, builds graft/ from your code, and drops a statusline and hooks into .claude/, so from the next session on Graft rides along in Claude Code: it pulls the matching nodes into each prompt and rebuilds the graph in the background after every turn. No daemon, no re-indexing to remember, nothing to run or maintain by default — the graph is just files.

Nothing is written until you pick. Run graft init --dry-run to see every file it would touch first, or graft init --agents claude to skip the prompt and wire Claude Code alone.

graft build adds graft/ to your .gitignore automatically — the graph is a local, regenerable cache (like node_modules), not something you commit. What you share is the wiring init dropped into .claude/; each teammate runs graft build to generate their own graph:

git add .claude && git commit -m "wire in graft"

Prefer not to install globally? npx @nanonets/graft init works the same way.

<p align="center"> <img src="assets/graft-terminal.png" alt="Two commands — npm install and graft init — then Graft rides along in a Claude Code session, statusline synced" width="820"/> </p>

---

The problem

Every task, your coding agent starts blind. Before it changes anything, it re-explores the repo: grep a term, open a file, follow an import, back out, try again. It is rebuilding a picture of a codebase it mapped an hour ago and threw away. That rediscovery burns most of a run's tool calls, tokens, and latency, and it is pure overhead:

• Repeated. Every task pays the exploration cost again, from zero.
• Discarded. Whatever the agent figured out dies with the session.
• Unshared. The next teammate, and their agent, start from scratch too.

Humans onboard to a codebase once. Agents onboard every single time.

<p align="center"> <img src="assets/graft-site-act-demo.gif" alt="A no-map agent's exploration trail wandering file to file before it finds what it needs" width="820"/> </p>

---

What Graft does

Graft builds that understanding once and writes it into your repo as a folder of linked markdown files, one node per system, API, or concept.

• Real explanations, not a list of symbols. Each node says, in plain English, what a part of the system does and how it connects to the rest, the way a senior engineer would explain it. That is the part an agent actually needs so it can skip the exploration. It is not a dump of function names.
• A real graph you can read. No embeddings, no similarity search, no index to keep warm. The graph is a set of linked files your agent opens, greps, and follows, exactly the way it reads any other file in the repo.
• A local cache, not a committed artifact. graft build writes graft/ and adds it to .gitignore — it's a regenerable local cache, like node_modules. What you commit is the small wiring graft init drops in (.claude/, AGENTS.md, the MCP config); each teammate runs graft build to generate their own graph. No database, no server, no setup.
• Always fresh, automatically. Every query rebuilds the graph against the working tree first — structural, $0, ~3ms when nothing moved — so ask/grep/callers/skeleton/map describe the code as it is right now, including uncommitted edits. graft check is a local freshness signal; there's no stale index to babysit.
• Your provider, your key, your model. Summaries are written by any provider you choose — OpenAI, Anthropic (native), OpenRouter, Fireworks, Groq, OrcaRouter, a LiteLLM proxy, or a local model — under your own key. The structural code graph (graft build, graft check) is deterministic tree-sitter and never calls a model at all.

<p align="center"> <picture> <source media="(prefers-color-scheme: dark)" srcset="assets/graft-cold-vs-graft-dark.png"> <img src="assets/graft-cold-vs-graft.png" alt="The same task, 'fix the auth bug', run two ways. A cold Claude Code session re-reads the repo and wanders file to file; Claude Code + graft loads its map once and rides the hooks to one clean pass. With Graft: 46% fewer tool calls, 42% fewer tokens, 60% less time, +22% more SWE-bench instances resolved." width="880"/> </picture> </p>

---

Benchmark

An agent that reads the graph should be cheaper and faster without getting more answers wrong. That's the whole claim, so we measured it instead of asserting it.

The harness ran three variants of the same Claude Sonnet 5 agent with the same file tools: cold (explores from zero), Graft (a graft ask --source bundle pushed up front), and pull (graft_find_code/graft_file_api tools, nothing injected — context paid for only when asked). An Opus 4.8 judge scored correctness with a required-keyword floor, so a fast-but-wrong answer couldn't win by being fast. Cost is cache-aware: reads ≈0.1×, writes 1.25×, the billing model agents actually run under.

162 runs, two repos (graft itself and a real Node/Express auth service), 3 trials each, tasks split between single-file and multi-file questions.

| Metric (mean/task) | Cold Claude Code | Claude Code with graft | |---|---|---| | Cost savings ($) | 0.0429 | 0.0292 (+32%) | | Token savings | 8,070 | 4,650 (+42%) | | Tool-call savings | 4.2 | 2.3 (+46%) | | Latency savings (s) | 39.8 | 15.8 (+60%) | | Correctness | 93% | 93% (equal) |

Graft never answered worse than cold, on any corpus. The pull variant gave up most of that speed for something bigger: correctness jumped to 98%, +5 points over cold, the strongest single result in the sweep. Push when speed is what you need; pull when being right matters more.

---

S