Guide · Open source
How to use Trail-Code: install, build a code map and set up agents
Updated · written with AI from the project's own documentation and checked against our catalogue data
Trail-Code is a command-line tool that indexes your codebase and stores notes on decisions and lessons from your work, so coding agents like Claude Code, Cursor and Codex start with that context instead of searching from scratch. This guide covers installation, the first-time setup with trail init, and how the two parts (the code map and learnings) fit together. By the end you will know what to install, what to run in your repo, and what the tool saves on your machine.
Trail-codetrailhq/Trail-Code · ★ 11k · MIT Install options & downloads Quick start
- 1Check your Node version. Confirm Node.js is 22.3 or newer. Node 20.16 is noted as working too.
- 2Install the CLI. Run npm install -g @trailhq/trail-code to install the trail command globally.
- 3Fix global install permissions if needed. If you see EACCES, set a user-owned npm prefix, add its bin folder to your PATH, and install again.
- 4Go to your repository. Change into the project folder that your coding agents work on.
- 5Run trail init. Choose the agents to connect, let it build the graft map, and let it create the .trail/ folder.
- 6Work as usual. Keep using your agent; the map refreshes itself and learnings are saved from your conversations.
- 7Review learnings. Open the learning files in .trail/ to check what was saved, since they are readable files.
Check the requirements before you install
Trail-Code needs Node.js 22.3 or newer. The README notes that Node 20.16 also works. If you are on an older Node version, upgrade first, because the README lists no other supported path.
Trail-Code is written in TypeScript and released under the MIT licence. Its main value comes through coding agent integration, so it is most useful if you already use Claude Code, Cursor, Codex or a similar agent.
- Node.js 22.3 or newer (20.16 noted as working)
- A coding agent such as Claude Code, Cursor or Codex
- A medium or large repository, where the code map saves the most searching
node --versionInstall the Trail-Code CLI
Install the command-line tool globally with npm. This is the only install method the README shows, and it installs the trail command on your system.
npm install -g @trailhq/trail-codeFix the EACCES error on global npm install
If npm reports EACCES, your Node global folder needs sudo. The README suggests avoiding sudo by pointing npm at a folder in your home directory, then installing again from a new terminal. This way later upgrades also work without sudo.
- Run the prefix commands below
- Add ~/.npm-global/bin to your PATH
- Open a new terminal and run the install command again
mkdir -p ~/.npm-global && npm config set prefix ~/.npm-globalRun trail init in your repository
Move into the repo you want agents to work on and run trail init. According to the README, it builds the graft map from your code, creates a .trail/ folder for the repo's learnings, and asks which coding agents to wire up. It also adds a statusline and hooks to Claude Code.
On first run, trail init also reads your past Claude Code sessions in the repo, once, and saves what you told Claude more than once as learnings. The README says your own Claude Code does that reading, and it takes about a minute. After setup there is no daemon or server to start; you work as you normally would.
- Asks which coding agents to connect
- Builds the graft map of files, functions and callers
- Creates .trail/ for learnings
- Adds a statusline and hooks to Claude Code
trail initUnderstand the code map
The code map is an index of your code: every file, every function and which code calls what. It is built with tree-sitter, needs no model and no API key, and refreshes when the code changes, including uncommitted edits. With each prompt, your agent receives pointers to the matching files and functions, and sees what depends on a file right after it edits it.
The map answers where things are. It does not explain why they are that way; that is the job of learnings.
- Built with tree-sitter, no model or API key needed
- Updates automatically, including uncommitted edits
- Shows the impact of a change on dependent code
Use learnings so agents remember decisions
Learnings are notes on decisions, corrections and lessons from your work. When a session works something out, or you correct how something is done, your agent saves it as a learning. Later sessions on that code, yours or a teammate's, start from it.
Learnings about the code are committed with the code. Learnings about you stay on your machine. The README gives an example: trail check flags a change that would undo a teammate's decision before the pull request, quoting who decided it and why.
- Learnings about code are committed with the repo
- Learnings about you stay local
- trail check warns before a PR if a change conflicts with a recorded decision
- Learnings are saved as files you can read
trail checkSearch and orient inside the map
The README documents trail grep and trail map as search and orientation commands for the graph. Use them to look up code through the map instead of only through plain text search. The README also covers trail viz for visualizing the graph and notes monorepo and multi-repo folder support in its reference sections.
For the full list of commands and flags, check the CLI section of the README in the trailhq/Trail-Code repository, since this guide only covers commands the source shows.
- trail grep: search through the map
- trail map: orient yourself in the graph
- trail viz: visualize the graph
- Monorepos and submodules are covered in the README
What people use it for
- Giving Claude Code or Cursor the right files for a task in a large repository without a long search
- Recording a team decision about retries or error handling so a future agent does not undo it
- Running trail check before opening a pull request to catch changes that conflict with past decisions
- Reducing tool calls and token use for an agent working on a medium or large codebase
Frequently asked questions
Is Trail-Code free?
Trail-Code is released under the MIT licence, according to the README and repository badges. The source shows no paid tier, so check the repository for any terms before relying on it commercially.
What Node.js version does Trail-Code require?
The README requires Node.js 22.3 or newer and notes that Node 20.16 also works. Older Node versions are not supported according to the README.
How do I install Trail-Code?
Run npm install -g @trailhq/trail-code to install the CLI globally, then run trail init inside your repository. If you get an EACCES error, set a user-owned npm prefix as described in the README.
Does Trail-Code send my code to a server?
The README says both the code map and learnings run on your machine. The repository also links a TELEMETRY.md file describing anonymous, opt-out telemetry, which you can read there for details.
Which coding agents does Trail-Code work with?
The README names Claude Code, Cursor, Codex and other coding agents. trail init asks which agents to wire up, and it adds a statusline and hooks to Claude Code.
How does Trail-Code compare to Aider, Sourcegraph Cody or Continue?
Aider, Sourcegraph Cody and Continue are listed as comparable projects in the source. The README does not compare them directly, so review each project's documentation to see which fits your workflow.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Trail-Code is a good fit for developers who already use Claude Code, Cursor, Codex or similar agents on a medium or large repository, especially teams that want agents to remember past decisions. It is a poor fit if you do not use coding agents, since most of its value comes from agent integration, or if you need independently audited benchmarks, because the README's performance figures come from the maintainers' own tests.
Install options & downloads