Signal Grep for Pi

简体中文 · English

Context-efficient, correctness-first content search and bounded code inspection for the Pi coding agent. Signal Grep turns broad ripgrep output into file counts, real matching-line samples, and explicit follow-up requests while preserving retained evidence and reporting limits.

Latest release: 0.5.8. Publisher: 宝儿.

Why Signal Grep?

For a broad query, the next useful step is often to choose the right files and inspect their code. Signal Grep supports that path directly:

• Small search: return all grouped matching lines in one call when they fit.
• Broad search: return exact per-file counts before bounded, labeled source-preview windows.
• Direct follow-up: copy the cursor from the result text to retrieve selected files or inspect up to five visible match numbers together.
• Stable evidence: cursor pages use the retained snapshot; current-file context and inspection require verified source revisions.
• Explicit limits: distinguish retained matches, displayed previews, missing source ranges, and partial retention.

0.5.8 evidence operations

Ordinary content search remains the default. The following operations add evidence that a plain grep response cannot establish:

• allOf: ["authorize", "persist"] proves that every literal term occurs in one file. Add within: "function" to require JS/TS/TSX own implementation code; nested callbacks, comments, static strings, regex literals and type areas do not count.
• roles: ["declaration"] or roles: ["call"] filters each individual occurrence by syntax role in JS/TS/TSX/Go. Go call-versus-conversion and short-declaration cases remain explicit candidates.
• changes: { "base": "HEAD", "scope": "lines", "side": "new" } uses a fixed Git comparison. With allOf, every term must be wholly inside the selected side's changed lines. Historical output stays bound to commit/blob source; it does not switch to the worktree.
• mode: "outline" returns paged JS/TS/TSX symbols. mode: "imports" follows bounded static named/default ESM bindings and named re-exports. mode: "tests" returns direct, indirect and weak related-test candidates; it never claims coverage or a passing test run.

Use the complete JSON shown after Next request:. A sourceCursor continues only missing raw-byte source ranges from the exact same source version; replaying the same token is safe, while changed, expired or modified tokens fail explicitly.

The samples are examples of matching text, not relevance scores or complete file contents. File order follows match counts, not an estimate of which file will solve the task. The plugin has no fuzzy fallback, background index, database, telemetry, or network requests.

Example: choose files, then inspect code

For illustration, a broad TODO query can return counts, bounded source previews, and a usable cursor in one model-facing response:

N matches across M files (complete snapshot).
Files 1-M of M, ordered by match count.

broad.ts     200
noise.ts      30
README.md       1
src/app.ts       1
utils.ts       1

