Give coding agents a structural map of your codebase.
Codetrip turns a repository into a local typed code graph so Codex, Claude Code, Cursor, VS Code/Copilot, and GitHub Copilot CLI can answer questions that plain text search cannot:
What calls this method? What could this change affect?
How does this request flow? Can I safely rename this symbol?
It combines graph traversal, source search, and optional semantic retrieval behind one CLI, MCP server, and Go library. Indexes stay on your machine. When an MCP client invokes a tool, the selected result is returned to that client and may enter its model context under the client's data policy. Configuring an external embedding endpoint additionally sends indexed chunks to that endpoint; lexical and graph indexing require neither service.
In a real read-only Codex run, Codetrip mapped the current working-tree diff to five changed CLI symbols, walked their reverse dependencies, separated documentation-only changes, and identified the shared runtime risk path:
The prompt was:
Before I commit, use Codetrip to analyze the current working-tree changes. Separate documentation-only changes and show the highest-risk runtime path.
Codex called Codetrip's diff and impact MCP tools. The index remained local,
the selected graph results were returned to Codex, and no files were edited.
The same graph is directly available to humans through the CLI:
$ codetrip impact IndexRepo --repo codetrip --depth 2 --format tree
IndexRepo engine.go:318
└── CALLS ← newIndexCmd cmd/codetrip/cli.go:469
└── CALLS ← newRootCmd cmd/codetrip/cli.go:39
2 affected symbols across 2 filesUnlike a text match, the result records relationship direction, distance, and
the evidence used to resolve each call. Omit --format tree to receive the
complete JSON result, including confidence and resolution evidence.
Codetrip is primarily for developers and small teams who want their coding agent to understand repository structure without deploying a code-intelligence service. It is also useful directly from the terminal for pre-change impact analysis, architecture exploration, and safe rename planning.
The Go library is the secondary integration surface for tools that need an embedded, repository-scoped code graph. Codetrip is not currently intended to replace an enterprise code-search platform, an IDE refactoring engine, or a cross-organization code host.
Download a prebuilt binary for Linux, macOS, or Windows from GitHub Releases, or install with Go:
go install github.com/mengshi02/codetrip/cmd/codetrip@latestBuilding with go install requires Go 1.26+ and a C toolchain. Release archives
contain a single executable and require no language runtime.
cd /path/to/project
codetrip index . --repo projectThe command prints the number of files, graph nodes, graph edges, and elapsed
indexing time. Re-index later with --replace.
# Exact symbol names work directly.
codetrip search "ParseConfig" --repo project
codetrip context ParseConfig --repo project
codetrip impact ParseConfig --repo project --depth 3 --format tree
codetrip diff HEAD~1 --target HEAD --repo projectIf a name is ambiguous, Codetrip lists matching locations and their node IDs
instead of guessing. Pass one of those IDs to select it precisely. CLI query
results are JSON by default and are safe to pipe into jq or another program.
codetrip mcp setup --dry-run
codetrip mcp setupThe setup command detects supported clients and preserves unrelated MCP servers. Restart your client if it is already running, then try:
Use Codetrip to find
ParseConfigand show what depends on it.
Target a specific client with codetrip mcp setup codex (or claude,
cursor, vscode, or copilot). Use --force only when replacing an existing
Codetrip entry.
| Plain text or vector search | Codetrip |
|---|---|
| Finds similar or matching text | Resolves symbols plus typed relationships |
| Shows isolated occurrences | Connects calls, imports, inheritance, and overrides |
| Does not know dependency direction | Traverses forward or reverse dependencies |
| Leaves change impact to the reader | Maps Git changes to symbols and affected code |
| Treats rename hits alike | Separates semantic references from review candidates |
Codetrip still includes fast source and symbol search. The graph adds structural context where search alone is not enough.
These projects overlap, but optimize for different operating models:
| Project | Best fit | Deployment model | Current strengths |
|---|---|---|---|
| Codetrip | Local structural context for coding agents and CLI users | One native executable; embedded Go library; local MCP | Atomic repository snapshots, Git-diff-to-symbol impact, typed graph queries, five release targets, no required model service |
| GitNexus | Rich agent workflows and graph exploration | Node/npm CLI, MCP, skills/hooks, and Web UI | Incremental updates, execution flows, clusters, Cypher, repository groups, PDG/taint tools, broad agent automation |
| Serena | IDE-like semantic retrieval and source editing | MCP backed by language servers or its JetBrains plugin | 40+ language-server integrations, symbolic editing, refactoring, diagnostics, and optional IDE-grade analysis |
| Sourcegraph | Organization-wide search and navigation | Managed single-tenant/enterprise platform plus IDE/Web integrations | Multi-repository and multi-code-host search, branch/history search, SCIP-based precise navigation, enterprise scale |
Choose Codetrip when local deployment simplicity, a native binary, deterministic repository snapshots, and embeddability matter more than a Web UI or agent workflow suite. Choose GitNexus when you want a broader graph-agent environment today; Serena when the agent should perform IDE-backed edits and refactors; and Sourcegraph when the problem is organization-wide code discovery and governance.
This table compares documented product shape, not relative speed or accuracy. Codetrip has not yet published an apples-to-apples competitor benchmark.
| Goal | Command |
|---|---|
| Find a symbol | codetrip search "ParseConfig" --repo project |
| Search source or documentation | codetrip source 'lang:go ParseConfig' --repo project |
| Explain a symbol and its neighbors | codetrip context ParseConfig --repo project |
| Find reverse change impact | codetrip impact ParseConfig --repo project --format tree |
| Analyze a Git diff | codetrip diff HEAD~1 --target HEAD --repo project |
| Trace a directed route | codetrip path LoadConfig ParseConfig --repo project |
| Check cycles and graph integrity | codetrip check --repo project |
| Plan a rename without editing files | codetrip rename ParseConfig NewName --repo project |
The MCP server exposes the same core operations:
list search source context impact check diff rename traverse path
Codetrip parses Go, TypeScript/TSX, JavaScript/JSX, Python, Java, C, C++, C#, Rust, PHP, Swift, and Kotlin. Language-aware resolution is covered by the repository's semantic test suite, but relationship precision varies with each language and with dynamic or reflective code. Textual candidates remain available when a reference cannot be resolved semantically. All 12 languages pass curated semantic fixture gates; real-repository precision and source-driven recall reviews are complete for C++, in progress for Kotlin, and planned for the remaining languages. See the semantic quality report.
Cold full-snapshot indexing on an Apple M2 Pro with 16 GB RAM, with embeddings disabled:
| Repository | Language | Files | Nodes | Edges | Duration | Index size |
|---|---|---|---|---|---|---|
| Kubernetes | Go | 17,389 | 107,385 | 277,588 | 121.11 s | 713.5 MiB |
| RocksDB | C++ | 2,006 | 52,507 | 198,900 | 204.62 s | 434.5 MiB |
| RocketMQ | Java | 2,552 | 29,535 | 141,874 | 29.16 s | 342.7 MiB |
| FastAPI | Python | 2,714 | 8,913 | 15,474 | 7.53 s | 68.4 MiB |
| Exposed | Kotlin | 5,173 | 25,763 | 70,030 | 26.65 s | 443.9 MiB |
All 12 advertised languages completed the same cold-index procedure. See the full results, commits, and methodology. These are Codetrip measurements, not cross-tool comparisons; time and size vary with hardware, checkout contents, operating system, and version.
Lexical search and graph analysis do not require an embedding model. To add semantic retrieval, point Codetrip at an OpenAI-compatible embeddings endpoint:
codetrip embed --repo project \
--endpoint http://localhost:11434/v1/embeddings \
--model nomic-embed-text
codetrip hybrid "configuration loading" --repo project \
--endpoint http://localhost:11434/v1/embeddings \
--model nomic-embed-textVectors are persisted per repository. Optional int8 quantization is available for smaller indexes.
+-------------------+ +---------------------------+
| Repository | | Typed Code Graph |
| .go .ts .py ... | ----> | symbols, calls, imports, |
| source + Git | | inheritance, processes |
+-------------------+ +-------------+-------------+
|
+---------------------+---------------------+
| | |
Symbol/source Graph traversal Optional vectors
search and change impact + hybrid ranking
| | |
+---------------------+---------------------+
|
Go library / CLI / MCP
Each repository has independent storage and is published as an atomic snapshot. The durable graph is authoritative; search indexes and vectors are repository-scoped derived data. Building a replacement never exposes a partially updated active snapshot.
engine, err := codetrip.Open("./.codetrip")
if err != nil {
log.Fatal(err)
}
defer engine.Close()
_, err = engine.IndexRepo(ctx, "/path/to/project",
codetrip.WithRepoName("project"),
codetrip.WithReplaceExisting(true),
)
result, err := engine.Search(ctx, &codetrip.SearchRequest{
Repo: "project", Query: "ParseConfig", Limit: 20,
})
impact, err := engine.Impact(ctx, &codetrip.ImpactRequest{
Repo: "project", NodeID: result.Results[0].NodeID, MaxDepth: 3,
})The public API also provides source and hybrid search, context, structural checks, Git change analysis, rename planning, traversal, shortest paths, repository management, CSV export, metrics, and configuration options.
Export the complete active graph as deterministic CSV plus a manifest with row counts and SHA-256 checksums:
codetrip export --repo project --output ./exports/projectFor parser and language tuning, index --export can also capture validation
CSV before persistence. See the user guide for details.
Release binaries are built for Linux and macOS on amd64/arm64, and Windows on amd64. Linux artifacts are statically linked; macOS artifacts use system libraries only; Windows artifacts do not depend on a compiler runtime.
Linux and macOS use the native high-throughput source-search backend. Windows uses a portable backend with the same query features and may be slower on large repositories. Rename is analysis-only and never edits source. Git diff analysis does not include untracked files until they are added and indexed.
- Re-indexing currently builds a complete replacement snapshot. This is consistent and reader-safe, but expensive for large frequently changing repositories.
- Cross-repository relationships are not resolved yet.
- Dynamic dispatch, reflection, generated code, macros, and runtime module loading can reduce relationship precision. Confidence and textual fallback candidates remain visible rather than being presented as certain.
- Language support is not equally precise. Fixture results are published for all advertised languages, while real-repository precision and recall reviews are complete for only part of the language matrix.
- The CLI is moving toward richer human-readable views; most commands still
return JSON, while
impactadditionally supports--format tree. - Codetrip has no Web UI and does not perform source edits.
Current priorities:
- Incremental indexing without weakening atomic publication
- Cross-repository analysis and contract-aware impact
- Stronger resolution for dynamic languages
- More human-readable CLI output
- Automatic repository discovery and simpler repo selection
- More MCP workflows for pre-commit analysis, debugging, and review
The longer-term direction is a distributed, cloud/local hybrid code-intelligence engine that preserves the current embedded and local-first path. See an important missing capability or workflow? Open an issue—or star the repository to follow the roadmap.
go test ./...
go vet ./...