A local-index-first code search tool for fast, verifiable source evidence.
CodeTrail's core promise is not to "understand the code"—it is to return verifiable evidence quickly. Search, symbol location, range reading, definitions, references, call candidates, index status, and MCP output are all organized around readable results, pagination, and caveats.
macOS/Linux:
curl -fsSL https://raw.githubusercontent.com/mars167/CodeTrail/main/install.sh | shWindows PowerShell:
irm https://raw.githubusercontent.com/mars167/CodeTrail/main/install.ps1 | iexThe installer downloads the latest GitHub Release assets for your OS, verifies SHA256SUMS, and installs codetrail. On macOS/Linux, it is installed by default to ~/.local/bin. On Windows, it is installed to %LOCALAPPDATA%\Programs\codetrail\bin and added to your user PATH.
Install a specific version:
curl -fsSL https://raw.githubusercontent.com/mars167/CodeTrail/main/install.sh | sh -s -- --version v0.1.4$env:CODETRAIL_VERSION = "v0.1.4"; irm https://raw.githubusercontent.com/mars167/CodeTrail/main/install.ps1 | iexIf codetrail exits immediately with no output in PowerShell or Git Bash, check the exit code first:
codetrail --version; $LASTEXITCODEAn exit code of -1073741515 (0xC0000135, STATUS_DLL_NOT_FOUND) means the Windows loader killed the process before it could print anything. Releases up to v0.1.6-beta.2 linked the MSVC C runtime dynamically and therefore required VCRUNTIME140.dll from the Visual C++ Redistributable; a clean Windows 11 install does not ship it. Later releases link the CRT statically and are fully self-contained — upgrading to the latest release fixes this without installing anything else. An exit code of -1073741795 usually means the binary architecture does not match the machine; reinstall with CODETRAIL_ARCH set to arm64 or amd64.
codetrail index build
codetrail find "TODO"
codetrail read README.md:1-40Default output is concise text. For machine consumption, use --output json or --output jsonl. For full argument details, run codetrail --help and check src/cli.rs.
Content and path search:
codetrail find "TODO"
codetrail grep "fn [a-z_]+"
codetrail files "README"
codetrail glob "src/**/*.rs"Range read and symbol lookup:
codetrail read README.md:1-40
codetrail defs main
codetrail refs main
codetrail symbols queryIndexing and saved query:
codetrail index build
codetrail index status
codetrail find "TODO" --save-query todo-find
codetrail query replay todo-findWhen debugging local issues, add -v/--verbose to send diagnostic logs to stderr and keep stdout clean for JSON/text output:
codetrail -v --output json index build --force > out.json 2> debug.logMCP integration:
codetrail mcpPublic JSON responses only include results, page, and caveats. Each caveat carries a stable severity and category to distinguish risk warnings from expected capability-level caveats.
Before editing code, verify search, remote, or graph-derived results with read. Different source types are represented with different reliability levels: text hits are verifiable clues, SCIP occurrences are more precise but still need range review, parser fallback and call candidates are not semantic proof, and remote results must be clearly marked when they are not aligned with local file proof.
CodeTrail separates "searchability" from "trustworthiness": indexing speeds up discovery, but answers must always be traceable back to local files, snapshots, ranges, and reliability notes. CLI and MCP share the same query service so different integrations do not get different facts.
flowchart TB
User["Developer / LLM Agent"] --> Entry["CLI / MCP"]
Entry --> Query["Query service"]
Git["Git repository\nHEAD / index / worktree"] --> Snapshot["Snapshot identity"]
Files["Local source files"] --> Freshness["Freshness proof\npath / size / mtime / hash"]
Snapshot --> Freshness
Freshness --> Index["Local index\n.codetrail/index.lance"]
Freshness --> Live["Live scan / dirty overlay"]
Freshness --> Saved["Saved query metadata"]
Remote["Remote snapshot cache"] --> Verify["Local proof verification"]
Index --> Text["Text and path candidates"]
Index --> Occ["SCIP occurrences"]
Freshness --> Parser["Parser fallback"]
Freshness --> Graph["Call candidates"]
Verify --> RemoteResults["Verified or unverified remote results"]
Text --> Query
Occ --> Query
Parser --> Query
Graph --> Query
Live --> Query
Saved --> Query
RemoteResults --> Query
Query --> Output["Results with ranges,\nreliability and caveats"]
Output --> Read["read verifies exact source ranges"]
Core boundaries:
- Snapshot is the truth boundary: results must declare whether they come from commit, staged, or worktree state; different sources must not be merged into one untraceable answer.
- Local index is the acceleration layer: when index data is missing, stale, or partial, queries should fall back to live scanning, dirty overlay, or return clear caveats.
- Query service is the integration boundary: CLI, MCP, saved query replay, and remote snapshots all share the same public JSON/text projection.
- Reliability is an interface contract: text hits, exact occurrences, parser fallbacks, call candidates, and remote results must use different reliability levels; key edits should still be rechecked with
read. - Remote and saved query are not ground truth: remote is only confidence-boosting when aligned with local proof; saved query stores only replay metadata, never full result payloads.
This repository includes an LLM Agent Skill and agent templates:
skills/codetrail/
It explains how an agent should use codetrail to collect verifiable source evidence, apply reliability grading, replay saved queries, check index freshness, and validate MCP/JSON contracts. When using with this repository, install the Skill from the repo:
npx skills add https://github.com/mars167/CodeTrail --skill codetrailIf you are already inside this repository checkout, install from local root:
npx skills add . --skill codetrailFor multi-step repository investigation, install the OpenCode subagent template:
skills/codetrail/agents/opencode/codetrail-evidence.md
into .opencode/agents/ or ~/.config/opencode/agents/. The subagent owns
task-aware query sequencing and evidence compression; CodeTrail itself remains
the search/navigation tool layer. Do not add task-specific CLI commands such as
brief, context, or analyze-*.
For benchmark-backed guidance on when to use the CLI directly and when to
delegate to the subagent, see
docs/04-agent-benchmark.md.
Design references:
| Document | Details |
|---|---|
docs/00-design-summary.md |
Product positioning, boundaries, and architecture overview |
docs/01-architecture.md |
Snapshot, index, query, watcher, and remote architecture |
docs/02-command-contract.md |
Command families, JSON responses, and reliability contracts |
docs/03-quality.md |
Local quality gate, CI mapping, performance and reliability safeguards |
docs/04-agent-benchmark.md |
Docker/OpenCode benchmark results and Agent usage guidance |
Implementation details should be treated as the source of truth in src/, tests/, and scripts/.
cargo build
cargo testUnified local/CI quality entrypoint:
scripts/quality-gate.sh pr
scripts/quality-gate.sh main
scripts/quality-gate.sh benchquick is an alias for pr, cli is an alias for main, and full runs main then bench.
Please report issues and improvements via pull requests. If you touch command contracts, reliability levels, indexing, remote behavior, watcher logic, or MCP output, update related documentation and run the relevant quality gates.
MIT. See LICENSE.