pi-clarify

A Pi coding agent extension that rewrites rough, plain-language prompts into precise technical prompts before you send them to the agent.

Use it when you know what you want, but not the exact term or structure. Pi loads the TypeScript extension directly, so this package intentionally publishes its source rather than a compiled build.

Install

pi install npm:pi-clarify

Git and local installs are also supported:

pi install git:github.com/dodo-reach/pi-clarify
pi install https://github.com/dodo-reach/pi-clarify
pi install /path/to/pi-clarify
pi -e git:github.com/dodo-reach/pi-clarify

After installation, restart Pi or run /reload.

Important

Pi extensions execute with your full user permissions. Review extension source before installing it, especially from an untrusted repository or package version.

Usage

/clarify make the cards not jump when I drag them
/clarify                          # rewrite current editor text
make the cards not jump --clarify  # marker anywhere in the message
--clarify wait until typing stops before search

The rewrite is written back through Pi's editor API (setEditorText). The coding agent does not start until you review and send the rewritten prompt.

Model selection

By default, clarify uses the current session model. Pin a different model from your Pi registry with:

/clarify model                      # show effective model
/clarify model <provider>/<model>   # pin a model
/clarify model reset                # return to the session model

Pinned model configuration is stored at <agent-dir>/extensions/clarify.json (usually ~/.pi/agent/extensions/clarify.json, alongside subagents.json):

{
  "model": "your-provider/your-model-id"
}

The model must already exist in Pi's model registry and have authentication configured.

Behavior

• Registers /clarify.
• Intercepts the whole-token --clarify marker anywhere in normal user input.
• Runs one model turn to compress long descriptions into standard technical terms.
• Preserves concrete details such as names, paths, numbers, errors, and acceptance criteria.
• Keeps the user's language and does not invent scope, stack choices, or requirements.
• Returns ready-to-send prompt text only, without quotes or a preamble.

Requirements

For use:

• Node.js 22.19 or newer.
• Pi with extension support.
• A configured session model, or a pinned model and API key.

For development:

• Nix with flakes enabled and devenv (recommended), or compatible Node.js and pnpm versions.
• pnpm is pinned through the packageManager field.
• Pi is needed only for interactive testing.

Development

Enter the reproducible environment and install dependencies:

devenv shell
pnpm install

Launch Pi with the source entry point for an interactive check:

pnpm run dev

The extension entry point is src/clarify.ts; pure marker helpers are in src/marker.ts. Run quality checks with:

pnpm run check
pnpm run lint
pnpm run fmt
pnpm run test
pnpm run test:watch
pnpm run test:coverage

Coverage is written to coverage/. The devenv test command runs checks, tests, and package validation. CI performs the same core validation on GitHub pushes and pull requests.

Package and publishing

Validate the exact npm archive contents without publishing:

pnpm run pack:check

Only src/, README.md, LICENSE, and package metadata are published. Pi-provided runtime packages remain optional peer dependencies, while matching development dependencies provide their APIs for local checks and tests.

Before publishing, update the version, review the dry-run archive, run the full checks, and then publish through the configured npm registry:

pnpm run check
pnpm run test:coverage
pnpm run pack:check
pnpm publish

Consumers can install the released package with pi install npm:pi-clarify.

Package layout

pi-clarify/
├── .github/workflows/ci.yml
├── src/
│   ├── clarify.ts
│   └── marker.ts
├── test/
├── devenv.nix
├── package.json
├── pnpm-workspace.yaml
└── README.md

See the Pi packages documentation.

License

MIT