Repolode
Submit
trailhq

trailhq/Trail-Code

A self-learning context layer that gives coding agents like Claude Code and Cursor a map of your codebase plus the decisions your team has made about it.

View on GitHubWebsite
Stars
11,118
Forks
990
Open issues
275
Last commit
20 hours ago

What is it?

Trail-code (formerly graft) gives coding agents two things: a code map and a store of learnings. The code map is built locally with tree-sitter and records every file, function and caller, so an agent can find the relevant code and see what a change might break. No model or API key is needed for this part, and it refreshes as files change, including uncommitted edits.

The learnings part captures what you, your agents and your team have worked out or decided. When a session resolves something or you correct how work is done, the agent saves a short markdown file in the repo's .trail/learnings directory. These files are committed with the code, so teammates' agents start from the same decisions. Personal learnings stay in ~/.trail on your machine. The trail check command compares a branch against recorded learnings before a PR.

The project is a TypeScript CLI installed from npm. Its README reports benchmark results on SWE-bench Verified and on its own harness, which the maintainers ran themselves.

Key features

  • 01Builds a local code graph of files, functions and callers using tree-sitter, with no model required.
  • 02Refreshes the code map on each query so it reflects uncommitted edits.
  • 03Saves learnings as markdown files in the repo, reviewed through pull requests.
  • 04Runs trail check to compare a branch against recorded learnings before a PR.
  • 05Keeps personal learnings in ~/.trail, never committed.
  • 06Supports 24 languages, including TypeScript, Python, Go, Java and Rust.

Use cases

  • Giving Claude Code or Cursor a map of a large codebase so it opens fewer files.
  • Recording why a design choice was made so future agent sessions don't undo it.
  • Catching changes that conflict with a teammate's recorded decision before merging.
  • Reducing token use and session time when agents work on an unfamiliar repository.

Quick start

  1. 1

    Install the CLI globally from npm

    npm install -g @trailhq/trail-code
  2. 2

    In your repo, build the code map and set up the agent wiring

    trail init

Things to know

  • Trail-code needs Node 22.3 or newer (20.16 also works), so older Node setups must be upgraded first.
  • Learnings are stored as files in the repo, and personal learnings stay on your machine.

In collections

MCP servers for Claude CodeClaude Code tools, skills & pluginsOpen-source AI agent frameworks & appsMCP serversCLI & terminal tools

Topics

#ai-agents#claude-code#code-graph#context-engineering#mcp#tree-sitter#llm#developer-tools#anthropic#cli

FAQ

What is Trail-Code?
A self-learning context layer that gives coding agents like Claude Code and Cursor a map of your codebase plus the decisions your team has made about it. Trail-code (formerly graft) gives coding agents two things: a code map and a store of learnings. The code map is built locally with tree-sitter and records every file, function and caller, so an agent can find the relevant code and see what a change might break. No model or API key is needed for this part, and it refreshes as files change, including uncommitted edits.
Is Trail-Code free to use? What license does it have?
Trail-Code is open source under the MIT license. Check the license terms before using it in commercial products.
Is Trail-Code still maintained?
Actively maintained. The last commit to Trail-Code was on Nov 6, 2026.
What can I use Trail-Code for?
Giving Claude Code or Cursor a map of a large codebase so it opens fewer files. Recording why a design choice was made so future agent sessions don't undo it. Catching changes that conflict with a teammate's recorded decision before merging. Reducing token use and session time when agents work on an unfamiliar repository.
How do I install Trail-Code?
Install the CLI globally from npm: npm install -g @trailhq/trail-code In your repo, build the code map and set up the agent wiring: trail init
Where can I get Trail-Code?
The source code and installation instructions are on GitHub: https://github.com/trailhq/Trail-Code

Summary generated by AI from the project's README. GitHub stats refresh daily.

Related projects