pi-prompt-optimize

Interactively optimize a prompt in pi, guided by the writing-for-agents skill.

This package adds a /prompt-optimize command and one model-callable tool:

• propose-prompt-optimization — presents the complete optimized prompt for Accept, Modify, or Cancel review.

The optimization phase is stored in pi session custom entries, so it follows session history, resume, fork, tree navigation, reload, and compaction behavior without an external database.

Install

Requires Pi 0.84.0 or later (interactive TUI mode).

Install from npm:

pi install npm:pi-prompt-optimize

Install a pinned npm version:

pi install npm:pi-prompt-optimize@<version>

Install from GitHub:

pi install https://github.com/wicii2120/pi-prompt-optimize

The package bundles the writing-for-agents skill under skills/, so no extra skill setup is needed.

Usage

/prompt-optimize <draft>    Start optimizing a prompt
/prompt-optimize end        Abort an active phase

• With no draft, the agent asks you for the prompt to optimize.
• While a phase is active, the footer shows ✦ prompt optimization, the propose-prompt-optimization tool is enabled, and the agent treats your draft and all subsequent messages as material to improve rather than tasks to run.
• When the agent decides the prompt is ready it calls propose-prompt-optimization with the full optimized prompt. Review it:
  • Accept — the phase ends and the optimized prompt is written into the editor after returning to the branch start.
  • Modify — describe the changes you want; the agent re-optimizes and proposes again (repeat as needed).
  • Cancel — the phase ends without writing the prompt.
• Accept and /prompt-optimize end both finish by navigating back to the branch start.

Durability

The phase is an event log of custom entries on the session branch:

• a start entry (branchStartId, previousTools) is appended when the phase begins;
• an end entry is appended when the phase terminates via /prompt-optimize end, Accept, or Cancel.

On session_start and session_tree the branch is replayed last-write-wins to rebuild (or clear) the in-memory phase. So:

• a reload or resume restores an in-flight phase;
• a fork rehydrates per its branch — a fork taken after start but before end carries the phase, while a fork from before start or after end does not;
• custom entries survive compaction, so no flush-on-compact logic is needed.

Only durable fields are persisted; the runtime command context is re-acquired from the event context on rehydration.

Requirements and notes

• propose-prompt-optimization and the phase system prompt are active only while a phase is running.
• Interactive (TUI) mode and a selected model are required to start.
• If the session is reloaded mid-phase (new session runner), previously captured command contexts are invalidated, so Accept/Cancel finish automatically by self-dispatching an internal extension command, which receives a fresh command context from the current runner. /prompt-optimize end remains available as an explicit abort at any time.

Development

From a local checkout, install and verify:

pnpm install
pi install .            # install the checkout into the active pi config
# project-local install:  pi install -l . --approve
pnpm typecheck          # tsc --noEmit
pnpm test               # Node test runner (unit tests in test/)
pnpm sync:skills        # refresh skills/writing-for-agents from the upstream submodule

Acknowledgements

• Matt Pocock's skills — the writing-for-agents optimization methodology comes from this repository, which this package vendors under skills/ (refresh with pnpm sync:skills).
• pi-codex-goal — the durable phase design (state stored in pi session custom entries so it follows session history, resume, fork, tree navigation, reload, and compaction) replicates the pattern from this project.