🎯 pi-goal — Goal Mode for the Pi Coding Agent

@xbear/pi-goal is a native Pi coding agent extension that adds session-scoped /goal commands and a goal_complete({ goal_id, summary }) tool for autonomous, verifiable task completion.

This is a fork of @narumitw/pi-goal that adds print-mode (non-interactive pi -p) support — /goal now works both interactively (tui) and from the command line (pi -p "/goal ..."). See Print mode below.

Goal mode uses Codex-like persistence instructions and keeps sending guarded continuation messages until the agent calls goal_complete, the user pauses or clears the goal, an interrupt/error pauses the goal, or an optional token budget is reached.

✨ Features

• Adds /goal <goal_to_complete> to start goal mode, with confirmation before replacing an existing goal.
• Works in both interactive (tui) and non-interactive print/json mode — drive a goal to completion from the CLI with pi -p "/goal ...".
• Bare /goal shows the current goal summary.
• Keeps advanced goal management inside /goal subcommands: pause, resume, clear, and edit.
• Exposes only one top-level command: /goal.
• Supports optional token budgets such as /goal --tokens 100k <goal>.
• Tracks active, paused, budget_limited, and complete states.
• Stores goal state in the current Pi session, following Codex's thread-owned goal model instead of using a global per-directory goal.
• Registers a goal_complete({ goal_id, summary }) tool for explicit completion, requiring the current goal id and rejecting missing/stale ids plus plainly contradictory summaries such as “not complete” or “tests still fail”.
• Automatically prompts the agent to continue if an active turn ends early, directly triggering the next turn when Pi is idle and no pending messages are queued.
• Pauses and aborts queued goal work when the user pauses a goal or Pi reports a non-retryable aborted/errored assistant turn.
• Keeps retryable provider interruptions and Pi compaction retries active without enqueueing duplicate goal continuations while Pi retries.
• Preserves active goals across manual, threshold, and overflow compaction.
• Guards auto-follow-ups so duplicate, replaced, paused, cleared, completed, or budget-limited goals are not continued.
• Rotates the completion guard id when a goal is resumed or edited so delayed old turns cannot complete the newer goal instance.
• Blocks stale tool calls after pause or non-retryable interruption.
• Encourages requirement-by-requirement verification before the goal is marked complete.

📦 Install

pi install npm:@xbear/pi-goal

Try without installing permanently:

pi -e npm:@xbear/pi-goal

Install from git (no npm account needed):

pi install git:github.com/xbeark/pi-goal
# or
pi install https://github.com/xbeark/pi-goal

Try locally without installing permanently (from a clone of this repo):

pi -e .

🚀 Commands

/goal
/goal implement snake game
/goal --tokens 100k fix the failing test and verify it
/goal edit ship the smaller fix first
/goal pause
/goal resume
/goal clear

• /goal shows the current goal, status, iteration count, elapsed time, token usage, and available /goal subcommands.
• /goal <goal_to_complete> starts goal mode. If another unfinished goal exists, Pi asks for confirmation before replacing it with a new active goal and resetting its usage counters.
• /goal --tokens 100k <goal_to_complete> starts or replaces goal mode with a token budget. k and m suffixes are accepted, for example 100k or 1.5m.
• /goal edit <goal_to_complete> updates the existing goal objective without resetting usage counters. Active goals stay active, paused goals stay paused, and budget-limited goals remain budget-limited if their budget is still exhausted.
• /goal pause stops prompt injection and auto-continuation, aborts the current turn, and keeps the goal for later resume.
• /goal resume resumes a paused or budget-limited goal when the token budget allows it, then queues a resume prompt so work continues.
• /goal clear clears the current goal state, status, pending continuation, and legacy persisted state for the current working directory without aborting any in-flight agent turn.

Goal objectives are limited to 4,000 characters. Put longer instructions in a file and reference the file path from /goal.

🖨️ Print mode (non-interactive / pi -p)

/goal also works in Pi's non-interactive print/json mode, so you can drive a goal to completion from the command line and exit:

pi -p "/goal implement snake game" --provider <provider> --model <model> -a

In print/json mode the /goal command blocks until the goal settles (complete, paused, budget_limited, or cleared), keeping the process alive through the whole continuation loop. In interactive (tui) mode the behavior is unchanged: /goal returns immediately and the goal runs in the background while you keep typing.

Why this is needed: Pi's extension-facing pi.sendUserMessage is fire-and-forget, so the /goal command handler would otherwise return before the agent runs. In tui mode the session persists and the loop runs in the background; in print mode (pi -p) the process would exit and dispose the runtime the moment the handler returns, killing the just-started agent. The command therefore awaits a goal-settled signal in non-interactive mode only.

🔁 Session and reload behavior

Goal state is stored as Pi session state, similar to Codex's thread-owned goals. /reload and reopening the same Pi session can restore that session's unfinished goal. Starting a new Pi session in the same working directory does not inherit the old goal.

Older versions wrote unfinished goals to ~/.pi/agent/pi-goal-state.json keyed by working directory. This version no longer reads that global file, and /goal clear removes any legacy entry for the current working directory.

📊 Statusline states

pi-goal writes compact plain status strings for statusline extensions. @narumitw/pi-statusline adds the default 🎯 icon unless configured otherwise:

• active 3m — an active goal without a token budget.
• active 18k/100k — an active goal with token usage and budget.
• paused — auto-continuation is paused.
• budget 100k/100k — the token budget was reached; auto-continuation stops.
• complete — shown briefly after goal_complete succeeds.

✅ How completion works

While a goal is active, pi-goal injects persistence rules, a <goal_id> stale-turn guard, and exposes goal_complete. To finish, the agent must call goal_complete with the exact current goal_id and a summary of completion evidence. Missing or stale goal_id values are rejected before summary validation, and paused goals cannot be completed until resumed. Empty or plainly contradictory summaries are also rejected; the summary is completion evidence, not the stale-turn safety token.

If a turn ends before completion, pi-goal records usage and sends one guarded continuation only when no other messages are pending.

🛑 Interruption and queued-input behavior

On user pause, abort, or non-retryable error, pi-goal pauses the goal, aborts stale work, and blocks stale tool calls until the next user prompt (non-extension input), /goal resume, or /goal clear. On /goal clear, it clears goal state, pending continuation markers, and any stale tool-call block; it does not abort the current turn. Retryable provider interruptions and overflow compaction retries stay active while Pi retries; no extra continuation is queued.

🧠 Use cases

• Finish implementation tasks without stopping at a plan.
• Keep debugging until the bug is verified fixed.
• Run refactors that require multiple tool cycles.
• Encourage agents to test, lint, or typecheck before completion.
• Make long-running Pi coding sessions more autonomous.

🗂️ Package layout

pi-goal/
├── src/
│   └── goal.ts
├── test/
│   └── goal.test.ts
├── README.md
├── LICENSE
├── tsconfig.json
└── package.json

The package exposes its Pi extension through package.json:

{
  "pi": {
    "extensions": ["./src/goal.ts"]
  }
}

🔎 Keywords

Pi extension, Pi coding agent, goal mode, autonomous coding agent, AI agent workflow, task completion, agent loop, verification, TypeScript Pi package.

📄 License

MIT. See LICENSE.