Trail-code (formerly Graft) CLI
Graft
A CLI that builds a map of your repo's code and keeps team decisions in .trail, so Claude Code, Cursor and Codex stop re-exploring the project
- 11,233 ★ on the repository
- Last commit
- MIT
Broad access
Why this level
- Writes files into the repo and edits settings in the home folder (`~/.claude/settings.json`, `~/.claude.json`, `~/.codex` when present), after which hooks fire in every repository you open
- Reads the logs of your past Claude Code sessions and review comments on merged pull requests, the text is processed by your own Claude Code, so it goes to Anthropic
- `build --deep` sends file contents to the model provider under your key, and connecting a Trail workspace sends learnings and search records
Install
- Works in
Manual install
npm install -g @trailhq/trail-code
trail initinit asks which agents to wire, Claude Code is preselected. Without a terminal to prompt on, it writes nothing. Preview with `trail init --dry-run`.
Access and checks
How we reviewBroad accessThe tool can change data, run commands or handle secrets.
- Writes files into the repo and edits settings in the home folder (`~/.claude/settings.json`, `~/.claude.json`, `~/.codex` when present), after which hooks fire in every repository you open
- Reads the logs of your past Claude Code sessions and review comments on merged pull requests, the text is processed by your own Claude Code, so it goes to Anthropic
- `build --deep` sends file contents to the model provider under your key, and connecting a Trail workspace sends learnings and search records
This is third-party code. Review the repository files before installing.
What it does
Trail-code, formerly Graft, has two parts. The first is the code map: `trail init` parses the repository with tree-sitter into a map of files, functions and calls, with no model and no key. The map is checked against the working tree before every query, unsaved edits included. With each prompt the agent gets pointers to the matching files, and after editing a file it sees what depends on it. The second part is learnings from past sessions. When a session works something out, or you correct the agent, it saves a learning as a short markdown file. Learnings about the code live in the repo's `.trail/learnings/` and are committed with the change, personal ones stay in `~/.trail`. The next session on that code starts from them, yours or a teammate's. On day one `trail init` collects what you told Claude Code in two or more past sessions of the repo. Before a pull request, `trail check` compares the branch with the accumulated learnings. The tool wires the agents you pick: it writes their instruction files, and for Claude Code adds a statusline, hooks and an MCP server with six code search tools. The `trail build --deep` mode also builds explanations of files and nodes on your own model provider. A CI mode exists too: `trail blast` shows what a diff touches.
Who it is for. For developers and teams who use coding agents on a large repository and are tired of repeating the same things to the agent every session.
Good fit when
- The agent re-searches the repository every session for where things are and who calls what
- The team wants code decisions and rejected options to live in the repo and reach the agent's context on their own
- Before a pull request you want to check that the branch does not undo a decision a colleague already made
- You keep repeating the same instructions to the agent from one session to the next
Not a fit when
- The project is small and the agent copes without an extra context layer
- Your policy forbids installing hooks and changing agent settings in the home folder. A standalone MCP server such as CodeGraph fits better then
- You need one team page across all repositories: the Trail workspace is marked as upcoming in the docs
- The machine has Node.js below 20: the package requires version 20 or newer
Example request
Before changing the retry count in the client, use trail to see what we already decided about itLimitations
- Learnings come in two kinds so far, decisions and preferences, in the personal and repo places. Skills, agent guardrails and the shared team layer are marked as upcoming.
- To collect past sessions, `trail init` runs your own Claude Code on Claude Sonnet under your login, which counts toward your subscription limit. It also reads review comments on the last 50 merged pull requests when `gh` is installed. Fragments that look like secrets are removed.
- 23 languages and Vue single-file components are parsed, files in other languages are skipped. For OCaml and Zig the map holds symbols only, without call edges.
- The `graft/` folder with the map is a local cache and goes into `.gitignore`. The commit carries `.claude`, `.mcp.json`, `.trail`, `.gitignore` and `.ignore`, and the rest of the team builds the map on their side.
- Once a day the tool checks the npm version and sends one batch of anonymous stats with no code, paths or learning text. In CI and in builds from source sending is off.
- Savings figures, such as 33 solved tasks out of 50 against 27, were measured by the author on its own harness and on a SWE-bench Verified sample.
How to disable. Run `trail uninstall` in the repository to see what would be removed, and `trail uninstall -y` to remove the files and config entries init added. With `--keep-cache` the `graft/` folder stays, with `--no-global` `~/.claude`, `~/.claude.json`, `~/.codex` and `~/.gemini` are left alone. Then remove the package: `npm uninstall -g @trailhq/trail-code`, or `npm uninstall -g @nanonets/graft` for an old install. Anonymous stats are turned off by `trail telemetry disable` or the `DO_NOT_TRACK=1` variable.
FAQ
Do I need a language model key?
No. The map, hooks, learnings and `trail check` work without one. A key is only needed for `trail build --deep`; the provider is set with `GRAFT_PROVIDER`, `GRAFT_API_KEY` and `GRAFT_MODEL`, and the endpoint address with `GRAFT_BASE_URL`.
What if Graft is already installed?
Nothing breaks: the `graft` command and the `@nanonets/graft` package run the same code. `graft upgrade` adds `trail` next to it. Repos set up by Graft move on their own the first time you open Claude Code after `trail` appears, or right away with `trail init`.
How is this different from CLAUDE.md and AGENTS.md?
You write and update those by hand. Trail-code saves learnings from conversations and brings in only the ones about the code being edited. init never touches `CLAUDE.md`, for Claude Code it writes its own `.claude/skills/trail/SKILL.md`.
What should I commit after setup?
`.claude`, `.mcp.json`, `.trail`, `.gitignore` and `.ignore`. A colleague without Trail-code gets the learnings from `.trail/learnings/` through the skill file in Claude Code, and the agent tells them once how to install the rest.
What if the agent saves a wrong learning?
A repo learning is a file in a pull request, reviewed like code, deleted or edited. Personal ones sit in `~/.trail`. The agent never rewrites an existing learning: when it goes against one, it explains why in the commit and saves a new one.
Do I need to sign in or have an account?
No. Everything runs on your machine and learnings reach the team through git. The Trail workspace, announced but not yet available, is only for the shared page across repos.
Discussion
No questions or reviews yet.
Related
CLI toolsA coding-agent monitor with a project component map and an experimental 3D kitchen view of ongoing tasks
cogit records every message to an agent as a thought commit and ties code to it, so cogit why explains the reason behind any line.
A set of Claude Code utilities: background skills, expert agents, slash commands and prompt templates for development
codesight maps a project in one run: routes, DB models, dependencies, env vars. It gives the map to an agent as files or through an MCP server
Shared Claude Code settings for a team: hooks against dangerous commands, a check before finishing and skills from spec to review
Reads Claude Code session logs as a conversation: tool calls, token counts and a live tail of a running session.
Comparison with similar tools
Cards that share the main search query, and how they differ.
| Tool | Official | Authentication | Repository stars | Main difference |
|---|---|---|---|---|
| Trail-code (formerly Graft) (this card) | no | 11,233 | ||
| CodeGraph | no | not required | 77,481 | a standalone MCP server with a local code graph in SQLite, the index updates on file system events |
| code-review-graph | no | not required | 32,733 | a PyPI package, a tree-sitter graph serves the context around a change over MCP, with a GitHub Action for review |
| base (basemode) | no | 385 | a Rust CLI that builds a knowledge graph of code and decisions and |
README in short
The documentation opens with a table of the two parts, the code map and learnings, followed by a quick start and a table for moving from Graft to Trail-code. It covers the kinds and places of learnings in detail, a sample file and how a team works through git. Measurements come in three forms: 162 runs of one agent on the same tasks, SWE-bench Verified and 15 tasks on the PocketBase repository. A reference follows: the two-pass graph build, the language list, a table of files init writes outside the repo, six MCP tools, the full CLI command list, monorepo handling and `trail viz` visualization. The root holds separate TELEMETRY.md and SECURITY.md files, a changelog, a Dockerfile and a GitHub action for blast radius reports. MIT licensed.