Codetopo — code graph for AI agents

What codetopo — code graph for AI agents does

codetopo — code graph for AI agents converts a source tree into a stored graph containing packages, modules, files, functions, external nodes, and typed relationships such as calls, containment, reads, and imports. It is domain-blind: the system reports structural facts and does not score code, rank components, or infer business meaning.

The graph supports questions such as which functions depend on a symbol, which nodes are downstream, what lies in a failure's blast radius, and how two nodes are connected. Query results are aggregate-first by default, returning counts before expanded lists. This helps keep responses and command pipelines bounded until a caller requests full detail.

How it works

Indexing parses Rust and TypeScript/JavaScript with tree-sitter and writes the extracted graph to a SQLite-backed store. The shared codetopo-core layer supplies the graph model, traversal queries, and snapshot operations used by the command-line, HTTP, and MCP surfaces.

The MCP package runs as a stdio JSON-RPC process. Its twelve tools cover indexing, graph traversal, discovery, integrity checks, snapshots, and schema description. The MCP handlers and HTTP API use the same core query implementation, so equivalent requests produce the same answers.

The stored data includes a hash-chained audit log. codetopo_verify checks that log, while snapshot and restore operations provide a portable JSON representation and a way to load it into another database. The separate ACP binary is a read-only stdio agent with deterministic routing for common structural questions; it is not the MCP server itself.

Setup and configuration

A stable Rust toolchain is required. The repository provides separate packages for the CLI, HTTP server, MCP server, and ACP agent. Install the binaries by naming the packages explicitly, then start codetopo-mcp from the MCP client's configuration.

A minimal stdio configuration is:

{ "mcpServers": { "codetopo": { "command": "codetopo-mcp" } } }

For CLI use, index a repository into a database before querying it. A typical sequence is codetopo index <repository> --db graph.db, followed by symbol discovery and a traversal query. Symbol identifiers include the indexed directory's package prefix, so callers should use the identifier returned by search rather than assume a shorter name.

The HTTP binary listens on 127.0.0.1:8080 by default and uses Bearer API-key authentication. Its documented configuration variables are CODETOPO_BIND, CODETOPO_DATA_DIR, CODETOPO_KEYS_FILE, and CODETOPO_METERING_LOG. The HTTP API contract is described by the repository's OpenAPI schema.

Tools and capabilities

The MCP tool set includes:

• codetopo_index to create a graph from a repository
• codetopo_search_symbols and codetopo_get_symbol for discovery
• codetopo_descendants and codetopo_ancestors for dependency traversal
• codetopo_blast_radius for downstream impact analysis
• codetopo_path for shortest typed paths between nodes
• codetopo_stats for graph counts
• codetopo_neighborhood for local graph context
• codetopo_verify for audit-log validation
• codetopo_snapshot for a frozen JSON export
• codetopo_describe_schema for the graph schema

These capabilities make codetopo — code graph for AI agents suitable for coding agents that need read-only structural context before editing or reviewing a repository. The CLI offers corresponding commands, including restore from a snapshot, while the HTTP surface exposes the same handler layer through JSON endpoints.

Limitations and notes

The extractor support described here covers Rust and TypeScript/JavaScript. The project intentionally does not provide domain interpretation, code-quality opinions, rankings, or edits. The MCP process communicates over stdio, so its host must support configuring a local stdio MCP server. ACP is also read-only and refuses edit requests. The HTTP deployment adds API-key management and metering requirements that do not apply to the basic stdio configuration.