trailhq/Trail-Code

Trail (formerly Graft) – a code‑base‑aware assistant helper

What it is – Trail is a TypeScript/Node.js CLI that builds a lightweight, local “graph” of a repository. The graph consists of markdown files that contain short, plain‑English summaries, key code excerpts (the crux), and typed links between concepts. By wiring this graph into coding agents such as Claude Code, Cursor, Codex, Gemini, or any LLM‑driven “coding assistant”, Trail lets the agent start a session already aware of the project’s structure, avoiding the costly “re‑exploration” phase that normally burns tokens, tool calls and latency.

Why it matters – Typical AI coding assistants treat every new task as if they have never seen the codebase before. They repeatedly grep, open files, and follow imports, which inflates token usage and slows down responses. Trail captures that understanding once, stores it locally, and injects it into the agent’s prompts. The README claims up to 4× cheaper and 3× faster runs with no loss of correctness, and even a measurable boost in accuracy on the SWE‑bench benchmark.

Key features

• One‑time graph build (graft init / trail init) that parses source files with tree‑sitter (no model, no API key) and optionally runs a language model once per file to generate human‑readable summaries.
• Markdown nodes: each node contains a summary, the most relevant code lines, source file hashes, and wikilink‑style typed edges (depends_on, uses, etc.).
• Local cache: the graft/ folder is added to .gitignore; only tiny wiring files (.claude/, AGENTS.md) are committed.
• Automatic freshness: before answering, the tool checks file hashes and rebuilds only changed parts, so the agent always sees the current working‑tree state, even with uncommitted edits.
• Agent integration: built‑in support for Claude Code (deep integration) and a generic MCP server hook for other agents.
• CLI utilities – graft ask, graft grep, graft map, graft viz, and graft check for searching, visualising, and validating the graph.
• Multi‑repo / monorepo support and a broad language coverage (23 languages, including TS/JS, Python, Go, Java, Rust, C/C++, etc.).
• Provider‑agnostic LLM usage – you can plug in OpenAI, Anthropic, OpenRouter, Groq, LiteLLM, or a local model for the summarisation step, using your own API key.

Typical workflow

1. Install the CLI (npm i -g @trailhq/trail or npm i -g @nanonets/graft).
2. Run trail init (or graft init) – select the agents you use, and the tool creates the graft/ directory and wiring files.
3. The next time you start a Claude Code session, Trail injects the relevant node summaries into the prompt, so the model can answer with far fewer tool calls.
4. After each coding session, any corrections you make are saved as “learnings” under .trail/learnings/. These become rules that the agent will apply automatically in future sessions.
5. Before a PR, trail check flags changes that conflict with existing learnings.

Benchmarks (as reported)

• Cold vs. Graft (Claude Code): 46 % fewer tool calls, 42 % fewer tokens, 60 % less latency, and a modest 12‑point lift in correctness on SWE‑bench (54 % → 66 %).
• Cost: $0.029 per task vs. $0.042 (≈ 32 % cheaper).

Who might use it – Development teams that rely heavily on LLM‑based coding assistants and want to reduce API costs, speed up responses, and capture institutional knowledge (team‑specific decisions, patterns, and fixes) directly in the repository.

---

TL;DR: Trail (formerly Graft) is a CLI that builds a human‑readable, markdown‑based knowledge graph of your codebase and wires it into AI coding agents, cutting down on repeated code‑exploration, saving tokens and time, and persisting team learnings for future sessions.