@lhl/pi-goal

Lightweight /goal mode for pi with optional @tintinweb/pi-tasks awareness.

Fork lineage. Forked from code-yeongyu/pi-goal@59b39e8 as the engineered base (strict TS, biome, tsgo, vitest, typed errors). UX patterns borrowed from Michaelliv/pi-goal (compact display:true continuation badge, --tokens 50k slash-flag, reload-auto-pause). The NO_TOOL_CALLS runaway-loop safety pause is borrowed from PurpleMyst/pi-goal. pi-tasks integration (discovery, <task_list> snapshot injection, complete-gate, /goal tasks shortcut) is new in this fork.

Install

This fork isn't published to npm. Install from git:

pi install git:github.com/lhl/pi-goal

Or load directly for development:

pi -e ./src/index.ts

Commands

/goal <objective>              Set a new goal (replaces with confirmation if one exists)
/goal --tokens 50k <objective> Set a goal with a token budget (k/M suffixes ok)
/goal tasks [extra prose]      Shortcut: objective = "Complete all open tasks…"
/goal                          Show current goal status
/goal pause                    Pause autonomous continuation
/goal resume                   Resume a paused goal
/goal clear                    Drop the current goal
/goal tokens [N|off]           Show, set, or clear the budget on the active goal
/goal allow-open-tasks [on|off]  Override the pi-tasks complete-gate for this goal

Once active, every agent_end queues a hidden-but-visible continuation prompt that drives the next turn. The transcript shows a compact Goal · continuing badge for each iteration; press ctrl+o to expand and inspect the full prompt the model received.

Tools registered with the model

• get_goal({}) — read the active goal: objective, status, tokens used, time used, remaining budget.
• update_goal({ status: "complete" }) — only accepts complete. Refuses if pi-tasks has open tasks. Pause/resume/clear are user-controlled, not model-callable.

Safety behaviors

• Reload-auto-pause. A Pi reload of an active goal pauses it with a notify; no model-visible event. The agent does not silently resume on reopen — you have to /goal resume explicitly.
• NO_TOOL_CALLS pause. If a continuation-triggered turn produces zero tool calls, the next agent_end pauses the goal with a warning. Prevents runaway loops when the model is stuck producing only text.
• Budget-limited. When tokensUsed >= tokenBudget, the goal transitions to budgetLimited and the model gets a "wrap up" prompt instead of more continuations.

pi-tasks integration

If @tintinweb/pi-tasks is loaded in the same pi session, @lhl/pi-goal discovers its task store at the standard paths (honors PI_TASKS env, .pi/tasks-config.json taskScope, session/project defaults) and:

• Injects a <task_list> snapshot into every continuation prompt with pending / in-progress / blocked / completed counts plus the next 20 open tasks (id, subject, status, blockers).
• Stands down when pi-tasks is driving. If pi-tasks' autoMode is cascade or auto and there's already a queued follow-up prompt at agent_end, pi-goal skips its own continuation. The goal loop re-enters whenever pi-tasks runs out of unblocked work.
• Gates goal completion on open tasks. update_goal complete returns a structured error if any pi-tasks task is still pending or in_progress. Override per-goal with /goal allow-open-tasks on if you genuinely want the model to be able to declare done while tasks remain (or use /goal clear to abandon entirely).

Quick TaskList workflow

TaskCreate {…}   TaskCreate {…}   TaskCreate {…}
/goal tasks

That's the whole workflow. The agent runs the list to empty, then audits and calls update_goal complete. If the audit reveals leftover work or the model gets confused mid-loop, you have /goal pause and /goal clear as exits.

State

Goal state lives as pi.appendEntry("pi-goal-state", { goal }) records in the active session branch. No filesystem store, no external database — the most recent entry on the branch is the source of truth, restored on session_start. Reload semantics, pause/resume, and budget transitions are all pure session data.

Development

npm install
npm test            # vitest, 69 tests across 11 files
npm run typecheck   # tsgo --noEmit
npm run lint        # biome check .
npm run check       # tsgo + biome + custom no-excuse rules

Differences from the upstream code-yeongyu/pi-goal

Area	Upstream	This fork
Tools	create_goal, update_goal, get_goal	update_goal, get_goal (goals are user-created via /goal)
Storage	~/.pi/agent/extensions/pi-goal/<thread>.json on disk	Pi session entries (pi.appendEntry) — no fs writes
Reload	Prompts the user to resume a paused goal	Auto-pauses an active goal, notifies, requires /goal resume
Continuation visibility	display: false (hidden from transcript)	display: true with a compact Goal · continuing (ctrl+o) renderer
Slash command	/goal <objective> only	adds --tokens N flag and /goal tasks shortcut
Stuck-model safety	none	NO_TOOL_CALLS auto-pause (PurpleMyst pattern)
pi-tasks integration	none	discovery + snapshot inject + complete-gate + cascade-stand-down

License

MIT, inherited from upstream.