# pi-codex-goal Codex-style goal tracking for pi. This package adds a `/goal` command plus three model-callable tools: - `get_goal` - `create_goal` - `update_goal` Goal state is stored in pi session custom entries, so it follows session history, resume, fork, tree navigation, reload, and compaction behavior without an external database. ## Install Install from npm: ```sh pi install npm:pi-codex-goal ``` Install a pinned npm version: ```sh pi install npm:pi-codex-goal@ ``` Install from GitHub: ```sh pi install https://github.com/fitchmultz/pi-codex-goal ``` Install a pinned GitHub release: ```sh pi install https://github.com/fitchmultz/pi-codex-goal@v ``` For local development from this repository: ```sh npm install pi install . ``` Compatibility note: this package is tested against the current pi release during each package update, and pi-bundled runtime packages are declared as optional wildcard peers. That keeps installs forward-open for future pi releases: npm peer ranges should not block users from trying a newer pi, though runtime behavior is only verified against the tested baseline until a follow-up package release confirms it. Release note: npm installs and pinned GitHub tags are the reproducible release artifacts. Installing from the repository default branch can include unreleased changes that will ship in a future package release, even when `package.json` still identifies the latest published version. ## Best way to create goals Use the included `/create-goal` prompt template instead of writing a goal by hand. Agents write better goal completion contracts than humans do because they can expand a plain task into outcome, verification, constraints, iteration, audit, and blocked-stop requirements before calling the `create_goal` tool. ```text /create-goal insert task and requirements here ``` The template follows the Codex goal-writing practices from: - - ## Development Validate types and tests before committing or opening a PR: ```sh npm run verify ``` Cross-platform release-sensitive changes should also pass the local Crabbox platform smoke gate: ```sh npm run check:platform-smoke npm run smoke:platform:all ``` `smoke:platform:all` runs the doctor before any target suite. That gate runs `npm run verify`, packs the package, installs the packed package into a clean pi project, checks `pi list`, and runs a real model-backed goal-tool smoke on macOS, Ubuntu Linux, and native Windows. The runtime smoke defaults to `zai/glm-5.1`; override it with `PLATFORM_SMOKE_MODEL` and configure forwarded auth env vars with `PLATFORM_SMOKE_AUTH_ENV`. Setup and artifact details: [docs/platform-smoke.md](docs/platform-smoke.md). Project agent notes and module map: [AGENTS.md](AGENTS.md). Latest structural audit: [docs/CODEBASE_AUDIT.md](docs/CODEBASE_AUDIT.md). ## Interactive smoke test This smoke test exercises the interactive `/goal` command, hidden continuation, bridged goal tools, filesystem verification, and final `update_goal` completion. Prerequisites: - Pi can authenticate to any capable model available in your local setup. Start pi from this repository: ```sh rm -f /tmp/pi-codex-goal-slash-smoke.txt rm -rf /tmp/pi-codex-goal-slash-smoke-session pi --model \ --session-dir /tmp/pi-codex-goal-slash-smoke-session ``` Then paste this into the interactive TUI: ```text /goal Create /tmp/pi-codex-goal-slash-smoke.txt containing PI_GOAL_SLASH_OK, verify the file content from the filesystem, inspect the current goal, and mark the goal complete only after verification. Final reply must include the verified file path, verified content, and final goal status. ``` Expected final evidence: ```text Verified file path: /tmp/pi-codex-goal-slash-smoke.txt Verified content: PI_GOAL_SLASH_OK Final goal status: complete ``` `/goal` is an interactive editor command. Do not use `pi -p '/goal ...'` as a slash-command smoke path; print mode sends an initial model prompt and is not a reliable way to exercise this extension command. For headless automation, prompt the model to call the `create_goal`, `get_goal`, and `update_goal` tools instead of relying on slash-command parsing. ## User Commands ```text /create-goal Build the requested feature and verify it end to end /goal /goal Build the requested feature and verify it end to end /goal pause /goal resume /goal clear ``` `/create-goal ` is the recommended way to start a goal. It expands the task into a strict objective and asks the model to call the `create_goal` tool. `/goal` with no arguments reports the current objective, status, token budget, token usage, and elapsed active time. A plain `/goal ` starts a new goal or replaces the current one after confirmation. This intentionally matches Codex TUI behavior: token budgets are set through the model tool rather than parsed from `/goal --tokens`. This package keeps its objective size limit at 8000 Unicode characters. ## Model Tools `create_goal` starts a goal with an objective and optional positive token budget. It fails if a non-complete goal already exists. After a goal is complete, `create_goal` replaces it with a new active goal. `get_goal` returns the current goal state and usage. `update_goal` only accepts `status: "complete"`, matching Codex's model-side contract. Calling it on an already-complete goal is idempotent and does not append duplicate session entries. The extension reports final token and elapsed-time usage before marking the goal complete. Completed goals are terminal for automatic transitions: pause, resume, and hidden continuations do not reopen them. To recover from premature completion, use `/goal ` to replace the goal or `/goal clear` before starting again. In bridged MCP environments, pi may expose these tools under namespaced MCP names like `pi__get_goal`, `pi__create_goal`, and `pi__update_goal`. Prompt guidance tells models to call whichever goal-tool name is actually exposed in the current run, not display or transcript labels. ## Behavior While a goal is active, the extension: - tracks elapsed active time between turns and tool completions - adds completed assistant turn input plus output token usage when the active model reports it - coalesces runtime goal custom-entry writes so unchanged status and usage are not appended on every tool completion; live footer usage stays current, and meaningful usage is flushed at turn boundaries, shutdown, compaction, budget crossings, and bounded intervals during long tool-heavy runs - pauses when an active assistant turn is aborted, such as when you press Esc - recovers from provider assistant errors without immediate hidden continuation loops: context-window overflow triggers automatic compaction and then resumes the active goal, transient errors use bounded backoff retries, and repeated unrecoverable failures pause with a clear `/goal resume` path - prompts on session resume before reactivating a paused goal, and resumes explicitly with `/goal resume` (only from paused) - rejects `/goal pause` unless the goal is active and `/goal resume` unless the goal is paused - treats completed goals as terminal for automatic transitions while allowing `/goal ` to replace them without extra friction - marks the goal `budgetLimited` when a positive token budget is reached - sends hidden steering messages when budget is reached or when the agent is idle but the goal is still active - compacts repeated hidden goal continuations before provider context so only the latest active continuation stays runnable, older ones become short bookkeeping markers, and auto-queued continuations use a compact prompt after `/goal` start or resume - shows Codex-style status labels with compact token or elapsed-time usage in the pi footer when UI is available Token counts are formatted with commas and compact abbreviations, for example `123M (123,456,789) tokens`. Token totals use pi's completed assistant turn input plus output usage. Cache read and cache write channels are excluded because they are provider cache accounting fields, not extra sent and received text tokens. Pi does not currently expose a separate extension usage total for automatic compaction summary calls.