Agent skill

Roam

by Cranot in Cranot/roam-code

Codebase comprehension via roam-code CLI. An agent skill from Cranot/roam-code.

Apache-2.0Auto-check passedDevelopment

Install Roam

skills CLI
$ npx skills add Cranot/roam-code --skill roam -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install Cranot/roam-code roam --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/Cranot/roam-code.git skills-src && mkdir -p .claude/skills && cp -r skills-src/skills/roam .claude/skills/roam && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
roam
GitHub stars
517
Token cost
~2.4k tokens
SKILL.md length
887 words
Files
1
Skills in repo
9
Repo updated
First seen
Licence
Apache-2.0

At a glance

Codebase comprehension via roam-code CLI. An agent skill from Cranot/roam-code.

  • Works in 4 steps: Orientation (first time in a repo) → Before Making Changes → After Making Changes → …
  • Exploring codebases
  • SKILL.md covers Setup, Command Decision Table, Core Workflow and Output Modes, plus 4 more sections
  • Calls git and pip

What it does

Roam is an agent skill from Cranot/roam-code. Codebase comprehension via roam-code CLI. Use when exploring codebases, planning modifications, debugging failures, assessing PR risk, or checking architecture health. Triggers on: understanding project structure, pre-change safety checks, finding symbols/files, blast radius analysis, affected tests, health scoring, refactoring guidance, code review. Requires roam-code installed (pip install roam-code) and an indexed project (roam init).

Its SKILL.md is about 2.4k tokens, which your agent loads only when the skill is triggered. It is a single SKILL.md file with no bundled scripts.

It sits in Development, covering Refactoring, Debugging and Code review. It works with Model Context Protocol and SQLite. The repository describes itself as: Local codebase intelligence CLI + MCP server for AI coding agents: SQLite code graph, 28 languages, 287 commands, 246 MCP tools, change-safety gates, audit evidence, zero API keys. The licence is Apache-2.0.

When your agent uses it

  • Exploring codebases
  • Planning modifications
  • Debugging failures
  • Assessing PR risk

Example prompts

  • “/roam”

Requirements

  • Python 3

Workflow steps

4 steps, taken from the step headings in SKILL.md.

  1. Orientation (first time in a repo)
  2. Before Making Changes
  3. After Making Changes
  4. Debugging

What it can do on your machine

Read from SKILL.md and the folder at commit 4856519. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    Shell commands in SKILL.md call:

    • git
    • pip

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md. Its commands use git and pip, which can reach the network depending on how they are called.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Roam loads about 2.4k tokens when it runs. Until then it costs about 113 tokens; SKILL.md has 887 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~113
When it runs · the whole SKILL.md, loaded when a task matches
~2.4k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from Cranot/roam-code at commit 4856519, republished under its Apache-2.0 licence (© Cranot). 887 words, ~2,399 tokens.

