Stop Burning Tokens on grep: roam-code Is the AI Agent Brain You Didn't Know You Needed

What if every AI coding agent you deployed could actually see your codebase instead of blindly groping through files?

Here's the dirty secret nobody building with Claude, Cursor, or GitHub Copilot wants to admit: your agents are code-blind. They burn through 15,000 tokens doing what a graph query could answer in 3,000. They ship O(n²) nested loops that pass every test and crater production at scale. They rename a function in one file and miss seventeen clone siblings. You've felt the pain—the post-deploy incident, the 3 AM page, the PR review that caught nothing because reviewers can't hold 200 files in working memory either.

What if there was a local codebase intelligence layer that transformed your repository into a queryable semantic graph—symbols, calls, imports, architecture layers, git history, runtime traces, all in one SQLite database? What if it exposed 238 commands and 224 MCP tools across 28 language families, ran entirely on your machine with zero telemetry, and cut agent token consumption by 80%?

That tool exists. It's called roam-code, and it's about to change how you think about AI-assisted development forever.

What is roam-code?

roam-code is an open-source local codebase intelligence engine created by Cranot and released under the Apache 2.0 license. At its core, it parses your entire repository into a SQLite-backed semantic graph—a dense, queryable model of every symbol, dependency, call relationship, architectural layer, and historical change pattern. Where traditional tools give you text search, roam-code gives you structural comprehension.

The project emerged from a critical observation: modern AI coding agents explore codebases through brute-force iteration—dozens of grep and read_file cycles that explode token budgets and miss structural relationships entirely. roam-code replaces this chaos with single-shot graph queries that answer questions like "what breaks if I edit this?" or "pull the exact spans I need for this task" in under 500 milliseconds.

What's driving its explosive traction now? Three converging forces. First, the MCP (Model Context Protocol) standardization has created demand for structured tool interfaces that agents can actually use. roam-code ships 224 MCP tools with a 92% token overhead reduction in its default core preset—down from ~36K to under 3K tokens. Second, enterprise AI governance is maturing; teams need tamper-evident evidence chains, audit trails, and local execution for regulated environments. roam-code's evidence packets hash-verify offline and work in air-gapped deployments. Third, the multi-agent orchestration wave is here—teams are running parallel agents on the same codebase, and roam-code's lease system, partition engine, and HMAC-chained run ledgers make this safe for the first time.

The ecosystem extends beyond the free CLI. Roam Review (PR bot), Roam Cloud (metrics dashboard), and Roam Self-Hosted (regulated stacks) are paid layers built atop the same open-source engine. But the core graph engine, all 238 commands, and 57 default MCP tools? Forever free and Apache 2.0.

Key Features That Separate roam-code from Everything Else

Structural indexing, not text indexing. roam-code uses tree-sitter parsers across 28 language families to build a genuine symbol graph—not regex-based approximations. It knows that Flask has 47 callers and 31 affected tests; grep only knows it appears 847 times. This distinction is everything.

Algorithmic risk detection—the secret weapon. The roam math (alias roam algo) command detects code that is correct but computationally wrong—the exact failure mode that sinks agent-generated code post-deploy. It finds nested-loop lookups that become O(n²), N+1 database queries, regex compilation inside hot loops, quadratic string concatenation, and 19 other anti-patterns. Each finding includes Big-O improvements, confidence scores, and language-aware fix templates.

MCP-native architecture. The v2 MCP server runs in-process, eliminating per-call subprocess overhead. Four compound operations (roam_explore, roam_prepare_change, roam_review_change, roam_diagnose_issue) collapse multi-step agent workflows to single calls. Preset-based tool surfacing (core, review, refactor, debug, architecture, full) keeps default choices tight while retaining full depth on demand.

Tamper-evident evidence and compliance. Every analysis produces hash-verifiable evidence packets. The cga (Code Graph Attestation) command generates in-toto v1 statements with Merkle roots. Audit trails export to EU AI Act-compatible formats. OSCAL v1.2 artifacts materialize for procurement workflows. This isn't security theater—it's cryptographic proof that lives entirely on your machine.

Multi-agent coordination substrate. The Agent-OS control plane under .roam/ includes constitution files, HMAC-chained run ledgers, multi-agent leases with scope reservation, and four cumulative execution modes (read_only → safe_edit → migration → autonomous_pr). Parallel agents can work the same repo with zero-conflict guarantees.

Performance that scales. Symbol search moved to SQLite FTS5/BM25—typical queries dropped from seconds to tens of milliseconds. Incremental indexing shifted from O(N) full rebuilds to O(changed) updates. First index takes ~5 seconds for 200 files, ~15 seconds for 1,000 files; subsequent runs are near-instant.

