@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_present | Record the contract (Outcome, Done criteria, Decision philosophy, Ask-before boundaries) when presenting it to the user; call this right when you show the contract | | goal_set | Activate the latest confirmed setup — checks that goal_present was called with a matching objective | | 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
  -> assistant calls goal_present to record the contract
  -> user approves the contract
  -> assistant calls goal_set (checks goal_present was called + objective match)
  -> 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 confirmed=true, a matching objective, and a prior goal_present call that recorded the 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/[email protected]/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, debug, and structured message helpers | | index.test.ts | Regression tests | | messages.test.ts | Structured message and toolResponse helper tests | | .github/workflows/publish.yml | Trusted publishing workflow |