rmap

Codebase map CLI. Compact, parsed, friendly to humans and LLM tooling.

Rust-aware today. tree (no --detail) works on any repo. Item parsing, refs, deps, graph are Rust-only (parsed via syn). Other languages render as bare file names. Respects .gitignore in or out of a git work tree.

Install

cargo install rmap

Subcommands

Quick start

Orient on an unfamiliar repo:

rmap tree --depth 2                # shape of the repo
rmap tree --detail                 # tree + Rust items per .rs file
rmap tree --detail --lines         # add :start-end ranges, :LOC per file

Drill into a subtree or file:

rmap module computer               # fuzzy: any unique path suffix
rmap module src/domain/hull        # exact directory
rmap module src/walk.rs            # single-file item index

Find an identifier:

rmap refs enumerate                # all defs + uses
rmap refs Filter --defs-only       # where defined?
rmap refs render_file --uses-only  # who calls?

Trace dependencies:

rmap deps                          # whole-repo forward graph
rmap deps --reverse                # who imports each file
rmap deps --ext                    # include external crate edges
rmap deps src/walk.rs              # focus: in/out/ext for one file
rmap graph                         # brace tree from crate root
rmap graph src/walk.rs --reverse   # who reaches walk.rs?
rmap graph --mermaid               # mermaid `graph TD` block

Output samples

rmap tree --detail:

src {
  parse.rs { struct ParseOptions, fn render_file, fn render_str, fn render_items }
  walk.rs { enum Node { fn name }, struct Filter, fn enumerate, fn list_paths }
}

rmap tree --detail --lines:

walk.rs:200 { enum Node:13-24 { fn name:27-31 }, struct Filter:34-42,
              fn enumerate:44-67, ... }

rmap refs Filter:

src/main.rs:396:24 use struct-lit Filter
src/refs.rs:28:25  use import     Filter
src/walk.rs:37:12  def struct     Filter
src/walk.rs:47:40  use type       Filter

rmap refs Filter --excerpt 1 (with source context):

src/walk.rs:37:12 def struct Filter
    36 | #[derive(Default)]
  > 37 | pub struct Filter {
    38 |     /// Skip paths whose relative path contains any of these substrings.

rmap refs Filtr (typo → suggestion):

no hits for `Filtr`
did you mean: Filter, filter?

rmap deps src/walk.rs:

src/walk.rs
  out: -
  in:  src/refs.rs, src/render.rs

rmap graph --depth 2:

src/main { deps, graph { deps* }, parse, refs { walk }, render { parse*, walk* }, walk* }

Markers: * revisit, ~ back-edge, {…} depth limit hit.

Teach an AI agent

rmap agent >> CLAUDE.md            # or AGENTS.md, .cursorrules, ...

Prints a short markdown snippet telling Claude/Cursor/Codex/... to reach for rmap instead of find/ls/tree when locating code.

Flags reference

Run rmap --help for the full surface. Highlights:

tree

• --depth N, --detail, --lines
• --cap PREFIX=N (repeatable, default docs/sessions=10), --no-default-caps
• --exclude SUBSTR (repeatable), --ext rs,md
• --detail implicitly caps depth at 4 unless --depth is given.

module

• --depth N, --lines, --ext rs,md
• Positional args: exact dir, exact file, or unique path suffix. Multiple args render in order, blank line between.

refs <NAME>...

• --in PATH, --defs-only, --uses-only, --excerpt N
• Output: file:line:col role kind name. role ∈ def|use.
• --excerpt N appends ±N source lines around each hit; the hit line is marked >.
• def kinds: fn, method, struct, enum, union, trait, const, static, type, macro.
• use kinds: call, method, type, struct-lit, path, macro, import, pat.
• Matches by trailing path segment only — no name resolution. Scope with --in PATH to disambiguate.
• Zero hits → did you mean: ... suggestions ranked by token overlap, prefix, bigram similarity, edit distance.

deps [PATH]

• --reverse, --ext
• PATH selects scope: dir with Cargo.toml (whole repo), subdirectory (scoped subtree, repo auto-detected), or .rs file (focus mode: in/out/ext).
• Whole-repo / scoped output: file -> dep1, dep2, ....
• Resolves crate::, self::, super:: against the mod tree from src/main.rs or src/lib.rs. Single-crate only — workspaces not parsed.

graph [ENTRY...]

• --reverse, --mermaid, --depth N, --ext
• Zero or more entries (each renders its own subgraph; default = detected crate root).
• Default output: single-line brace tree. Reuses the deps graph and follows mod x; edges too.

License

MIT.