Use Cases Where roam-code Absolutely Dominates

1. Agent-Assisted Coding at Scale

When Claude Code or Cursor explores a 500-file repository, the token burn is real—often 8-15 tool calls and 10+ seconds per task. roam-code collapses this to one command under 500ms. The roam retrieve task uses hybrid FTS5 + structural reranking (personalized PageRank + clone-canonical signal) to return exactly the spans an agent needs, with justification tags showing why each span ranked. Token budgets drop 80% without sacrificing context quality.

2. Post-Rename Documentation Hygiene

The killer demo: you git mv docs/old-guide.md docs/new-guide.md, then run roam stale-refs --fix preview to see safe auto-rewrites, and roam stale-refs --fix apply to rewrite every dangling markdown link, HTML href, backtick path, and broken #anchor across the entire repository. It combines git history, basename matching, and LLM enrichment with confidence-tagged hints. Composable with --gate for CI enforcement, --sarif for GitHub Code Scanning, and roam lsp for editor squiggles.

3. Pre-Merge Algorithmic Safety

AI agents ship code that passes tests but fails at scale. The roam math command catches this class of bug before merge—nested loop lookups, N+1 queries, unmemoized recursion, expensive work in render loops. In a 200-file Flask project, it identified 8 algorithmic improvements (3 high-severity) that would have caused production incidents. Each finding includes exact file:line locations, current Big-O, improved Big-O, and implementation tips.

4. Multi-Agent Parallel Development

Running 4 Claude instances on the same monorepo? Without coordination, they'll collide on shared files and produce conflicting changes. roam-code's fleet command uses Louvain community detection + co-change analysis + PageRank anchors to partition the codebase into non-conflicting agent scopes. The lease system reserves file/symbol scopes with automatic expiration. The agent-plan command decomposes partitions into dependency-ordered tasks with merge sequencing and handoffs.

5. Regulatory Compliance and Audit Evidence

For teams under EU AI Act, SOC 2, or internal governance mandates, roam-code produces machine-verifiable evidence. roam attest bundles blast radius, risk scores, breaking changes, fitness metrics, and test coverage into a single signed artifact. roam audit-trail-export generates JSONL chains with SHA-256 integrity verification. roam article-12-check produces 1-page Markdown/PDF readiness assessments. All offline, all local, all cryptographically tamper-evident.

Step-by-Step Installation & Setup Guide

Basic Installation

The fastest path is PyPI with pip or modern Python tooling:

# Standard pip installation
pip install roam-code

# Recommended: isolated environment with pipx
pipx install roam-code

# Or with uv (fastest)
uv tool install roam-code

# From source for bleeding edge
pip install git+https://github.com/Cranot/roam-code.git

Requirements: Python 3.10+, Linux/macOS/Windows. No external databases, no Docker required, no network calls after installation.

Docker Option (Alpine-based)

docker build -t roam-code .
docker run --rm -v "$PWD:/workspace" roam-code index
docker run --rm -v "$PWD:/workspace" roam-code health

First-Time Setup

cd your-project
roam init                  # Creates .roam/ directory, indexes codebase, sets up CI workflow

The init command is your onboarding wizard. It builds the initial index, creates .roam/fitness.yaml for architectural governance, generates a GitHub Action workflow, and shows your baseline health score. First index takes ~5 seconds for 200 files, ~15 seconds for 1,000 files. Subsequent runs are incremental.

Windows-Specific Note

If roam isn't found after uv installation, run:

uv tool update-shell

Then restart your terminal.

AI Agent Integration

Generate agent-specific configuration automatically:

roam describe --write       # Auto-detects CLAUDE.md, AGENTS.md, .cursor/rules, etc.
roam mcp-setup claude-code  # Generate MCP config for Claude Code
roam mcp-setup cursor       # Generate MCP config for Cursor

The --write flag introspects your project structure and emits the appropriate configuration file for your detected agent. The mcp-setup command produces JSON snippets for direct paste into MCP client configurations.

CI/CD Integration

roam ci-setup --platform github-actions --write

Generates a complete workflow with SARIF upload, quality gates, sticky PR comments, and cache-aware execution. Supports GitHub Actions, GitLab CI, Azure Pipelines, Jenkins, and Bitbucket out of the box.

REAL Code Examples from the Repository

Example 1: The Five Verbs That Cover 80% of Agent Workflows

This is the canonical getting-started pattern from the README. Master these five commands and you've unlocked the core value of roam-code:

pip install roam-code

