@tduyng/pi-goal

Long objectives that survive a reload and a tree switch, count what they spend, and stop when the budget runs out.

A task with more work than one turn needs an objective written down and a way to continue without typing "continue" every time. A goal is that objective, an optional token budget, and an optional check command.

create_goal is 345 tokens and deferred. It joins the session when the request asks for a goal, which is the only time it is needed before one exists, or through codemode at any other time. get_goal and update_goal join it the moment a goal is created, not at the next turn boundary, and stay for the session since dropping a tool again rewrites the front of every later request. They are 364 tokens a request when active, and 9 of 97 recorded sessions ever held a goal, so a session that never does now carries none of the three.

Completion needs a command

A goal can carry a check such as bun test, and update_goal cannot mark the goal complete unless that command exits 0. A model can be wrong about whether the tests pass. A command cannot. When the check fails, the output goes back to the model and the goal stays active.

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

| Subcommand | Effect | | --- | --- | | /goal edit | Open the objective in an editor | | /goal budget <tokens\|off> | Set, raise or remove the budget | | /goal check <command\|off> | The command that must exit 0 before completion | | /goal pause | Stop queueing continuations | | /goal resume | Start them again | | /goal clear | Drop the goal |

Raising the budget past current spend resumes a budget-limited goal. Three tools back it: create_goal, get_goal, update_goal. notes replaces the progress notes, up to 3,000 characters, and those notes are what a later turn after a compaction starts from.

Cache behaviour

Standing orders live in the system prompt and never change, so they ride in the cached prefix instead of invalidating it. Live counters, elapsed time and tokens used, travel in the continuation message at the request tail, which is not cached anyway.

Pausing is defensive rather than a fixed cap. Runaway detection fires when the same tool-free output repeats three times in a row, and again after seven turns that land nothing, because a loop that paraphrases never repeats a fingerprint: one print session spent twenty turns saying the goal was complete and that no tool existed to mark it. A stagnation nudge arrives after five goal turns with no successful edit or write, names the count, and asks for the next concrete change. The budget remains the only hard stop on a goal that is making progress.

Only input and output tokens count toward the budget. cacheRead and cacheWrite are excluded, since providers report them as separate fields and counting them would end a goal on a warm prefix.

Loops

/loop 5m check for failing CI jobs refires a prompt on an interval. A loop with no prompt runs a maintenance check after each settle: review recent work and address anything stale, broken or half-finished.

/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. The interval is a number plus ms, s, m, h or d, and a bare number is refused rather than guessed at. Self-paced mode fires 250ms after agent_settled, once pi's own retries and compactions are done.

/loop composes with /goal instead of reimplementing it: exactly one continuation fires per turn, decided by hasPendingMessages(). Loop state is session-scoped and its timer dies with the process. For a run that must survive a restart, use pi -p from an OS scheduler.

After a crash

State lives in custom session entries, with no external database, so resuming a session restores its goal. An interval loop re-arms and fires at once if its interval passed.

A goal that was mid-turn when the process died gets one continuation when the session reopens. A turn that ended on a user message, a tool result, or a tool call that never ran counts as cut off.

A turn aborted, or one that ended in an error, does not. An aborted turn was a deliberate stop, and an errored turn is what the goal already pauses on. Only an interactive session resumes, because a headless run has no editor to send a message from.

A goal that hit its token budget resumes with the budget raised to usage plus 50,000 tokens, and the status bar says so.

Install

pi install npm:@tduyng/pi-goal

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

No configuration. A check command needs a shell, and nothing else.

/create-goal in ../prompts/create-goal.md expands a plain task into a strict objective and calls create_goal. The objective quality decides whether the loop stops early, so use it for anything long-running.

Limits

• An objective is capped at 4,000 characters and notes at 3,000. A goal that does not fit in a page is a plan, and a plan belongs in a file.

• The check has a 300 second timeout and returns 1,500 bytes, so it is a gate and not a test report.

• The extension never creates a goal from an ordinary task. A request has to name the intent, either an action verb with a goal noun or the phrase "long-running", or /goal has to be run deliberately.

• /goal clear is the way out of a goal that is going nowhere. Nothing caps continuations, because the goal decides when it is done, and the budget decides when it is not.