pi-codebase-router

Index-first routing for Pi. It makes the agent reach for the opencode-codebase-index semantic tools (codebase_peek, codebase_search, implementation_lookup, call_graph) before falling back to exploratory grep and shell — which saves tokens and keeps context focused — and keeps file access/mutation on the built-in read / edit / write tools.

It bundles three things:

• An extension that injects index-first guidance, guards discouraged discovery, and can auto-index on session start / after writes.
• A skill (indexed-codebase-workflow) documenting the discovery loop.
• cb* prompt templates — thin, safe wrappers over the index tools.

Requires the companion package opencode-codebase-index, which provides the codebase_* / index_* tools this package routes toward. It is a separate install (see below for why). Without it, this extension degrades gracefully and shows index tools unavailable in the status bar.

Install

# 1. the companion that provides the actual index tools (~235 MB native)
pi install npm:opencode-codebase-index

# 2. this router (extension + skill + cb* prompts)
pi install npm:pi-codebase-router
#   …or straight from git:
pi install git:github.com/josephjohncox/pi-codebase-router

Use pi install ... -l to write to project settings (.pi/settings.json) instead of global (~/.pi/agent/settings.json).

Why two installs (and not one)?

This package intentionally does not bundle or auto-install opencode-codebase-index:

• It ships ~235 MB of per-platform native binaries (tree-sitter + usearch, 5 platforms). Vendoring that into a ~12 KB routing package via bundledDependencies — the only way Pi reliably loads a sibling pi-package, since it hoists normal deps into one flat node_modules — would be absurd.
• Pi has no supported "install this other package into settings" hook, and a postinstall shelling out to pi install is fragile and invasive.

So they stay decoupled: install the companion once, globally, and every project reuses it. This package is declared an optional peer of it (documents the relationship without triggering a 235 MB auto-download).

Configuring the companion (opencode-codebase-index)

The router points at whatever opencode-codebase-index is configured to do; it does not have its own indexing config. Under Pi, that package runs in host pi, which uses the neutral .codebase-index/ layout:

| Scope | Config | Index storage | | --- | --- | --- | | Global | ~/.config/codebase-index/config.json | ~/.codebase-index/global-index | | Project | <repo>/.codebase-index/config.json | <repo>/.codebase-index/index |

Project config overrides global. The router's background indexer launches the companion with --host pi, so it writes the same directory the in-process codebase_search reads — no split-brain index.

Example config (local Ollama embeddings)

The reference setup uses a local Ollama server via its OpenAI-compatible API (/v1), so nothing leaves the machine and there are no embedding-API costs:

// ~/.config/codebase-index/config.json
{
  "embeddingProvider": "custom",
  "customProvider": {
    "baseUrl": "http://127.0.0.1:11434/v1",
    "model": "qwen3-embedding:8b",
    "dimensions": 4096,
    "apiKey": "ollama"
  }
}

Ollama setup (recommended: local + free + private)

# 1. install Ollama — https://ollama.com  (macOS: brew install ollama)
# 2. start the server (the desktop app does this too)
ollama serve
# 3. pull an embedding model (see the table below)
ollama pull qwen3-embedding:8b

Then point the companion at it. Two ways:

• Custom /v1 (recommended for any model / larger models) — the example above. baseUrl must end in /v1 (the companion appends /embeddings); apiKey can be any placeholder ("ollama").
• Built-in Ollama provider (simplest) — { "embeddingProvider": "ollama" }. Uses Ollama's native API with nomic-embed-text, but budgets input to ~2048 tokens, so prefer the custom /v1 route for larger-context models.

Remote Ollama? Set OLLAMA_HOST=http://host:11434 (built-in provider) or the full baseUrl (custom provider).

Which embedding model?

All run locally via Ollama. Pick by the RAM/VRAM you can spare; bigger = better retrieval but slower indexing.

| ollama pull … | dimensions | Footprint | Use when | | --- | --- | --- | --- | | qwen3-embedding:8b | 4096 | ~8B (needs real RAM/VRAM) | Best quality. Workstations/servers. (the reference config) | | qwen3-embedding:4b | 2560 | ~4B | Strong quality, lighter than 8B | | qwen3-embedding:0.6b | 1024 | ~0.6B | Best quality-for-size on laptops | | mxbai-embed-large | 1024 | ~335M | Strong English retrieval, low resource | | bge-m3 | 1024 | ~567M | Multilingual / longer context | | nomic-embed-text | 768 | ~137M | Fast, tiny default; fine for most repos |

