Cranot/roam-code — roam-code: Local-First Codebase Intelligence for AI Agents
Transcript
QuickFacts
Welcome! Today we're exploring roam-code, a tool built to help AI coding agents understand what they're about to change before they change it. Think of it as a pre-flight checklist for code edits, powered by a local knowledge graph.
PlainEnglish
roam-code indexes your codebase into a local SQLite database, creating a searchable graph of functions, classes, imports, and calls. AI agents can then query this graph to understand blast radius, complexity, and which tests might break—all without sending your code to the cloud. It's like giving agents a city map instead of making them wander the streets.
QuickFacts
Under the hood, roam-code is a Python application built on Click for the CLI and tree-sitter for parsing twenty-eight different languages into abstract syntax trees. It stores everything in a local SQLite database, runs graph algorithms with NetworkX to find cycles and clusters, and exposes those capabilities to AI tools through a FastMCP server. The stack is designed to work entirely offline once the grammar pack is downloaded.
Architecture
Let's trace the architecture. You interact through either the CLI or the MCP server—both talk to the same command layer underneath. The indexer pipeline scans your repo, parses files, and writes symbols and edges into SQLite. Graph algorithms enrich that data with PageRank scores and cluster IDs. When you query, commands pull from the database and return structured results. The Agent OS substrate wraps around the MCP server to enforce mode policies, log every action, and emit tamper-evident receipts.
Architecture
The indexing pipeline runs in six steps. First, discovery finds all files using git ls-files, which respects your gitignore. Next, each file is parsed into an abstract syntax tree using tree-sitter. Then language-specific extractors pull out symbols like functions and classes, along with references like imports and calls. The resolve step matches those references to actual symbol IDs and creates edges. Metrics are computed—complexity, churn from git history, and PageRank for centrality. Finally, the index is written to SQLite and ready to query. On a two-hundred-file repo, this takes under five seconds.
PlainEnglish
Let's talk about why preflight matters. Imagine an agent asked to refactor a function. Without preflight, it edits blindly, breaks seventeen downstream callers, discovers no test coverage, and the fixes take hours to untangle. With preflight, the agent queries blast radius first, sees a critical risk with six hundred eighty-one tests affected, and decides to ask for human review instead. The graph stops the agent before the damage happens. It's like a pilot's checklist—you don't take off until you've verified the plane is safe.
Architecture
Here's how an MCP tool call flows. Claude Code invokes roam preflight with a symbol name. The MCP server checks the active mode policy to see if preflight is allowed in safe edit mode. It is, so the server spawns a subprocess running the actual roam preflight command. The CLI returns a JSON envelope with the verdict. The MCP server redacts any secrets from the output—think GitHub tokens or AWS keys—then computes an HMAC receipt proving what was returned. That receipt gets logged to the run ledger at dot roam slash runs. Finally, the result and receipt go back to the agent. Every action is gated, logged, and provable.
Architecture
The database schema centers on symbols and edges. Symbols are functions, classes, and methods—they belong to files. Edges capture relationships: this function calls that function, this class inherits from that interface. Symbol metrics track complexity and PageRank scores. Git commits and git cochange tables record history: who changed what, when, and which files often change together. The schema is currently at user version eighteen, up from thirteen in earlier releases, with sixteen core tables and twenty indexes for fast queries.
Architecture
roam-code defines four cumulative agent modes. Read-only lets an agent query the graph but not change files. Safe-edit adds permissions to write files and run tests—this is the default for most agents. Migration mode adds commands for planning database schema changes and bulk refactors. Autonomous PR mode allows the agent to commit, attest changes, and prepare pull request bundles with all the evidence attached. Each mode builds on the previous one, and the active mode is stored in dot roam slash active mode.
Community
The community pulse shows active development. The last commit was yesterday, with forty-two commits in the past thirty days and over five hundred in the last year. Three contributors have been active in the last ninety days, with a core maintainer driving most of the work—four hundred eighty-seven commits. There are eight branches and forty-seven tags, suggesting a release cadence with semantic versioning. This is a well-maintained project with steady momentum.
PlainEnglish
roam-code is local-first intelligence for AI coding agents. No API keys, no cloud dependencies, just a SQLite graph built from your source and git history. Agents query blast radius, complexity, and test coverage before changing a line, and every action is logged with tamper-evident receipts. It's the pre-flight checklist that keeps agents safe—and gives reviewers proof they checked first. Thanks for exploring with us!
How this was made
Lenzon read Cranot/roam-code and generated this walkthrough automatically. The narration above is the transcript of what it says.
Explain a pull request from your own repo
Point Lenzon at a repo or a pull request and get a narrated walkthrough like this one.
Try it