pi-find

Release notes: changelog · GitHub releases

Simple, bounded grep and find tools for the pi coding agent, backed by ripgrep and fd.

Install: npm:@tian.zuo/pi-find · npm package @tian.zuo/pi-find · workspace packages/pi-find

The extension reuses pi's built-in tool names, so the model sees one search surface instead of competing built-in and extension tools.

Tools

grep

grep(pattern, path?, glob?)

• pattern is a case-sensitive ripgrep regular expression.
• path is one file or directory and defaults to the current directory.
• glob optionally limits file names, for example *.ts or **/*.test.ts.

{ "pattern": "TODO|FIXME", "path": "src", "glob": "*.ts" }

find

find(pattern, path?)

• pattern is a case-insensitive file glob, for example *.ts or **/*.test.ts.
• path is one directory and defaults to the current directory.

{ "pattern": "**/*.test.ts", "path": "packages" }

Search behavior

• Both tools respect .gitignore and always skip .git. Explicit .git roots, files inside them, and symlink aliases to them are rejected.
• Globs without / match basenames at any depth. Globs containing / match paths relative to the search directory (or the parent of an explicit grep file) or to the working directory, so both { "path": "src", "glob": "src/*.ts" } and { "path": "src", "glob": "deep/*.ts" } select files under src. src/*.ts matches direct children of src, while src/**/*.ts includes descendants. Use / in globs on every platform. Glob filtering never re-includes ignored files.
• A leading ! excludes instead of includes, like ripgrep's own --glob: for example glob: "!*.test.ts" or pattern: "!**/*.generated.ts".
• A leading @ is stripped from input paths; ~ and ~/... expand to the home directory. Ripgrep user configuration is ignored so it cannot change the tool's case sensitivity or ignore behavior.
• Hidden files and directories are not searched by default. An explicitly named hidden path still works, for example path: ".github".
• Grep stops after 100 matches; find stops after 200 files. A result says when the fixed limit was reached so the caller can narrow the search.
• Grep skips files larger than 4 MiB during directory traversal. Explicitly named files follow ripgrep's explicit-file behavior and can exceed that limit.
• Grep lines longer than 400 characters are clipped.
• A single match or path record larger than 8 MiB is skipped instead of being buffered, and the result says so. Explicitly named files bypass ripgrep's traversal size cap, so this is what keeps a search of a single-line bundle, sourcemap, or lockfile from ballooning memory.
• Search output also has a hard byte limit, and running searches are cancellable.
• Relative result paths can be passed directly to pi's read and edit tools. Paths containing control characters, backslashes, or quotes are JSON-quoted; decode the JSON string before using them. Newlines in filenames do not create extra find results.
• Timeouts are marked as partial, including when no results were gathered. Unexpected process termination is an error, not a completed empty search.

For uncommon searches involving several roots, exclusions, multiline matching, counts, sorting, or pipelines, use rg or fd through the shell rather than expanding these tool schemas.

Hidden files and secrets

Default searches do not walk hidden paths. This reduces accidental exposure of files such as .env, .npmrc, and private keys in model-visible tool output. It is not a complete secret boundary: explicitly named files, ordinary tracked files, read, and shell tools can still expose secrets. Strong secret isolation must be enforced across every filesystem tool, not only grep.

Binaries

The extension first uses pi's managed ~/.pi/agent/bin/{rg,fd} binaries, then checks PATH (fdfind is accepted on Debian/Ubuntu). It requires ripgrep >= 12.0 and fd >= 8.7.0. If either is unavailable, the tool returns a clear install or upgrade message; it does not run a package manager.

Development

pnpm --filter @tian.zuo/pi-find run check
pnpm --filter @tian.zuo/pi-find test
pi -e ./packages/pi-find

The integration tests run real rg and fd searches when those binaries are available.