@tduyng/pi-goal0.0.2

@tduyng/pi-goal

Keep working toward an explicit objective without typing "continue" after each run. Goals survive reload and tree navigation, track token use, and pause when output repeats or a token budget runs out.

/goal command

Set a long-running objective with an optional token budget:

/goal refactor the auth module to use JWT refresh tokens
/goal with token budget 50000 migrate the database schema

Subcommands: edit (opens the objective in an editor), budget <tokens|off> (set, raise, or remove the token budget), check <command|off> (the command that must exit 0 before the goal can complete), pause, resume, clear. Raising the budget past current spend resumes a budget-limited goal.

Tools

• create_goal: the model creates a goal when the user explicitly asks. Objective max: 4,000 characters. Fails if an unfinished goal exists. A complete goal is replaced. When no token_budget is set, the response includes an advisory that spend is unbounded.
• get_goal: returns the current goal's status, token and time usage, remaining budget, and thread ID.
• update_goal: mark the goal complete or blocked after verifying the required conditions. Pass notes (max 3,000 characters) to replace the progress notes. complete runs the goal's check first and is refused unless it exits 0. The model should not mark a goal complete merely because the budget is nearly exhausted or because it is stopping work.

Goal tools enter the active set while a goal is active or the user asks to create one. Otherwise their schemas stay out of the model request.

Automatic continuation

After a successful agent run, the extension queues a continuation prompt so the model keeps working without user input. Standing orders live in the system prompt (byte-stable for prompt cache). Live counters (elapsed time, tokens used) ride in the continuation message at the request tail.

Only one continuation fires per turn. If the loop extension also queued a prompt, the hasPendingMessages() guard ensures exactly one wins.

Runaway detection

If the same tool-free output repeats 3 times in a row, the extension pauses the goal. Any tool call resets the streak.

Stagnation nudge

After 5 goal turns with no successful edit or write tool result, the continuation message carries a line naming the count and asking for the next concrete change, or for the blocked audit when a blocker keeps repeating. User input resets the count. The nudge never pauses the goal.

Auto-continuation

There is no fixed cap: a goal keeps queueing continuations until it completes, is paused, or hits its token budget. Stop one that is going nowhere with /goal clear.

Token counting

Only input and output tokens count toward the goal budget. cacheRead and cacheWrite are excluded because providers report them as separate fields.

Completion check and notes

create_goal with check, or /goal check <command>, sets a shell command such as bun test. update_goal with status complete runs it first. A failing check keeps the goal active and returns the output to the model. /goal check off removes it.

The progress notes hold what is done, what failed and what is next. They are sent again in the next continuation after a compaction or a resume. A note written in a turn is already in that turn's context, so it is not repeated.

Status bar

Shows elapsed time, token usage, and budget during active pursuit. Other states display as Goal paused, Goal blocked, Goal hit usage limits, Goal budget reached, or Goal complete.

/loop command

Repeat a prompt on a fixed interval (e.g. 5m, 1h, 30s) or after each agent run settles:

/loop 5m check for failing CI jobs
/loop review recent work and fix unfinished items
/loop stop

Starting a loop fires the first prompt immediately. /loop and /goal share the pending-message guard to avoid duplicate continuations. Loop state is session-scoped. The timer dies with the pi process. For durable scheduled runs across restarts, use pi -p "<prompt>" from an OS scheduler.

Interval format: a number followed by a unit. Supported units: ms, s, m, h, d. Bare numbers without a unit are not supported to avoid silent misinterpretation.

Self-paced mode fires 250ms after agent_settled, once pi's own retries and compactions have finished. The default prompt when none is provided: "Run a maintenance check: review recent work and address anything stale, broken, or left half-finished."

Subcommands: stop (also cancel, clear, off), or bare /loop to show status. The status bar shows the pace label (e.g. Loop every 5m (3)) and iteration count.

Design

The extension persists state as custom session entries, without an external database. Resuming a saved session restores its goal. Interval loops re-arm on resume, firing immediately if their interval has elapsed. The extension does not create goals automatically from ordinary tasks and does not reimplement timeout or retry logic that pi already handles.

Crash resume

Reopening a session whose goal was mid-turn when the process died queues one continuation, so the run picks up instead of waiting for the user to type. A turn that ended on a user message, a tool result, or a tool call that never ran counts as cut off. A turn the user aborted, or one that ended in an error, does not: the first was their own stop, and the second is what pi-goal already pauses on. The resume counts as an automatic continuation, and only an interactive session resumes, because a headless run has no editor to send a message from. A resume pi refuses, because it is already replaying the interrupted turn, says nothing: the goal continues from that turn's own settle.

Blocked and completion audits

The standing orders in the system prompt require the model to verify completion against the actual current state before marking a goal complete. For blocked status, the same blocking condition must repeat for at least 3 consecutive goal turns before the model calls update_goal with status blocked. Resuming a previously blocked goal resets the count.

Budget resume

When resuming a goal that hit its token budget, the extension raises the budget to tokensUsed + 50,000 so the next turn can proceed. The status bar notes the raised budget.

Prompt matching

The promptRequestsGoal heuristic requires an action verb (create, set, start, new, add, track, pursue, manage, establish) plus a goal noun, or the phrase "long-running". A bare "goal" does not enable the tools.

Install

pi install npm:@tduyng/pi-goal

Local checkout: pi install /path/to/dotfiles/pi/agent/extensions/pi-goal

No configuration is required.