Rules of thumb

• Laptop / low memory → nomic-embed-text (or qwen3-embedding:0.6b for better recall).
• Plenty of memory and you want the best hits → qwen3-embedding:8b.
• Set dimensions to the value in the table (the model's native output width). Ollama does not reliably honor a requested smaller dimension, so don't guess — if unsure, check the model card on ollama.com. A wrong dimensions yields a dimension-mismatch error and a forced rebuild.
• Changing model or dimensions invalidates the index: run /cbindex force once after the change.

Provider options (if not using Ollama)

embeddingProvider accepts auto (default; detects Copilot → OpenAI → Google → Ollama), ollama, openai, google, github-copilot, or custom (any OpenAI-compatible /v1/embeddings endpoint). Hosted providers read their key from the usual env vars (e.g. OPENAI_API_KEY, GOOGLE_API_KEY); GitHub Copilot reuses existing OpenCode auth. See the companion README for the full schema (chunking, hybrid weights, reranker, knowledge bases, etc.).

Verifying / building the index

/cbstatus            # provider, model, chunk count, readiness
/cbindex             # incremental build/update
/cbindex force       # full rebuild (after changing provider/model/dimensions)

What it does

1. Index-first guidance (before_agent_start)

On code/repository-flavored prompts it appends a short routing block to the system prompt: peek → look up the definition → read exact lines; reserve grep for exact identifiers; keep edits on read/edit/write; use /cbindex when the index is missing or stale.

2. Discovery guard (tool_call)

| Attempt | Verdict | | --- | --- | | grep / shell rg for a concept ("where is auth handled?") | blocked → use codebase_peek | | grep for an exact identifier/literal (validateToken, -F fixed strings) | allowed | | Shell source read (cat/head/tail/sed/less/more a file) | blocked → use read | | Shell source write (>/>> to a file, tee <file>, sed -i, perl -i) | blocked → use edit/write | | Toolchain commands (git, npm, pytest, …) and 2>/dev/null / 2>&1 | allowed |

The guard is deliberately conservative: single-token identifier-shaped patterns, fd redirects (2>/dev/null, 2>&1), and normal toolchain commands are never blocked.

3. Optional background auto-indexing

Off by default. When enabled, indexing runs in the background — a detached opencode-codebase-index MCP subprocess does the work. There is no agent turn and no LLM cost, and Pi is never blocked: you keep typing while the index refreshes into the same .codebase-index/ directory Pi's codebase_search reads (host pi).

| Env var | Effect | | --- | --- | | PI_CODEBASE_AUTO_INDEX=1 | Background index on session start / resume / new / fork when the cwd looks like a project. | | PI_CODEBASE_AUTO_INDEX_AFTER_WRITE=1 | After a settled turn that used write/edit, background index once. | | PI_CODEBASE_INDEX_BIN=/abs/path/dist/cli.js | Point at the opencode-codebase-index CLI explicitly (otherwise auto-located under ~/.pi/agent/npm, the project's .pi/npm, or npx). | | PI_CODEBASE_AUTO_INDEX_VIA_TURN=1 | Revert to the legacy behavior: queue /cbindex as a follow-up agent turn instead of a background subprocess. |

Always an incremental index (never force), only in project directories (detected via .git, package.json, pyproject.toml, Cargo.toml, go.mod, pom.xml, build.gradle). At most one index runs at a time; writes that land during a run coalesce into a single follow-up index. The subprocess is killed on session shutdown (indexing is incremental and resumes next time). If the CLI can't be located or spawned, it automatically falls back to the follow-up-turn path.

Configuration

Settings resolve with precedence env var > project router.json > global router.json > built-in default. Nothing is required; the defaults are safe (enforce mode, no auto-indexing).

Config file — router.json

| Scope | Path | | --- | --- | | Global | ~/.config/codebase-index/router.json (respects $XDG_CONFIG_HOME) | | Project | <repo>/.codebase-index/router.json (overrides global) |

It sits next to the companion's config.json, so one dotfiles sync covers both. Re-read on /reload and on each new session. Example (all keys optional):

{
  "mode": "enforce",
  "autoIndex": false,
  "autoIndexAfterWrite": true,
  "autoIndexViaTurn": false,
  "indexTimeoutMs": 900000
}

Keys and env overrides

| router.json key | Env override | Values | Default | Meaning | | --- | --- | --- | --- | --- | | mode | PI_CODEBASE_ROUTER_MODE | enforce | warn | off | enforce | enforce blocks discouraged calls; warn allows but shows a hint and still injects guidance; off disables everything. | | autoIndex | PI_CODEBASE_AUTO_INDEX | bool | false | Background index on session start / resume / new / fork. | | autoIndexAfterWrite | PI_CODEBASE_AUTO_INDEX_AFTER_WRITE | bool | false | Background index after a settled turn that used write/edit. | | autoIndexViaTurn | PI_CODEBASE_AUTO_INDEX_VIA_TURN | bool | false | Use a follow-up agent turn instead of a background subprocess. | | indexBin | PI_CODEBASE_INDEX_BIN | path | auto | Explicit path to opencode-codebase-index's dist/cli.js. | | indexTimeoutMs | PI_CODEBASE_INDEX_TIMEOUT_MS | int (ms) | 900000 | Background-index kill timeout. |

Env booleans accept 1/true/yes/on and 0/false/no/off. An env value always wins over the files — set PI_CODEBASE_AUTO_INDEX_AFTER_WRITE=0 to switch off a file true for one session.

Commands (prompt templates)

| Command | Tool | Purpose | | --- | --- | --- | | /cbindex [estimate\|force\|verbose] | index_codebase | Build/update the index (incremental by default). | | /cbstatus | index_status | Show index status and provider/model. | | /cbreindex | index_codebase force | Full rebuild. | | /cbpeek <query> | codebase_peek | Metadata-only locations (cheapest). | | /cbsearch <query> | codebase_search | Semantic search with content. | | /cbfind <query> | peek → lookup/search → grep | Token-efficient hybrid discovery. | | /cbdef <symbol> | implementation_lookup | Authoritative definition site. | | /cbcallgraph <name> [callers\|callees] | call_graph | Callers/callees. | | /cbpath <from> <to> | call_graph_path | Shortest call path. | | /cbimpact [branch\|PR#] | pr_impact | Change blast radius. | | /cbhealth | index_health_check | GC and health report. |

Skill

indexed-codebase-workflow documents the loop: codebase_peek → implementation_lookup/codebase_search → read exact lines → edit/write → tests/diagnostics → inspect the diff. Load it with /skill:indexed-codebase-workflow.

Compatibility

• Pi loads the extension as TypeScript via jiti — no build step required.
• Requires Node ≥ 18.
• Peers (both optional/informational): @earendil-works/pi-coding-agent (provided by the Pi runtime) and opencode-codebase-index (install separately — see above; declared optional so it is not auto-downloaded).

Migrating from a local copy

If you previously hand-placed codebase-routing.ts in ~/.pi/agent/extensions/ (plus the skill/prompts), remove those local copies after installing this package so the extension doesn't load twice:

rm -f ~/.pi/agent/extensions/codebase-routing.ts
rm -rf ~/.pi/agent/skills/indexed-codebase-workflow
rm -f ~/.pi/agent/prompts/cb*.md

Continuous integration & publishing

• CI (.github/workflows/ci.yml): typechecks on every push/PR.
• Publish (.github/workflows/publish.yml): on a published GitHub Release it runs npm publish --provenance --access public. Manual runs (workflow_dispatch) support a --dry-run.

One-time setup: add an npm Automation token as the NPM_TOKEN repository secret (gh secret set NPM_TOKEN). Release flow:

npm version patch   # or minor / major — bumps package.json + tags
git push --follow-tags
gh release create "v$(node -p 'require("./package.json").version')" --generate-notes

The workflow verifies the release tag matches package.json. First release can also be published locally with npm publish --access public.

License

MIT © Joseph Cox