pi-agentic-search

pi-agentic-search is a Pi extension for finding code with fewer tool round-trips.

I built it to avoid the repeated searches and file reads an agent goes through before reaching the right place in a codebase. It ranks search results and collects related code in one call, so the agent doesn't have to fetch each file separately.

Finding code

agentic_search ranks ripgrep matches, suggests which file to read first, and includes source snippets. It can look for definitions, references, or tests. When the same name appears in several parts of the codebase, context helps rank the relevant matches.

For example, searching for remaining_value with context actual goal progress helps separate goal-related code from unrelated financial calculations. The search pattern stays the same; the context changes how matches are ranked.

The search can also follow supported Ruby mixins and JavaScript/TypeScript imports into other files and packages. That lets the agent find the definition behind an imported name without opening every file along the way. Directory and partial-path searches follow relationships from a limited set of ranked matches, with the selected and omitted files reported in the results.

Following calls and reviewing changes

The context tools collect definitions, calls, callers, and related tests for Ruby, JavaScript, and TypeScript.

sparsity_collect takes a file and line number, finds the enclosing definition, and follows its calls up to the requested depth. The result includes source snippets, static callers, and calls it couldn't resolve.

sparsity_scan collects context for a whole diff, including removed definitions that still have callers. It accepts commits, Git ranges, or uncommitted changes with untracked files.

A manifest lists the pack's contents and points to sections in pack.md. The agent can read the section it needs without loading the whole pack into the conversation. Schemas, configuration, and other files include their changed hunks without call expansion. Additional test definitions are grouped by file.

Installation

You need Pi and rg (ripgrep) on your PATH. Diff context also uses Git. The package includes its Ruby parser and TypeScript dependency.

pi install npm:pi-agentic-search

Then run /reload in Pi. To try the published package for one session without saving it to your package settings:

pi -e npm:pi-agentic-search

Usage

Pi can call these tools during coding work. You can also ask for one by name:

Use sparsity_scan to collect context for my uncommitted changes. Explain what changed and which callers might be affected.

Pi can collect the diff with diff: "worktree", read the relevant sections, and use sparsity_collect for a closer look at a definition. When starting from a name rather than a diff, agentic_search finds candidates first.

Scope and limitations

Depth, file, node, and time limits bound each search or traversal. When a tool stops early, it reports unfinished scopes and unresolved relationships so the agent knows where to follow up. The collector reports setup time and total wall time separately. Its traversal budget doesn't interrupt initial parser, index, or compiler setup.

Call resolution is static. A matching name, especially in Ruby, doesn't prove which method gets called at runtime. Labels distinguish exact declarations from candidates, ambiguous matches, and unresolved calls. The tools find tests that reference the code, but don't run them or establish coverage. They also omit common library operations, so zero unresolved edges doesn't mean they found every runtime call.

Context collection defaults to the nearest component root within the working directory. Use cwd to select another checkout. For a diff, omitting root or passing . keeps separate component roots; an explicit path narrows the scan. Files absent from a sparse checkout aren't searchable.

For committed ranges, changed files come from the range's head. Callers, tests, and unchanged files come from the checkout. The manifest records which revisions it used.

Large TypeScript projects can use a lot of memory. Building a compiler program for one recorded 5,800-file import closure took about two seconds and 1 GB. Those numbers describe that workload, not a resource limit.

Evaluation

The public evaluation compares search results on 15 frozen Pi, Rails, and Zod cases, including six holdouts. Its baseline report records:

Measure	Raw rg	Full search
Correct first file, positive cases	6/12	11/12
Correct first span, positive cases	5/12	10/12
Valid negative misses	3/3	3/3

These cases were selected manually. They measure search quality, not how many tool round-trips the extension saves in general. Two Zod ranking/span limitations remain; the evaluation documents them alongside the feature ablations and model runs.

The synthetic benchmarks check ranking and execution behavior. Exact-file searches without related expansion use one ripgrep process and no path listing, including in fixtures with 7,999 unrelated files.

Use /agentic-search-stats in Pi to inspect recent context-tool runs, or /agentic-search-stats 10 for the last ten.

Data access

The extension makes no direct network requests. It reads local source and configuration, runs ripgrep and Git, and writes context packs, metrics, Ruby index caches, and oversized output. Packs contain source snippets.

The runtime access document describes search's filesystem and subprocess access. Report vulnerabilities privately using SECURITY.md.

Other installation options

Install from GitHub:

pi install git:github.com/dantetekanem/pi-agentic-search

Or use a local checkout:

git clone https://github.com/dantetekanem/pi-agentic-search.git
cd pi-agentic-search
npm ci
pi install .

Development

This repository uses npm and package-lock.json for development, CI, and publishing. Use Node.js 22, as CI does, with rg on your PATH. Keep dependency changes in package.json and package-lock.json together; don't maintain a second lockfile.

npm ci
npm run check
npm test
npm run smoke
npm run benchmark -- --samples 15 --check --output /tmp/search-benchmark.json

The smoke command covers search, call cycles, committed-range context, the language adapters, cached Ruby indexing, and boundary ranking. Write new benchmark runs to a separate output file.

Public-source and opt-in model measurements have separate reproduction instructions. Normal tests don't make live model requests.