pi-colgrep

@gotgenes/pi-colgrep

Pi extension that integrates ColGrep semantic code search as a tool available to the agent.

ColGrep is a fully local semantic code search CLI built on multi-vector ColBERT embeddings and tree-sitter parsing. It combines regex filtering with semantic ranking, supports 25 languages, and runs entirely on the user's machine. This package exposes ColGrep as a Pi tool that complements (not replaces) the built-in grep.

Prerequisites

• ColGrep installed and available on PATH
• Node.js ≥ 22

Install

pi install npm:@gotgenes/pi-colgrep

Or add it to your Pi settings (~/.pi/agent/settings.json):

{
  "packages": ["npm:@gotgenes/pi-colgrep"]
}

Indexing

The extension keeps a semantic index current for the agent:

• On session start it builds the index in the background (colgrep init), so it never blocks Pi startup.
• After each successful write/edit it schedules a debounced reindex — but only when an index already exists for the directory, so a directory you never search is never indexed proactively.
• Run /colgrep-reindex to build or refresh the index on demand. This also re-enables the write/edit auto-reindex for the rest of the session.

If no index exists and startup indexing is disabled, the extension skips the auto-reindex and notifies you once. A real colgrep search still auto-indexes on demand regardless.

Configuration

Optional configuration is read from a JSON file at two locations, with the project file overriding the global one:

Scope	Path
Global	<agentDir>/extensions/pi-colgrep/config.json
Project	<cwd>/.pi/extensions/pi-colgrep/config.json

Key	Type	Default	Description
indexOnStartup	boolean	true	Build the index in the background on session start. Set to false to skip startup indexing entirely (the index is then built lazily on the first real search or via /colgrep-reindex).

Example — disable startup indexing for a large non-code directory:

{
  "indexOnStartup": false
}

A missing config file is fine (defaults apply); a malformed file is ignored with a warning.

Scope and non-goals

Purpose. The built-in grep finds text matching a pattern, but not code by intent when you do not know the exact wording. This extension exposes the external ColGrep CLI as an agent tool and keeps its index warm across a session.

In scope. The tool surface, the index lifecycle, and agent guidance about when semantic search is the right instrument.

Non-goals.

• Replacing grep. Exact string, regex, and symbol matching stay with the built-in tools; the shipped skill exists to stop the agent defaulting to semantic search for everything.
• Owning the ColGrep binary. It is a user-supplied prerequisite — not bundled, installed, patched, or vendored — and a CLI bug is reported upstream. ColGrep is the backend, not one of several interchangeable engines.
• Blocking startup on indexing. Startup indexing is fire-and-forget, so a session is usable immediately.
• Indexing a directory nobody searched. Auto-reindex is gated on an index already existing, and there are no trigger heuristics beyond that plus one indexOnStartup boolean.
• Full CLI parity. The tool exposes a curated parameter subset; other flags remain reachable by running colgrep through bash.

Where adjacent requests belong. Exact pattern or symbol matching → the built-in grep. Finding files by name → the built-in find. Advanced filtering and multi-directory search → colgrep invoked through bash.

License

MIT