roam — Instant codebase intelligence for AI coding agents

The Problem

Agents explore the same codebase, blind, every session

Without roam

agent-session.log

# Agent explores blindly... Tool: grep "Flask" src/ --recursive Tool: read src/flask/app.py # 963 lines Tool: grep "import Flask" tests/ Tool: read src/flask/__init__.py Tool: grep "FlaskClient" src/ Tool: read src/flask/testing.py Tool: read tests/test_basic.py Tool: grep "def test_" tests/test_basic.py 8 tool calls, ~11s, ~15,000 tokens Incomplete picture of the codebase

With roam

agent-session.log

# Agent queries the index $ roam context Flask Callers: 47 Callees: 3 Affected tests: 31 Files to read: src/flask/app.py:76-963 # definition src/flask/__init__.py:1-15 # re-export src/flask/testing.py:22-45 # FlaskClient.__init__ tests/test_basic.py:12-30 # test_app_factory ...12 more files 1 call, <0.5s, ~3,000 tokens Complete blast radius

Measured on a 200-file Python project. Results vary by codebase size and structure.

When an AI agent opens your repository, it sees files.
Not structure.

It doesn't know that auth_service.py is load-bearing and utils.py is mostly dead code. It doesn't know which symbols are imported by 40 other files and which are imported by none. It doesn't know that the last three bugs all touched the same module.

It finds out by reading. Session after session. That's expensive -- in tokens, in time, and in mistakes made before the picture comes into focus.

roam pre-computes the picture. One index, one query, complete structural understanding.

What it knows

roam models your codebase as a graph -- not text, but a network of what calls what, what changes together, and what breaks what.

Structural graph: Symbols, call edges, inheritance, dependency layers. PageRank identifies the most important code. Tarjan SCC finds circular dependency clusters. Louvain detects natural module boundaries.
Git archaeology: Churn rates, co-change coupling, bus factor, authorship entropy. Which files change together? Which developer owns what? Where are the hidden couplings?
Architecture metrics: Health scores (0-100), cognitive complexity per function, tangle ratios, god component detection. CI quality gates with SARIF output for GitHub Code Scanning.

How it stays safe

Deliberately local. No cloud. No API keys. No telemetry. No network calls. Everything runs on your machine in a SQLite database.

Read-only by default: The index is a queryable snapshot of your codebase structure. Your source code is never modified unless you explicitly run roam mutate --apply.
Works air-gapped: Once installed, no internet access is required. Safe for proprietary codebases, security-sensitive environments, and offline development.
MIT licensed: Open source, no vendor lock-in, no data leaving your machine. Inspect the code yourself.

What it does and doesn't do

What it does

Maps code structure: symbols, call graphs, dependency layers, git history, architecture metrics
Resolves cross-file references using name-based heuristics -- works well for most codebases
Supports 27 languages via tree-sitter, all with full symbol extraction
Detects 23 algorithm anti-patterns with Big-O improvements and language-aware fix suggestions

What it doesn't

Trace runtime behavior, dynamic dispatch, reflection, or eval'd code -- for that, use a profiler
Run a full type system -- a small percentage of call edges may be imprecise in dynamic languages
Replace your linter or security scanner -- roam understands architecture; SonarQube finds bugs; use both
Work magic on tiny projects -- below 10 files, just read them directly

In Practice

Five questions, five commands

Most developers use about 10 commands regularly. Here are the five that matter most.

"What files should I read before changing this?"

$ roam context Flask Files to read (ranked by relevance): src/flask/app.py:76-963 # definition src/flask/__init__.py:1-15 # re-export src/flask/testing.py:22-45 # FlaskClient.__init__ tests/test_basic.py:12-30 # test_app_factory ...12 more files, PageRank-ranked Callers: 47 Callees: 3 Affected tests: 31

"What breaks if I rename this?"

$ roam impact Flask Direct callers: 47 Transitive reach: 89 symbols across 34 files Affected tests: 31 Highest-risk callers (PageRank-weighted): FlaskClient.__init__ src/flask/testing.py:22 PR=0.0124 create_app src/flask/factory.py:8 PR=0.0098 test_app_factory tests/test_basic.py:12 PR=0.0065

"Are there algorithm anti-patterns in this codebase?"

$ roam algo VERDICT: 8 algorithmic improvements found (3 high, 4 medium, 1 low) Nested loop lookup (2): fn resolve_permissions src/auth/rbac.py:112 [high, impact=86.4] Current: Nested iteration -- O(n*m) Better: Hash-map join -- O(n+m) Tip: Build a dict/set from one collection, iterate the other String building (1): meth build_query src/db/query.py:88 [high, impact=74.0] Current: Loop concatenation -- O(n^2) Better: Join / StringBuilder -- O(n) Tip: Collect parts in a list, join once at the end 23 pattern catalog. Language-aware tips for Python, JS, Go, Rust, Java.

"Is this codebase healthy?"

$ roam health Health: 78/100 Tangle ratio: 0.0% (no circular dependencies) God components: 1 (Flask, degree 47) Bottlenecks: 0 Layer violations: 0 Use --gate in CI to enforce thresholds (.roam-gates.yml)

"Is it safe to change this function?"

$ roam preflight Flask === Preflight: Flask === Blast radius: 47 callers, 89 transitive Affected tests: 31 (DIRECT: 12, TRANSITIVE: 19) Complexity: cc=40 (critical), nesting=6 Coupling: 3 hidden co-change partners Fitness: 1 violation (max-complexity exceeded) VERDICT: HIGH RISK -- consider splitting before modifying

Quick Start

Working in under a minute

Install

pip install roam-code

Python 3.9+. Also works with pipx and uv tool install.

Index

cd your-project && roam init

Creates a local SQLite database. ~5s for 200 files. Incremental after that.

Query

roam understand

Full architectural briefing: tech stack, key abstractions, health score, entry points.

Connect your agent

roam mcp-setup claude-code

Generates MCP config for Claude Code, Cursor, Windsurf, VS Code, Gemini CLI, and more. For full client workflows, see integration tutorials.

When not to use roam

The right tool for the job. roam earns its weight at scale -- not everywhere.

Small scripts (<10 files)

Just read the files directly. roam adds overhead without value at this scale.

Pure text search

ripgrep is faster for raw string matching. roam is structural, not textual.

Real-time type checking

Use an LSP (pyright, gopls, tsserver). roam is static and offline.

Works with your tools

Via MCP: Claude Code, Cursor, Windsurf, VS Code + Copilot, Cline, Continue.dev, Gemini CLI. Via CLI: any agent that can run a shell command -- Aider, Codex CLI, custom scripts. Via CI: GitHub Actions, GitLab CI, Azure DevOps. JSON + SARIF output.

27 languages via tree-sitter: Python, TypeScript, JavaScript, Java, Go, Rust, C, C++, C#, PHP, Ruby, Kotlin, and 15 more. All 27 languages have full symbol extraction via native extractors or YAML-defined grammars.

The full surface

roam has 139 CLI commands and 101 MCP tools. That's a lot for a human to memorize. It's not designed for that. It's designed for AI agents, which use commands as a vocabulary -- calling whatever they need, when they need it.

Most developers use about 10 commands directly. The rest are there for your agent. See the full command reference.