pi-rbtr

A pi extension package that gives the LLM access to rbtr's structural code index. The agent can search by name, keyword, or concept, read symbol source, list file structure, trace dependency edges, and compare structural changes between git refs — without constructing shell commands or parsing raw output.

Install

The extension requires the rbtr CLI. Install both:

# Install rbtr (the code index)
uv tool install rbtr

# Install the pi extension
pi install npm:@janrito/pi-rbtr

For development from a local clone (no global install):

# Install the extension from the local checkout
pi install -l ./packages/pi-rbtr

# Point the extension at the local rbtr source
# (in .pi/rbtr-index.json)
{ "command": "uvx --from ./packages/rbtr" }

What the agent gets

Eight tools, registered automatically on session start:

| Tool | Description | | ---------------------- | ------------------------------------------------------------------------------------------------------------------------ | | rbtr_search | Search by name, keyword, or concept (BM25 + semantic + name fusion). Optional keywords/variants for query expansion. | | rbtr_read_symbol | Read a symbol's full source by name | | rbtr_list_symbols | Structural table of contents for a file | | rbtr_find_refs | Find references via the dependency graph (imports, docs) | | rbtr_changed_symbols | Symbols that changed between two git refs | | rbtr_watch | Watch refs and keep them indexed (background, incremental) | | rbtr_status | Check whether the index exists and how many symbols it contains | | rbtr_gc | Reclaim index storage. Destructive; previews as a dry run unless told otherwise |

The extension also injects a system prompt note so the agent knows the index is available without being told.

When to use which tool

• Concept query ("how does authentication work") → rbtr_search with keywords and variants. More precise than grep for semantic queries. The LLM generates expansion terms automatically via promptGuidelines.
• Known symbol ("read the source of fuse_scores") → rbtr_read_symbol. Faster than finding the file and reading it.
• File structure ("what's in config.py?") → rbtr_list_symbols. One-line-per-symbol TOC with line ranges.
• Exact string match ("find all TODO comments") → grep. The index is structural, not textual.
• Who calls X? → rbtr_find_refs. Follows import and doc edges in the dependency graph.
• What changed? → rbtr_changed_symbols. Function-level diff between two refs, not line-level.

Tool examples

Shapes, not fixtures — the line numbers and scores below move with the code they describe.

rbtr_search — query in, scored results out:

{"kind": "search", "results": [
  {"name": "fuse_scores", "kind": "function", "file_path": "src/rbtr/index/search.py",
   "line_start": 298, "line_end": 380, "content": "def fuse_scores(...):\n    ...", "score": 0.49}
]}

The per-signal ranking breakdown is omitted by default; pass explain: true to include a nested signals object.

rbtr_read_symbol — symbol name in, full source out:

{"kind": "read_symbol", "chunks": [
  {"name": "fuse_scores", "kind": "function", "file_path": "src/rbtr/index/search.py",
   "line_start": 298, "line_end": 380, "content": "def fuse_scores(...):\n    ..."}
]}

rbtr_list_symbols — file path in, TOC out:

{"kind": "list_symbols", "chunks": [
  {"name": "_name_score_expr", "kind": "function", "line_start": 44, "line_end": 86},
  {"name": "fuse_scores", "kind": "function", "line_start": 298, "line_end": 380}
]}

rbtr_find_refs — symbol name in, referring symbols out:

{"kind": "find_refs", "refs": [
  {"name": "from rbtr.index.store import IndexStore", "kind": "import",
   "file_path": "src/rbtr/daemon/watcher.py", "line_start": 30, "edge": "imports"}
]}

rbtr_changed_symbols — two refs in, changed symbols out:

{"kind": "changed_symbols", "chunks": [
  {"name": "resolveCommand", "kind": "function", "file_path": "exec.ts", "line_start": 34}
]}

Footer

The extension shows index state in the pi footer:

• Building: rbtr: ⟳ parsing 42/177 (spinner with phase and progress).
• Ready: rbtr: ● 1.2k (symbol count).
• Error: rbtr: not installed or rbtr: disconnected (cli) when the daemon is down.

Commands

Three user-facing commands (no LLM involved):

| Command | Description | | ---------------- | ------------------------------------- | | /rbtr-status | Show index status (chunk count, path) | | /rbtr-index | Trigger a background indexing | | /rbtr-settings | View and toggle extension settings |

Configuration

Settings are read from JSON config files. Project-local overrides global:

| File | Scope | | ----------------------------- | ------------- | | ~/.pi/agent/rbtr-index.json | Global | | .pi/rbtr-index.json | Project-local |

{
  "command": "rbtr",
  "autoIndex": true
}

| Key | Default | Description | | ----------- | -------- | ------------------------------------------------ | | command | "rbtr" | How to invoke the CLI (see below) | | autoIndex | true | Auto-index on session start when no index exists |

CLI invocation modes

The command setting determines how rbtr is called:

| Value | Invocation | Use case | | --------------------- | ------------------------------------- | ------------------------------------------- | | "rbtr" | rbtr --json <cmd> | Installed globally (uv tool install rbtr) | | "uvx" | uvx rbtr --json <cmd> | Published on PyPI, no global install | | "uvx --from <path>" | uvx --from <path> rbtr --json <cmd> | Local development from a directory |

The extension validates the command on session start and shows an error with install instructions if it fails.

Development

Development requires Node.js 22.19 or later and npm. The full repository checks also require Python 3.13, uv, and just.

npm install               # install dependencies
just check                # full check (Python + TypeScript)
just lint-ts              # biome lint
just fmt-ts               # biome format
just typecheck-ts         # tsc --noEmit

Architecture reference

The extension talks to the daemon over ZMQ and falls back to the CLI when none is reachable, starting one on first use. ARCHITECTURE.md covers the session lifecycle, the reconnection model, and rendering.