Download SKILL.mdSave it as .claude/skills/roam/SKILL.md (or your agent's skills folder).
name
roam
description
Codebase comprehension via roam-code CLI. Use when exploring codebases, planning modifications, debugging failures, assessing PR risk, or checking architecture health. Triggers on: understanding project structure, pre-change safety checks, finding symbols/files, blast radius analysis, affected tests, health scoring, refactoring guidance, code review. Requires roam-code installed (`pip install roam-code`) and an indexed project (`roam init`).

Roam — Codebase Comprehension Skill

Repository: https://github.com/Cranot/roam-code

Roam pre-indexes codebases into a semantic graph (symbols, dependencies, call graphs, architecture layers, git history) stored in a local SQLite DB. Query it via CLI instead of repeatedly grepping files and guessing structure.

Setup

Ensure roam-code is installed and the project is indexed:

bash
pip install roam-code   # or: pipx install roam-code
cd <project-root>
roam init               # indexes codebase, creates .roam/index.db

After git pull or major changes, run roam index to refresh (incremental, near-instant if few files changed). After large refactors: roam index --force.

Command Decision Table

Use this table to pick the right command for the situation:

SituationCommand
First time in a reporoam understand then roam tour
Need a compact codebase overviewroam map or roam minimap
Find a symbol by nameroam search <pattern>
Need files to read for a symbolroam context <symbol>
Inspect a file's structureroam file <path>
Inspect a directoryroam module <path>
Before modifying a symbolroam preflight <symbol>
What breaks if I change X?roam impact <symbol>
Blast radius of uncommitted changesroam diff
Debugging a failureroam diagnose <symbol>
Which tests cover a symbol?roam affected-tests <symbol>
Check codebase healthroam health
Find hotspots (churn x complexity)roam weather
Detect dead/unused coderoam dead
PR risk assessmentroam pr-risk
Find dependency pathsroam trace <source> <target>
Who calls/imports this?roam uses <symbol> (alias: roam refs)
Find every reference to X (replaces multi-shape grep)roam refs <symbol>
Algorithm anti-patternsroam algo
Side effects of a functionroam effects <symbol>
Safe to delete?roam safe-delete <symbol>
Simulate a refactor`roam simulate move

Core Workflow

1. Orientation (first time in a repo)
bash
roam understand        # tech stack, architecture, health, conventions
roam tour              # onboarding: key symbols, reading order, entry points
roam map               # project skeleton with top symbols by PageRank
2. Before Making Changes

Always run roam preflight <symbol> before modifying code. It combines blast radius + affected tests + complexity + coupling + fitness into one check:

bash
roam preflight MyClass
# Output: blast radius, affected tests, complexity, coupling, fitness verdict

If you only need files to read:

bash
roam context MyClass
# Output: definition file + callers + callees with exact line ranges
3. After Making Changes
bash
roam diff              # blast radius of uncommitted changes
roam diff --staged     # blast radius of staged changes
roam pr-risk           # risk score (0-100) + suggested reviewers
4. Debugging
bash
roam diagnose <symbol>  # root cause ranking by z-score risk
roam trace <A> <B>      # dependency path between two symbols
roam effects <symbol>   # DB writes, network I/O, filesystem, global mutation

Output Modes

  • Default: Human-readable text (also optimized for LLM consumption)
  • roam --json <cmd>: Structured JSON with consistent envelope
  • roam --budget N <cmd>: Token-capped output (N = max tokens)
  • roam complexity --select '.symbols[:5]': Project one bounded JSON field without shell parsing (--select is repeatable)
  • roam grep <pattern> -C 5: Search source and return bounded live code packets in one call
  • roam grep <pattern> --whole-symbol --max-packets 3: Deduplicate hits into enclosing functions/classes; stale spans fall back safely
  • roam --sarif <cmd>: SARIF 2.1.0 for CI integration

Prefer --json when you need to parse output programmatically. Prefer --budget 2000 when context window is tight. Prefer --select '.summary' or a bounded list slice when only one envelope section is needed.

Key Commands Reference

roam search <pattern>

Find symbols by name (regex). Results ranked by PageRank.

bash
roam search "Auth.*Service"
roam search "handle_request" --kind fn
roam context <symbol>

AI-optimized file list with line ranges for reading. Supports --task modify|debug|review for context tuning.

bash
roam context Flask
roam context myfile:MyFunction    # disambiguate with file prefix
roam preflight <symbol|file>

Compound pre-change check. Run this before every modification.

bash
roam preflight UserController
roam preflight src/auth/login.py
roam health

Composite score (0-100). Use --gate for CI (reads .roam-gates.yml).

bash
roam health
roam health --gate               # exit 5 on failure
roam diff

Blast radius of uncommitted or committed changes.

bash
roam diff                       # uncommitted
roam diff --staged              # staged only
roam diff HEAD~3..HEAD          # commit range
roam algo

Detect algorithm anti-patterns (23 patterns: O(n^2) loops, N+1 queries, quadratic string building, etc.) with confidence levels and fix suggestions.

bash
roam algo
roam algo --confidence high     # high-confidence only
roam algo --task nested-lookup  # specific pattern
roam impact <symbol>

Full blast radius using Personalized PageRank.

bash
roam impact Flask
roam symbol <name>

Symbol definition + callers + callees + metrics.

bash
roam symbol open_db
roam symbol --full open_db      # include source code
roam affected-tests <symbol|file>

Trace reverse call graph to find covering tests.

bash
roam affected-tests UserService
roam agent-export --write

Auto-generate agent instructions for the project. Detects CLAUDE.md, AGENTS.md, .cursor/rules, etc.

bash
roam agent-export --write
roam agent-export --brief           # compact top-level summary
Show full SKILL.md (352 more words)Show less
roam minimap --update

Inject/refresh annotated codebase snapshot in CLAUDE.md.

bash
roam minimap --update           # update sentinel block in CLAUDE.md

Discovering More Commands

This skill covers the most common commands, but roam has 287 commands. To explore what's available:

bash
roam --help                 # list all available commands
roam <command> --help       # detailed usage for a specific command

For full documentation, examples, and the latest features, see the roam-code repository.

Tips

  • One roam command replaces 5-10 grep/read cycles. Always try roam first.
  • Use roam search instead of grep/glob for finding symbols — it understands definitions vs. usage and ranks by importance.
  • roam context gives exact line ranges — more precise than reading whole files.
  • After git pull, run roam index to keep the graph fresh.
  • For disambiguation, use file:symbol syntax: roam symbol myfile:MyClass.

"Find every reference to X" — prefer roam refs over multi-shape grep

A common agent pattern is:

Grep(pattern: "->ekfpa|\.ekfpa\b|'ekfpa'|\"ekfpa\"")

The intent is "find all references to symbol ekfpa". The multi-shape regex tries to catch function calls (->ekfpa), attribute access (.ekfpa), and string literal mentions ('ekfpa', "ekfpa"). It works, but:

  • False positives. Matches comments, docstrings, and unrelated string literals — the agent must filter those out manually.
  • Unstructured. Returns raw line text; the agent has to parse to learn which symbol owns each match.
  • Misses one-off shapes. Ruby obj.ekfpa!, Python f-string f"{ekfpa}", decorator @ekfpa, etc. each need another regex shape.

roam refs <symbol> (alias for roam uses) walks the indexed call/import/ inherit graph and returns only real references — every result is a named symbol with kind/file/line, grouped by edge type:

$ roam refs find_symbol
VERDICT: 'find_symbol': 50 production consumers, 7 test consumers in 27 files

-- Called by (30) --
fn  affected_tests   src/roam/commands/cmd_affected_tests.py:230  production
fn  annotate         src/roam/commands/cmd_annotate.py:21         production
…
-- Imported by (20) --
…

Latency on this repo: ~700ms via subprocess, sub-100ms via the MCP server (roam_uses tool, which agents in MCP-enabled clients should prefer because the import-cost is paid once at server start). 2-5× slower than ripgrep in raw wall-time, but the result is already usable — there's no follow-up "now read the matching files and figure out the structure" step.

Use roam refs when:

  • Finding every caller / importer / inheritor of a symbol.
  • Planning an API change ("what would break if I rename X").
  • Sweeping for usages before a deletion.

Stay with grep / Grep when:

  • The target is a literal string, not a symbol (e.g. an error message, a translation key, a SQL fragment).
  • The codebase isn't indexed yet (roam init first if you'll be doing many of these queries).

© Cranot, Apache-2.0. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

Just SKILL.md in skills/roam of Cranot/roam-code.

Open the folder on GitHubat commit 4856519

Compare with similar skills

Roam next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Roam compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Roam this skillCranot/roam-code517—~2.4kAutomated safety check: PassApache-2.0
Code Review Graph Navigatorhandsontable/handsontable22k—~939Automated safety check: PassCustom licence
Misakanet Failure MemoryIkalus1988/MisakaNet524—~1.9kAutomated safety check: PassApache-2.0
Batchys2-streamstore/claude-batch-toolkit160—~1.9kAutomated safety check: PassNone
Synapse UsageS1LV4/th0th136—~2.9kAutomated safety check: PassMIT
Copilot Code Coachtimothywarner/chatgptclass143—~1.9kAutomated safety check: PassCustom licence

Similar skills

  • Code Review Graph Navigator

    handsontable/handsontable

    Queries a pre-built, Tree-sitter-based code graph of the whole monorepo instead of grepping call chains, for exploring, debugging, refactoring or reviewing code.

    22k GitHub stars~939 tokensUpdated today
    DevelopmentAuto-check passed
  • Misakanet Failure Memory

    Ikalus1988/MisakaNet

    Search and record failure-recovery lessons from real engineering sessions; submit and verify debugging lessons across the MisakaNet network.

    524 GitHub stars~1.9k tokensUpdated today
    DevelopmentAuto-check passed
  • Batchy

    s2-streamstore/claude-batch-toolkit

    Send non-urgent tasks to Claude's Batch API at 50% off. An agent skill from s2-streamstore/claude-batch-toolkit.

    160 GitHub stars~1.9k tokensUpdated 7 mo ago
    DevelopmentAuto-check passed
  • Synapse Usage

    S1LV4/th0th

    Use the th0th Synapse cognitive modulation layer to get focused, low-noise retrieval during multi-step coding tasks.

    136 GitHub stars~2.9k tokensUpdated 3 mo ago
    DevelopmentAuto-check passed
  • Copilot Code Coach

    timothywarner/chatgptclass

    Socratic coding tutor powered by GitHub Copilot. An agent skill from timothywarner/chatgptclass.

    143 GitHub stars~1.9k tokensUpdated 18 days ago
    DevelopmentAuto-check passed
  • Code Reviewer

    antonbabenko/deliberation

    Find bugs, security holes, and maintainability issues in a diff or file.

    169 GitHub stars~881 tokensUpdated today
    DevelopmentAuto-check passed

More from Cranot/roam-code

All 9 skills in this repo
  • Roam Agent Guidance

    Cranot/roam-code

    Review and maintain the technical instructions Roam gives coding agents: shipped skills, tool descriptions, preset guidance and generated instruction blocks.

    517 GitHub stars~1.3k tokensUpdated 4 days ago
    Auto-check passed
  • Roam Evidence Hardening

    Cranot/roam-code

    Investigate and harden Roam detectors, CLI/MCP result contracts, and evidence consumers when dogfooding or correcting incomplete, misleading, or inconsistent analysis.

    517 GitHub stars~1.5k tokensUpdated 4 days ago
    Auto-check passed
  • Roam Lesson Maintenance

    Cranot/roam-code

    Turn a reproduced or recurring Roam failure into a durable correction, regression control or narrowly scoped project skill, and reconcile conflicting lessons.

    517 GitHub stars~1.2k tokensUpdated 4 days ago
    Auto-check passed
  • Roam Measurement Design

    Cranot/roam-code

    Design or interpret a comparison of Roam performance, detector accuracy, retrieval or workflow value.

    517 GitHub stars~1.2k tokensUpdated 4 days ago
    Auto-check passed
  • Roam Milestone Planning

    Cranot/roam-code

    Define or revise a Roam product milestone and its engineering, adoption and offer-readiness sequence.

    517 GitHub stars~1.2k tokensUpdated 4 days ago
    Auto-check passed
  • Roam Release Readiness

    Cranot/roam-code

    Qualify a Roam commit or accumulated batch for package, website, or server publication; reconcile source, tests, review, CI and deployed identities, and identify the next authorized release step.

    517 GitHub stars~1.7k tokensUpdated 4 days ago
    Auto-check passed

Categories

Questions about Roam

What does Roam do?

Codebase comprehension via roam-code CLI. An agent skill from Cranot/roam-code. Roam is an agent skill from Cranot/roam-code. Codebase comprehension via roam-code CLI.

When should I use Roam?

Roam fits situations like: exploring codebases; planning modifications; debugging failures; assessing PR risk.

How do I install Roam in Claude Code?

Run `npx skills add Cranot/roam-code --skill roam -a claude-code`. Or copy the skill folder (skills/roam in Cranot/roam-code) into .claude/skills/roam in your project. Claude Code loads it when a task matches its description.

How do I install Roam in Codex?

Run `npx skills add Cranot/roam-code --skill roam -a codex`. Or copy the skill folder (skills/roam in Cranot/roam-code) into .agents/skills/roam in your project. Codex loads it when a task matches its description.

Can I use Roam in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add Cranot/roam-code --skill roam -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/roam, .gemini/skills/roam, .github/skills/roam and .opencode/skills/roam in your project.

What does Roam need to run?

Going by SKILL.md and its folder, Roam needs the command-line tools its instructions call (git and pip). Our summary lists: Python 3.

Does Roam access the network?

SKILL.md contains no URLs. Its commands use git and pip, which can reach the network depending on how they are called. This is read from the text; nothing was executed.

Is Roam safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Roam use?

Roam is published under the Apache-2.0 licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Roam use?

About 2.4k tokens (SKILL.md is roughly 9.6k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Roam?

Skills that share tags, products or a category with Roam: Code Review Graph Navigator (handsontable/handsontable, 22k stars), Misakanet Failure Memory (Ikalus1988/MisakaNet, 524 stars), Batchy (s2-streamstore/claude-batch-toolkit, 160 stars) and Synapse Usage (S1LV4/th0th, 136 stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Roam?

Cranot (a GitHub user) maintains it in Cranot/roam-code, which has 517 GitHub stars. The repository holds 9 skills in this directory. The repository was last updated on October 3, 2026.

Source: Cranot/roam-code on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.