by Cranot
Architectural intelligence layer for AI coding agents. Structural graph, architecture governance, multi-agent orchestration, vulnerability mapping. 139 commands, 101 MCP tools, 26 languages, 100% local.
# Add to your Claude Code skills
git clone https://github.com/Cranot/roam-codeThe architectural intelligence layer for AI coding agents. Structural graph, architecture governance, multi-agent orchestration, vulnerability mapping, runtime analysis -- one CLI, zero API keys.
140 commands · 102 MCP tools · 27 languages · 100% local
Roam is a structural intelligence engine for software. It pre-indexes your codebase into a semantic graph -- symbols, dependencies, call graphs, architecture layers, git history, and runtime traces -- stored in a local SQLite DB. Agents query it via CLI or MCP instead of repeatedly grepping files and guessing structure.
Unlike LSPs (editor-bound, language-specific) or Sourcegraph (hosted search), Roam provides architecture-level graph queries -- offline, cross-language, and compact. It goes beyond comprehension: Roam governs architecture through budget gates, simulates refactoring outcomes, orchestrates multi-agent swarms with zero-conflict guarantees, maps vulnerability reachability paths, and enables graph-level code editing without syntax errors.
Codebase ──> [Index] ──> Semantic Graph ──> 139 Commands ──> AI Agent
│ │ │
tree-sitter symbols comprehend
27 languages + edges govern
git history + metrics refactor
runtime traces + architecture orchestrate
No comments yet. Be the first to share your thoughts!
Coding agents explore codebases inefficiently: dozens of grep/read cycles, high token cost, no structural understanding. Roam replaces this with one graph query:
$ 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

$ roam understand # full codebase briefing
$ roam context <name> # files-to-read with exact line ranges
$ roam preflight <name> # blast radius + tests + complexity + architecture rules
$ roam health # composite score (0-100)
$ roam diff # blast radius of uncommitted changes
roam clones: New AST structural clone detection via subtree hashing. Finds Type-2 clones (identical control flow, different identifiers/literals) with Jaccard similarity scoring, Union-Find clustering, and automated refactoring suggestions. More precise than the metric-based duplicates command.print(), breakpoint(), pdb.set_trace(), console.log(), debugger, and System.out.println() in Python, JavaScript, TypeScript, and Java code. All use ast_match type with test file exemptions.SqlExtractor -- tables, columns, views, functions, triggers, schemas, types (enums), sequences, ALTER TABLE ADD COLUMN. Foreign keys produce graph edges; views and triggers reference source tables. Database-schema projects now work with roam health, roam layers, roam impact, roam coupling and all graph commands.ScalaExtractor -- classes, traits, objects, case classes, sealed hierarchies, val/var properties, type aliases, imports, and inheritance. Full extends + with trait mixin resolution.server.json for official MCP Registry submission.roam congestion, roam adrs, roam flag-dead, roam test-scaffold, roam sbom, roam triage, roam ci-setup.roam ci-setup generates pipelines for GitHub Actions, GitLab CI, Azure Pipelines, Jenkins, and Bitbucket.--undocumented mode in intent (wrong DB table), --changed flag in verify (was permanently dead), lazy-load violation in visualize (~500ms penalty), exit code inconsistency in rules, VERDICT-first convention enforced across all commands.roam_explore, roam_prepare_change, roam_review_change, roam_diagnose_issue) reduce multi-step agent workflows to single calls.core, review, refactor, debug, architecture, full) keeps default tool choice tight for agents while retaining full depth on demand.mmap_size, safer large-graph guards, batched writes) reduce first-run and reindex friction on larger repos.roam verify, roam vibe-check, roam ai-readiness, roam ai-ratio) for teams managing agent-written code.Speed. One command replaces 5-10 tool calls (in typical workflows). Under 0.5s for any query.
Dependency-aware. Computes structure, not string matches. Knows Flask has 47 dependents and 31 affected tests. grep knows it appears 847 times.
LLM-optimized output. Plain ASCII, compact abbreviations (fn, cls, meth), --json envelopes. Designed for agent consumption, not human decoration.
Fully local. No API keys, telemetry, or network calls. Works in air-gapped environments.
Algorithm-aware. Built-in catalog of 23 anti-patterns. Detects suboptimal algorithms (quadratic loops, N+1 queries, unbounded recursion) and suggests fixes with Big-O improvements and confidence scores. Receiver-aware loop-invariant analysis minimizes false positives.
CI-ready. --json output, --gate quality gates, GitHub Action, SARIF 2.1.0.
| | Without Roam | With Roam | |--|-------------|-----------| | Tool calls | 8 | 1 | | Wall time | ~11s | <0.5s | | Tokens consumed | ~15,000 | ~3,000 |
Measured on a typical agent workflow in a 200-file Python project (Flask). See benchmarks for more.
Getting Started: What is Roam? · What's New in v11 · Best for · Why use Roam · Install · Quick Start
**Using Roam: