@jmcombs/pi-better-toolsy

Drop-in replacements for Pi's built-in ls, read, grep, find, edit, and write tools — transparently adds .gitignore awareness, path-traversal protection, and injection-safe edits without changing how the agent works.

Quick Start

pi install @jmcombs/pi-better-toolsy

That's it. The agent uses its normal tool names and your implementations run automatically.

How It Works

Pi exposes six built-in file tools that the LLM is trained to call by name. This extension overrides all six with Node.js implementations that add correctness and safety guarantees the originals lack.

Tool	What's added
ls	.gitignore filtering, dotfile suppression, directories listed as name/
read	50 KB size guard, accurate line-number prefixes when using offset
grep	Relative paths in all results, ripgrep fast-path with Node.js fallback, ignoreCase / literal / context flags, .gitignore filtering
find	.gitignore filtering, path-based gitignore patterns (dist/**), reliable result cap
edit	$-injection-safe replacement (slice arithmetic, not String.replace), uniqueness validation, multiple edits in one call
write	Path-traversal guard, automatic parent directory creation

Because the overrides use the same tool names, the agent's trained behavior is completely unchanged — it calls grep, edit, etc. as always, and the improvements are invisible.

Path Safety

Every tool resolves user-supplied paths through safeResolve(), which blocks directory traversal attacks (../../etc/passwd). Paths are always resolved relative to the current working directory.

.gitignore Awareness

ls, grep, and find load .gitignore at the search root and skip ignored entries. Path-based patterns (dist/**, packages/*/node_modules/) are matched against the full relative path, not just the basename, so nested ignores work correctly.

$ Injection Safety

The built-in edit tool uses String.prototype.replace, which silently expands special $-patterns in replacement text ($&, $`, $', $$). This is especially dangerous in TypeScript source files full of template literals and $-prefixed identifiers. The override uses slice arithmetic so replacement text is always treated as a literal string.

Multi-Edit Support

The edit tool accepts an array of { oldText, newText } pairs and applies them in sequence within a single call. Each edit is validated for uniqueness before any change is written to disk.

Development

This package lives in the pi-extensions monorepo.

# From the repo root
npm ci
npm run check

To test changes locally against a real Pi session:

pi -e ./packages/better-toolsy

License

MIT © Jeremy Combs