RepoMap gives AI coding agents architectural maps without sending source code

RepoMap is a pipeline tool designed to give coding agents "architectural awareness" by building deterministic maps of repository structure. The problem it addresses is well-defined: modern coding agents reconstruct project architecture inefficiently, repeatedly opening files and following imports to answer basic questions about where authentication is implemented, which modules depend on the database, or how components connect. This reconstruction happens every session and consumes thousands of tokens just on repository understanding.

The solution operates in three phases. First, a deterministic analyzer scans the repository without calling an LLM, extracting directory hierarchy, imports, function signatures, module relationships, and Git information into a compact RawAnalysis that describes the structure without exposing source code. Second, the LLM receives only this structured analysis and performs one reasoning step to assign architectural roles, identify architectural patterns, improve module labels, and generate a visualization layout. Third, RepoMap renders the result as an interactive, editable graph using React Flow, supporting multiple layouts, branch-based editing, node inspection, and viewport culling, with persistent local storage and Git-aware visualization that lets users inspect commits and browse branches while highlighting added, modified, and deleted files.

The technical architecture consists of four main components: analyzer.js performs deterministic scanning without LLM calls; index.js orchestrates the pipeline—analysis, persistence, and visualization serving; cli.js provides list and open commands; and visual_src/ contains the React Flow-based interactive renderer. The RepoGraph output format is a JSON structure containing metadata (repository name, estimated size, languages, file and module counts), a nodes array describing layers, modules, and files with their metadata, an edges array capturing imports and architectural relationships with strength and confidence scores, and an overlay section for storing edits and manual additions.

Installation is straightforward: clone the repository, run npm install, and use the CLI command to analyze a local repository and serve the interactive map; the skill auto-discovers in OpenCode and Claude. The tool is designed for integration with coding agents like Claude and OpenCode, allowing agents to receive a compact, reusable structural model rather than repeatedly exploring the repository. Future versions will expand Git visualization into full architectural diff visualization showing how architecture changes across commits.

RepoMap addresses a concrete inefficiency in how modern coding agents work. Currently, agents spend significant effort reconstructing project architecture by opening files, following imports, and inspecting folder structures—a repetitive task that consumes thousands of tokens per session despite being largely deterministic. The tool solves this by separating repository structure extraction from architectural reasoning: a dedicated analyzer identifies imports, module relationships, and definitions without invoking an LLM, producing a compact structural representation that captures the repository's layout. The LLM then operates on this pre-computed model in a single reasoning step, dramatically reducing token usage while enabling richer architectural representations.

The design reflects a practical insight: finding imports, discovering modules, and extracting definitions are deterministic operations that do not require language model intelligence. By offloading this work to a conventional software scanner, RepoMap frees the LLM's context window for actual architectural reasoning—assigning roles, identifying patterns, improving labels, and generating visualization layouts. The tool also preserves source code privacy by ensuring that no actual code is sent to the LLM, only structural metadata. Its integration with AI agents like Claude and OpenCode, plus its interactive visualization for human exploration and Git-aware branch browsing, positions it as infrastructure for both immediate agent efficiency and future architectural diff capabilities.

No comments yet. Be the first to share your thoughts!