@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.

Nothing until a goal exists. The three tools are deferred, so they are not declared to the model and enter the active set only while a goal is active or a request asks to create one. A session that never touches a goal pays no tokens for this package.

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

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. A stagnation nudge arrives after five goal turns with no successful edit or write, names the count, and asks for the next concrete change. Neither stops the work, and the budget is the only hard stop.

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.