@qhn/pi-goal

Setup-first autonomous goal mode for Pi.

@qhn/pi-goal lets Pi pursue one objective across follow-up turns. It does not start autonomous work immediately: /goal <intent> first opens a setup interview so the assistant and user agree on outcome, done criteria, decision style, and ask-before boundaries.

Install

pi install npm:@qhn/pi-goal

Try without installing:

pi -e npm:@qhn/pi-goal

Commands

Command	Behavior
/goal <intent>	Start setup mode for a new goal
/goal status	Show current setup or goal state
/goal pause	Pause autonomous continuation
/goal resume	Resume a paused or blocked goal
/goal cancel	Cancel setup or active goal state
/goal help	Show command help

Agent tools

Tool	Purpose
goal_set	Activate the latest confirmed setup after user approval
goal_get	Inspect setup/goal state, budget, usage, and remaining tokens
goal_status_line	Update short current-progress text in the status line
goal_complete	Mark the active goal complete after evidence proves it is done

goal_complete is intentionally narrow. Pause, resume, and cancel stay user-controlled through /goal commands.

Goal flow

/goal <intent>
  -> Pi asks setup questions
  -> assistant summarizes the goal contract
  -> user approves the contract
  -> assistant calls goal_set
  -> Pi continues while idle
  -> assistant updates progress with goal_status_line
  -> assistant calls goal_complete only after proof

Setup contract

Before activation, the assistant must resolve:

Contract part	Meaning
Outcome	What should be true when the goal finishes
Done criteria	Evidence required before completion
Decision philosophy	How trade-offs should be made during autonomous work
Ask-before boundaries	Actions that require explicit user approval

Status line

State	Example
Setup	/goal ◇ setup: ship the package
Working	/goal ◇ ◴ verifying package
Paused	/goal ◇ Ⅱ paused: verifying package
Waiting on user	/goal ◇ ? answer needed: choose release target
Blocked	/goal ◇ BLOCKED! no progress — /goal resume
Budget blocked	/goal ◇ BLOCKED! budget limit reached
Done	/goal ◇ ✓ goal complete, then clears after the completion turn

Color is decoration only; glyphs and text carry the meaning. In terminals that support ANSI styling, /goal is bold and the working clock glyph is yellow.

Safety rules

Rule	Behavior
Setup first	/goal <intent> never activates directly
Explicit approval	goal_set requires a confirmed setup contract
User input wins	Pi does not continue over queued or pending user messages
No-work stop	A no-tool autonomous turn blocks with /goal resume guidance
Evidence before done	goal_complete should be called only after the done criteria are proven
Session-local state	Goal state is stored in Pi session entries, not a separate database

Pi package manifest

package.json declares the Pi package resources explicitly:

{
  "keywords": ["pi-package", "pi-extension", "pi", "goal", "goal-mode", "autonomous-agent", "status-line", "agent"],
  "pi": {
    "extensions": ["./extensions/goal.ts"],
    "image": "https://unpkg.com/@qhn/pi-goal@0.2.0/assets/pi-goal-status.png"
  }
}

Development

npm install
npm test
npm run test:ui
npm run verify:pi
npm run verify:package
npm run pack:dry-run

npm run test:ui writes terminal-render artifacts under codex-scripts/goal-ui/; those artifacts are local test output and are not part of the npm package.

Package contents

Path	Purpose
package.json	npm metadata and Pi package manifest
assets/pi-goal-status.png	Pi package gallery preview image
extensions/goal.ts	Pi extension entrypoint
extensions/goal/	State, prompt, format, and debug helpers
index.test.mjs	Regression tests
.github/workflows/publish.yml	Trusted publishing workflow