trailhq

Trail-Code: Share Code Maps and Learnings Across Coding Agents

Trail-Code combines Tree-sitter code maps with team learnings to give Claude Code, Cursor, Codex, and other coding agents shared context. Its local TypeScript CLI indexes code and helps agents reuse decisions across sessions and teammates.

Stars
11.3k
Forks
1k
Last commit
6 days ago
Contributors
71
Releases, 12 months
0

Our take

Newless than six months old and changing fast

Health score

68/100

How it is scored
Activity
53
Community
71
Issues
72
Pull requests
75
  • Merges more pull requests than 78% of the projects we track

Trail-Code is a rapidly changing, early-stage tool with a clear team-context workflow, and its recent activity and broad contributor base are promising but do not replace evaluation in your own repositories.

Good fit if

  • Your team uses supported coding agents and wants code maps plus reusable decisions shared through Git.
  • You want a local, model-free structural index, with optional summaries using your own provider credentials.
  • You can evaluate a young project that is actively changing and has no release in the past year.

Look elsewhere if

  • You need a mature, release-driven product rather than a newly established project.
  • Your workflow does not use coding agents, MCP, or the CLI-based code and learning tools Trail-Code provides.
  • You need team-wide learning management through a hosted workspace today; the README describes that workspace as coming soon.
All health signals
Last commit2026-11-09 (6 days ago)
Commits, last 90 days100+
Releases, last 12 months0
Contributors71 (top contributor: 49% of commits)
Issues closed, last 90 days9+ (typically closed in 1 day)
Pull requests merged, last 90 days60 (typically merged in 0 days)
Project age5 months

Checked on 2026-11-16 with the GitHub API.

Overview

Trail-Code is a TypeScript CLI that combines Tree-sitter code maps with learnings captured from coding sessions. It is designed for teams whose agents repeatedly search the same code or lose track of prior decisions: the map links code symbols and callers, while learnings give agents relevant context about what the team decided and why.

The project supports Claude Code, Cursor, Codex, and other agents through agent-specific setup and an MCP server. The code map is built on the developer’s machine without a model or API key; optional deeper summaries use a model provider configured by the user. Learnings can be stored in the repository and shared through Git, or kept personal on the developer’s machine.

Key Features

  • Builds a Tree-Sitter code graph of symbols and call relationships, with language support spanning TypeScript, JavaScript, Python, Go, and other languages.
  • Refreshes the structural map as code changes, including uncommitted edits.
  • Provides CLI and MCP tools for code search, repository orientation, symbol tracing, file signatures, and change impact.
  • Saves learnings as Markdown files that agents can reuse in later sessions and teammates can share through Git.
  • Checks code changes against saved learnings and can surface overlapping work on teammates’ branches.
  • Sets up integrations for Claude Code, Cursor, Codex, and other supported agents.
  • Offers optional LLM-generated summaries through a provider and API key selected by the user.

Use Cases

  • A team maintaining a large or unfamiliar codebase can help agents locate relevant functions and understand callers before making changes.
  • Teammates can share decisions about tricky code through committed learning files, reducing repeated investigation across sessions.
  • Developers using Claude Code, Cursor, Codex, or MCP-compatible agents can provide those tools with a common code map.
  • A maintainer can check a proposed change against prior decisions or inspect its potential impact before opening a pull request.

What you need

Detected in the repository

  • Node.js ^20.16.0 || >=22.3.0 (from package.json)
  • A Dockerfile, so it can run in a container
  • A test suite and automated checks on GitHub Actions

License in plain words

MITpermissive

  • Commercial use: yes
  • Modify and redistribute: yes
  • You must keep: the copyright and license notice
  • Share your changes: no

A summary, not legal advice: the LICENSE file is what applies.

Getting Started

npm install -g @trailhq/trail-code
trail init

See the README for agent setup options, CLI commands, configuration, and details on where data is stored.

Alternatives

  • Agent-Memory: Focuses on capturing and retrieving session memories across agents, rather than combining team learnings with a Tree-sitter code map.
  • agentmemory: Provides persistent memory across sessions through agent integrations, rather than indexing code structure and sharing team decisions.
  • codebase-memory-mcp: Maps code structure and relationships for repository queries, without Trail-Code’s emphasis on retaining shared team learnings.
  • codegraph: Focuses on code graphs, source retrieval, and change impact across languages, rather than cross-session team knowledge.
ProjectLanguageLicenseStarsStatus
Trail-CodeTypeScriptMIT11.3kNew
Agent-Memory–Apache-2.09Quiet
agentmemoryTypeScriptApache-2.029.1kActive
codebase-memory-mcpCMIT45.7kActive
codegraphCMIT73.1kActive

Considerations

  • The project is young and changing quickly. It has recent commit activity and contributions from many people, but no release in the past year, so check whether its current behavior and interfaces suit your setup.
  • Node.js 20.16 or newer, or 22.3 or newer, is required. Docker is also listed as a requirement in the repository metadata.
  • The basic code graph and learning workflows do not need an API key; optional deep summaries do.
  • Team-wide workspace features are described as coming soon. Current repository learnings are shared through Git.
  • The README describes anonymous usage statistics as opt-out, and details available controls and fields in TELEMETRY.md.
  • The project is MIT-licensed; review the license and your organization’s requirements before adoption.

Found this useful?

Share it with someone who would like Trail-Code.