cd your-repo/
roam understand                       # 1. landing pad — what is this codebase?
roam retrieve "where is auth?"        # 2. graph-aware retrieval for free-form tasks
roam context AuthService              # 3. exact files+lines to read before changing
roam preflight AuthService            # 4. blast radius + tests + complexity check
git diff | roam critique              # 5. patch verifier — clones-not-edited, hot-path

What's happening here? roam understand generates a full codebase briefing: tech stack, architecture, key abstractions, health score, conventions, complexity overview, and entry points. This replaces 5-10 read_file calls an agent would otherwise make. roam retrieve uses the hybrid FTS5 + structural reranker to answer natural-language tasks with ranked, justified spans. roam context is surgical—it returns exact file paths with line ranges, not entire files, dramatically cutting tokens. roam preflight computes blast radius (what breaks), affected tests, complexity metrics, and architecture rule violations before you write a line of code. Finally, git diff | roam critique pipes your uncommitted changes through the graph-grounded patch verifier, flagging clone siblings you missed and hot-path risks.

Example 2: Algorithmic Anti-Pattern Detection in Action

The roam algo output is one of the most technically impressive features. Here's the real output format from the repository:

$ roam algo
VERDICT: 8 algorithmic improvements found (3 high, 4 medium, 1 low)
Ordering: highest impact first
Profile: balanced (filtered 0 low-signal findings)

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

  fn   find_matching_rule           src/rules/engine.py:67   [high, impact=78.1]
        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

Branching recursion without memoization (1):
  fn   compute_cost                 src/pricing/calc.py:34   [medium, impact=49.5]
        Current: Naive branching recursion -- O(2^n)
        Better:  Memoized / iterative DP -- O(n)
        Tip: Add @cache / @lru_cache, or convert to iterative with a table

Why this matters: Each finding includes the exact function, file, line number, current Big-O complexity, improved Big-O complexity, and a language-aware implementation tip. The impact score incorporates caller count and runtime trace data when available—so you're not just fixing theoretical problems, you're fixing production-critical paths. The 23-pattern catalog covers everything from bubble sort to matrix multiplication naivety. Run with --sarif for direct GitHub Code Scanning integration, or --json for machine-readable consumption by downstream agents.

Example 3: The Stale-Refs Killer Use Case

This is the demo that converts skeptics. After renaming a file, documentation hygiene is typically manual drudgery or simply neglected:

git mv docs/old-guide.md docs/new-guide.md
roam stale-refs --fix preview     # see what auto-rewrites are safe
roam stale-refs --fix apply       # rewrite README + CHANGELOG + everywhere

The intelligence layer: stale-refs doesn't just string-match filenames. It combines git rename detection, basename similarity scoring, LLM-enriched confidence tagging, and structural awareness of markdown/HTML/backtick syntax. The --fix preview mode shows you exactly what would change before touching anything. The --fix apply mode executes safe rewrites across your entire repository—README, CHANGELOG, inline comments, HTML hrefs, even anchor links.

CI integration is where this becomes infrastructure:

roam stale-refs --gate             # Exit 5 on findings, CI-failable
roam stale-refs --diff             # Only check changed files (speed)
roam stale-refs --baseline-from main  # Acknowledge existing debt
roam stale-refs --watch            # Live monitoring during editing
roam stale-refs --check-external   # Validate HTTP links too
roam stale-refs --sarif            # GitHub Code Scanning format

And the companion roam lsp server puts squiggles directly in your editor for real-time feedback.

Example 4: Agent-Optimized Context Retrieval

When an AI agent needs to understand a symbol before modifying it, raw file contents are wasteful. roam-code returns exactly what's needed:

$ 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           # caller: FlaskClient.__init__
  tests/test_basic.py:12-30            # caller: test_app_factory
  ...12 more files

The token economics: Instead of reading entire files (potentially 10,000+ lines), the agent gets precise line ranges with semantic annotations. The 47 callers and 3 callees are computed from the actual call graph, not text search. The 31 affected tests are transitively reachable through the graph. This is the difference between an agent that guesses context and one that knows context.

Example 5: Minimap for Agent Configuration Injection

The roam minimap command generates a compact, sentinel-wrapped codebase snapshot that can be injected directly into agent configuration files:

roam minimap --update           # Replace sentinel block in CLAUDE.md in-place
roam minimap -o docs/AGENTS.md  # Target a different file
roam minimap --init-notes       # Scaffold project gotchas

Output includes stack identification, annotated directory tree with file counts, key symbols by PageRank, high fan-in symbols to avoid touching (with caller counts), hotspots by churn×complexity, and project conventions. The sentinel comments <!-- roam:minimap --> / <!-- /roam:minimap --> enable idempotent updates—surrounding content is preserved. Add project-specific warnings to .roam/minimap-notes.md and they appear in every subsequent generation.

