@agimon-ai/po-grep

Snapshot-bound hashline grep for Po.

Part of the Po distribution.

The native server plugin owns grep. Its private ripgrep service searches files, then attaches exact-byte file tags and stable three-letter anchors to writable matching or context lines. Non-writable files retain plain output. @agimon-ai/po-read and @agimon-ai/po-edit use the same hashline protocol.

Alpha: tool and protocol contracts may change between releases.

Requirements

• Node.js 24 or newer
• A Po native server host

Install

Select @agimon-ai/po-grep in .po/modes.yaml and run po sync. The package's poServer metadata names its built server plugin. There is no standalone Pi entry or tool-registration ordering requirement against po-ui.

Install @agimon-ai/po-edit when the model should apply the emitted anchors.

Tool protocol

Writable search results group matching and context lines beneath an exact-byte file header:

@file src/example.ts#A1b2C3d4
   4#def|const previous = true;
>> 5#abc|const match = true;

The eight-character file tag and three-letter line anchors are model-facing protocol data. Po's human renderer hides the protocol tags and anchors while retaining file paths, line numbers, match markers, and syntax highlighting.

Attribution

The hashline protocol and FNV anchor approach are adapted from Phi's writetool, licensed under MIT by pulseaiclub. Po uses an exact-byte SHA-256 file tag as an intentional compatibility boundary.

Public API

import { GrepParamsSchema } from '@agimon-ai/po-grep';
import type { GrepParams } from '@agimon-ai/po-grep';

Development

pnpm build
pnpm typecheck
pnpm test
pnpm lint

Maintained by Agimon.

License

Business Source License 1.1: free for personal use, organisations under USD 1M revenue, non-profits and education. See LICENSE and https://agimon.ai/licensing.

The server tool route lives in src/extensions/workspaces/sessions/(backend)/tool/grep.server.ts and delegates to the private grep service. Flat src/exports files only forward the public schema and parameter type; the tool factory is not public.