prime-basic-tools

If you really miss Pi's classic file tools in Prime Agent, this extension brings back read, write, and edit.

They work as normal model-callable tools and leave Prime Agent's persistent ipython environment untouched.

Install

From npm

prime-agent package install npm:prime-basic-tools

From GitHub

prime-agent package install git:github.com/NxcOP1891/prime-basic-tools

From a local checkout

git clone https://github.com/NxcOP1891/prime-basic-tools.git
cd prime-basic-tools
npm install
prime-agent package install "$PWD"

Start a new Prime Agent session after installation. Packages are loaded when a session starts.

Usage

No commands or configuration are required. Once installed, the model can call three additional tools.

Compact TUI results

read and write show short path, line, and byte summaries instead of dumping their contents into the TUI. edit uses Prime Agent's collapsed diff view, expandable with ctrl+o.

The model still receives the complete read result, including after a session is resumed.

read

Reads UTF-8 text and common images from relative or absolute paths.

• Supports 1-indexed offset and limit, with continuation hints.
• Limits text output to 2,000 lines or 50 KiB.
• Detects JPEG, PNG, GIF, WebP, and BMP by content and handles Pi's path expansions and macOS filename fallbacks.

Images are attached without resizing or conversion, so support depends on the selected model and provider.

write

Creates or overwrites a UTF-8 file, makes missing parent directories, and serializes concurrent writes to the same resolved path.

edit

Applies one or more unique, non-overlapping replacements to an existing UTF-8 text file.

• Rejects missing, duplicate, overlapping, or empty targets, plus calls that make no change.
• Preserves UTF-8 BOMs and LF or CRLF line endings.
• Falls back to Pi's whitespace and Unicode normalization when exact matching fails.
• Returns a display diff and unified patch, while accepting legacy model argument shapes.

Fuzzy fallback operates in normalized text space and may normalize matching punctuation or trailing whitespace elsewhere; inspect the returned diff.

Compatibility

prime-basic-tools 0.1.x is developed and tested with Prime Agent 0.7.x and Node.js 22.8 or later.

The implementation is intentionally self-contained: its runtime dependencies are installed with the package, and it does not import unpublished Prime Agent internals. Tool definitions are registered through Prime Agent's public extension API and participate in the normal tool lifecycle.

Safety

Extensions run with the same operating-system permissions as Prime Agent. These tools can read, create, and modify any path accessible to that process; they do not add a filesystem sandbox. Review tool calls and only install packages from sources you trust.

write and edit coordinate mutations within the current Prime Agent process. They do not lock files against unrelated processes or other Prime Agent processes.

Development

npm ci
npm run check
npm test
npm pack --dry-run

The tests cover registration, compact TUI summaries, provider-context restoration, reads, writes, edit matching, concurrency, and line-ending preservation.

Acknowledgements

The file-tool behavior and edit/diff implementation are adapted from the MIT-licensed Pi coding agent and Prime Agent. This project is an independent compatibility extension and is not an official Pi or Prime Intellect package.

License

MIT — see LICENSE.