<2-3 sentences summarising what the project addresses and solves, the target audience, and the benefit.> Roam provides an architectural intelligence layer for AI coding agents, transforming codebases into queryable semantic graphs. It enables efficient code exploration, architecture governance, multi-agent orchestration, and vulnerability analysis, operating entirely locally. This empowers developers and AI agents with deep, structural understanding of software projects, significantly reducing manual analysis time and token consumption.

How It Works

Roam indexes codebases by parsing 26 languages via tree-sitter into Abstract Syntax Trees (ASTs), extracting symbols and references. These are resolved into a local SQLite-based semantic graph, enriched with Git history, runtime traces, and computed metrics like PageRank and complexity. Advanced graph algorithms and a catalog of 23 anti-pattern detectors enable deep analysis of code structure, dependencies, and potential performance bottlenecks.

Quick Start & Requirements

Install via pip, pipx, or uv (pip install roam-code). Requires Python 3.9+. Run roam init in a project directory to index the codebase and generate a CI workflow. Initial indexing for 200 files takes ~5s, scaling to ~15s for 1,000 files; subsequent updates are near-instant.

Highlighted Details

• 100% Local Operation: No API keys, telemetry, or network calls; suitable for air-gapped environments.
• AI Agent Integration: Generates LLM-optimized, token-efficient output (plain ASCII, JSON) for seamless agent consumption.
• Cross-Language Analysis: Supports 26 languages with dedicated parsers and cross-language edge detection.
• Architectural Governance: Enforces quality gates, architectural budgets, and fitness functions via CI-ready commands.
• Multi-Agent Orchestration: Partitions codebases for parallel agent execution with zero-conflict guarantees.
• Vulnerability Mapping: Identifies and traces vulnerability reachability paths.
• Algorithm Anti-Pattern Detection: Catalog of 23 common suboptimal algorithms with suggested Big-O improvements.
• Runtime Trace Overlay: Integrates production trace data for dynamic hotspot analysis.
• Graph-Level Code Editing: roam mutate enables safe refactoring operations like moving or renaming symbols across the codebase.

Maintenance & Community

Actively developed with a detailed roadmap and frequent updates. No explicit community channels or contributor details are provided in the README.

Licensing & Compatibility

Distributed under the permissive MIT License, allowing for commercial use and integration into closed-source projects.

Limitations & Caveats

Static analysis limitations apply, particularly for dynamic dispatch and reflection, though runtime trace ingestion mitigates this. Import resolution is heuristic and may struggle with complex re-exports. Cross-language edge support is limited to specific integrations. Tier 2 languages offer only basic symbol extraction.