pi-neutrasearch

Token-efficient native indexed filename and path search for Pi.

pi-neutrasearch registers one read-only neutrasearch tool. It queries an existing Neutrasearch compact index without walking directories, opening file contents, writing files, elevating privileges, or using the network.

Install

Install the Pi package:

pi install npm:pi-neutrasearch

npm automatically installs the matching Neutrasearch application for Linux x64/ARM64, Windows x64, or macOS x64/ARM64. No separate application download or compiler is required.

Inside Pi, run:

/neutrasearch-setup

This installs convenient shortcuts and opens the bundled Neutrasearch app:

• Linux: application menu, Desktop, and ~/.local/bin CLI links
• Windows: Start Menu and Desktop shortcuts
• macOS: ~/Applications/Neutrasearch.app and a Desktop alias

Approve local indexing in the app, then return to Pi. Indexing remains an explicit user action; package installation never scans disks or requests privileges.

Use /neutrasearch to inspect installation and index status.

The package resolves, in order:

1. NEUTRASEARCH_QUERY or NEUTRASEARCH_BIN when explicitly configured
2. the OS/architecture-specific binary package installed by npm
3. neutrasearch-query or neutrasearch on PATH

Set NEUTRASEARCH_INDEX to override Neutrasearch's platform-default index path.

Agent tool

{
  "action": "search",
  "query": "invoice ext:pdf",
  "scope": "/workspace/project",
  "limit": 20,
  "relative_paths": true,
  "metadata": false,
  "max_chars": 6000
}

The output is deliberately compact:

scope=/workspace/project
matched=2 returned=2 search_us=184
records/2025/invoice-1042.pdf
records/2024/invoice-991.pdf

Defaults are optimized for agent context:

• 20 results
• relative paths
• no metadata columns
• 6,000-character hard output budget
• two-line numeric header

Use metadata: true only when kind, size, or modification time is needed.

Search language

• words and "quoted phrases"
• ext:rs,toml
• kind:file, kind:dir, or kind:link
• fs:btrfs,ext4,ntfs
• size:>10M, size:<4K, or size:1M..20M

Neutrasearch searches indexed names and paths, not file contents. Locate candidates with this tool, then use targeted read or grep calls.

Scope and privacy

Every search is scoped to the current Pi workspace by default. A requested scope must resolve inside that workspace.

To authorize additional roots explicitly, set an OS-path-delimited list:

export NEUTRASEARCH_PI_ALLOWED_ROOTS="$HOME/Documents:$HOME/Projects"

The extension verifies returned paths again and drops any path outside the approved scope. It never starts the scanner or helper daemon.

Development

cd packages/pi-neutrasearch
npm test
pi -e .

License

MIT