Advanced Usage & Best Practices

Preset-based MCP tool surfacing. The default core preset exposes 57 tools at under 3K tokens overhead. For specialized workflows, escalate to review (PR analysis), refactor (safe transformation), debug (diagnostic depth), architecture (governance), or full (all 224 tools). Never pay for what you don't use.

Index portability for team consistency. Use roam index-export to create signed, integrity-checked tarballs of your indexed graph. Teammates import with roam index-import—manifest SHA-256 verification ensures identical analysis environments. Counter to Cursor's "92% similar codebase = reuse teammate's index" cloud dependency, this works entirely offline.

Constitution-driven agent governance. The .roam/constitution.yml file is the single source for laws, rules, memory, and gates that all agents read first. Combine with roam mode enforcement (read_only → safe_edit → migration → autonomous_pr) for staged autonomy rollouts. The HMAC-chained run ledger at .roam/runs/ provides non-repudiable execution history.

Personalized PageRank for retrieval quality. The roam retrieve reranker uses NetworkX personalization biased toward query-relevant nodes. Seed with --seed-files to bias toward known-relevant starting points. Tune weights in .roam/config.toml (alpha through epsilon) for domain-specific optimization.

Suppression workflow for false positives. Use roam suppress <finding-id> --reason "..." to record audit-trail-friendly suppressions in .roam/suppressions.json. List and remove workflows included. Never silently ignore—always document with justification.

Comparison with Alternatives

The verdict: Use ripgrep for raw string matching in small projects. Use your LSP for real-time type feedback in your editor. Use Semgrep for hosted security rule enforcement. Use Sourcegraph if you need cross-repository search and can accept cloud dependency. Use roam-code when you need structural intelligence, algorithmic safety, agent-native tooling, multi-agent coordination, compliance evidence, and complete local control—especially for codebases exceeding 100 files where graph queries decisively outperform linear search.

FAQ

Q: Does roam-code work with my language? A: 28 language families with 17 dedicated Tier 1 extractors including Python, JavaScript/TypeScript, Go, Rust, Java, Kotlin, Scala, SQL, PHP (Laravel), Ruby (Rails), Vue SFC, and more. See the full language table in the repository.

Q: How does this compare to just using Cursor's codebase indexing? A: Cursor's index is proprietary, cloud-dependent, and offers no algorithmic risk detection, no tamper-evident evidence, no multi-agent coordination, and no MCP tool surface. roam-code gives you local control, cryptographic verification, and 224 agent-callable tools.

Q: Can I run this in CI/CD pipelines? A: Absolutely. roam ci-setup generates native configs for GitHub Actions, GitLab CI, Azure Pipelines, Jenkins, and Bitbucket. Every command supports --json, --sarif, and --gate (exit 5 on failure) for programmatic integration.

Q: Is my source code sent anywhere? A: Never. The entire graph lives in .roam/index.db—a local SQLite file. No telemetry, no network calls, no cloud dependency. Evidence packets hash-verify offline. Works in air-gapped environments.

Q: How do I handle false positives from roam algo or roam smells? A: Use roam suppress <finding-id> --reason "..." to record audit-trail-friendly suppressions. All suppressions are documented, reversible, and exportable for compliance review.

Q: Can multiple AI agents work on the same repo simultaneously? A: Yes. The roam lease system reserves file/symbol scopes. roam fleet partitions by community detection. roam agent-plan sequences merge operations. Zero-conflict guarantees with proper use.

Q: What's the performance on large monorepos? A: Incremental indexing is O(changed), not O(N). First index: ~5s for 200 files, ~15s for 1,000 files. Queries typically run in tens of milliseconds. The soft cap is 20,000 symbols; hard cap at 100,000.

Conclusion

The future of AI-assisted development isn't agents with bigger context windows—it's agents with actual comprehension. roam-code delivers that comprehension by transforming your codebase from a pile of files into a queryable, verifiable, governable semantic graph. The token savings alone justify adoption: 80% reduction in typical agent workflows. But the real value is safety—catching algorithmic time bombs before merge, ensuring documentation hygiene after renames, and producing cryptographic evidence that satisfies regulators and sleep-deprived on-call engineers alike.

The Apache 2.0 CLI is free forever. The 224 MCP tools are ready for your Claude, Cursor, Copilot, or custom agent. The graph is yours—local, offline, and completely under your control.

Stop burning tokens on grep. Give your agents the structural sight they need.

👉 Get roam-code on GitHub — star it, install it with pip install roam-code, and run roam init in your project today. Your future self—and your production systems—will thank you.