Source previews are bounded, not relevance-ranked or exhaustive.
broad.ts:1 {match #34} // TODO broad 0
noise.ts:1 {match #4} // TODO fix 1
README.md:1 {match #3} TODO readme
src/app.ts:1 {match #1} // TODO app
utils.ts:1 {match #2} // TODO utils

Snapshot cursor="<returned-cursor>".
Inspect samples: mode="inspect", cursor, matchIndices=[one or more visible match numbers, max 5].
Retrieve matching lines: cursor with path or paths selecting exact files, no mode.

The cursor is represented here by <returned-cursor>. Match numbers belong to that snapshot and can differ in a new search. Use the actual cursor and visible match numbers from your own response:

{ "mode": "inspect", "cursor": "<returned-cursor>", "matchIndices": [1, 2] }

This inspects the selected source locations in one bounded call. To retrieve matching lines from the two selected files instead:

{ "cursor": "<returned-cursor>", "paths": ["src/app.ts", "utils.ts"] }

Summary rows use descending match counts and path-order ties. A summary page shows at most 30 files and may show fewer to fit its text budget; sample omissions are explicit. Use the returned cursor with mode="summary" for later file pages. The original summary cursor remains reusable for details, repeated single-file selections, or up to 20 exact retained paths, without rescanning. A match cursor must keep its bound selection.

Compact complete searches return details directly, avoiding a summary-and-cursor round trip. Each matching line has a stable {match #N} marker; a summary cursor plus matchIndex=N remains the single-target inspection form. Long matching lines and cursor-scoped inspection keep the primary occurrence visible; other excerpts and occurrence ranges have explicit display limits.

For implicit auto searches without limit, Pi's reported context remainder controls only the initial detail-fit trial: full above 40% targets 2,000 estimated result-text tokens, tight from 12% through 40% targets 1,000, and critical below 12% targets 500. Unknown usage preserves the default. Explicit limits, matches, inspection, and cursor continuation are never downshifted.

Human-readable Pi TUI

In Pi's interactive terminal, Signal Grep presents the same result as a responsive evidence view: ranked bars for summaries, grouped file evidence for match pages, explicit partial-retention warnings, and bounded inspection status. The collapsed view adapts to narrow, medium, and wide terminals; expanding the tool row shows the complete original result.

This is a display-only boundary. The renderer does not change model-facing text, structured details, cursors, search policy, Metrics accounting, JSON/RPC/print output, or persisted state. If the current text/details shape cannot be recognized safely—or custom rendering fails—the Pi row falls back to the original result text.

Local verification

Run the repository quality gates before contributing:

bun run check
bun run pack:check

These commands validate contracts and package contents. They do not measure model performance, task-level token use, cost, coverage, or test success in a user repository.

Requirements

Runtime

• Pi 0.84.3 or newer
• Node.js 22.19+ or Bun 1.4+
• ripgrep available as rg on PATH
• Optional Universal Ctags with JSON output on PATH for symbol-level inspection
• Pinned @ast-grep/napi and @ast-grep/lang-go packages installed with the plugin for JS/TS/TSX/Go syntax. No Go compiler, Ctags or network request is required for these parser-backed operations.

Development

• Bun 1.4+
• TypeScript 7+
• Node.js 22+ for compatibility checks

Installation

Install the latest release from npm:

pi install npm:pi-plugin-signal-grep

You can also install the current GitHub version:

pi install git:github.com/xcjy8bao/pi-plugin-signal-grep

Then restart Pi. During local development:

pi -e ./src/index.ts

Optional built-in grep override

Signal Grep defaults to additive mode and registers signal_grep alongside Pi's built-in grep. To route every normal grep call through Signal Grep while exposing exactly one public search tool, run:

/signal-grep-override on

The command safely persists a user-global setting through a staged file at ~/.pi/agent/signal-grep.json and reloads Pi resources. Override mode registers Signal Grep as grep, accepts the built-in grep parameter shape, preserves built-in case-sensitive behavior when ignoreCase is omitted, and keeps the richer glob, exclusion, adaptive summary, and cursor controls. /signal-grep-health reports the active grep source. Before persisting an override, Signal Grep refuses the transition if another extension already owns grep; Pi also rejects duplicate registrations while loading extensions. A conflict therefore fails clearly without changing config or silently splitting search ownership. Disable it and restore Pi's built-in implementation with:

/signal-grep-override off

When pi-hashline-edit-pro is installed, Signal Grep adds one system prompt guideline telling the model to obtain served anchors through hashline's grep or read before editing a location found by signal_grep. The hint is not repeated in each search response, does not alter Metrics accounting, and does not claim that Signal Grep can write hashline's private served-state. Use /signal-grep-override status to inspect the active mode. Override is deliberately opt-in because another extension may also replace grep; Pi reports tool collisions at startup.

Interface language

Human-facing command descriptions, notifications, health output, and Metrics status/report text default to English. To use Simplified Chinese, set locale in ~/.pi/agent/signal-grep.json and restart Pi:

{
  "overrideBuiltinGrep": false,
  "startMetricsOnNextLoad": false,
  "locale": "zh-CN"
}

Supported values are "en" and "zh-CN". Existing config files without locale continue to use English. Signal Grep commands preserve the complete config object when they update override or Metrics handoff state. Search evidence, tool parameters, cursor details, and model-facing prompt guidelines remain language-neutral or English so localization cannot change search s