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 (project-local)
pi install -l ./packages/pi-rbtr

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

# In .pi/rbtr-index.json
{ "command": "uvx --from ./packages/rbtr" }

What the agent gets

Seven tools, registered automatically on session start:

| Tool | Description | | ---------------------- | ------------------------------------------------------------------- | | rbtr_search | Search by name, keyword, or concept (BM25 + semantic + name fusion) | | 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, tests, docs) | | rbtr_changed_symbols | Symbols that changed between two git refs | | rbtr_index | Index the repository (background, incremental) | | rbtr_status | Check whether the index exists and how many symbols it contains |

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. More precise than grep for semantic queries.
• 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, test, and doc edges in the dependency graph.
• What changed? → rbtr_changed_symbols. Function-level diff between two refs, not line-level.

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.

How it works

The extension shells out to the rbtr CLI via pi.exec(). All commands use --json for machine-readable NDJSON output. There is no daemon — each tool call spawns a process. Builds are incremental (blob-SHA dedup) so repeated calls are fast.

Session lifecycle

1. session_start — load settings, resolve CLI command, run rbtr status. If the index exists, show the symbol count in the footer. If not and autoIndex is true, start a background indexing.
2. before_agent_start — append a note to the system prompt telling the agent the index is available.
3. Tool calls — each tool runs rbtr --json <subcommand> with a 30-second timeout (10 minutes for indexing).

Background indexing

rbtr_index and /rbtr-index launch indexing as a background process. The footer shows "building…" and updates to the symbol count on completion. If the LLM searches while a build is running, it gets an error asking it to retry after the build completes. Concurrent build requests are deduplicated.

Output truncation

All query tool results are truncated to 50 KB / 2000 lines (pi's default limits) to avoid overflowing the LLM context. Truncation is noted in the output with a suggestion to use --limit or rbtr_read_symbol for details.

Development

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

Project structure

packages/pi-rbtr/
├── package.json              # pi manifest, npm dependencies
├── tsconfig.json             # strict TypeScript config
└── extensions/
    └── rbtr/
        ├── index.ts          # extension entry point
        ├── exec.ts           # CLI resolution, pi.exec() helpers
        ├── render.ts         # custom TUI renderers for all tools
        └── settings.ts       # config load/save, settings UI

Architecture reference

See ARCHITECTURE.md for how the extension is structured, CLI integration details, and rendering design.