@ramarivera/pi-goal

Pi extension that adds Codex-style persisted goals, /goal commands, model goal tools, and hidden continuation pressure.

Install

After the package is published:

pi package install @ramarivera/pi-goal

The publishable extension source is:

src/index.ts

For local development, Pi discovers the project-local shim from:

.pi/extensions/pi-goal/index.ts

That shim imports the real source entrypoint and is intentionally not part of the package payload. To avoid collisions when the published package is also installed globally, the project-local shim registers /local-goal and local_get_goal / local_create_goal / local_update_goal.

Commands

/goal <objective>
/goal <objective> --budget 10000
/goal status
/goal pause
/goal resume
/goal clear

Creating a goal also submits the objective as the next user message after the goal state is persisted, so the agent starts working on it immediately.

In interactive Pi sessions, /goal status opens a compact overlay with the objective, lifecycle status, usage, budget, elapsed time, and model breakdown. In non-interactive modes it falls back to the plain text status notification.

When developing from this repository with the global package installed, use the local command names:

/local-goal <objective>
/local-goal <objective> --budget 10000
/local-goal status
/local-goal pause
/local-goal resume
/local-goal clear

See docs/pi-goal-extension.md for behavior and test details.

Skill

This package also ships a goal skill under skills/goal/SKILL.md that helps Pi recognize when a persisted-goal workflow is appropriate and guides users toward effective objective writing, budget control, and completion auditing.

The skill covers:

• When to use /goal vs regular chat
• How to write specific, verifiable objectives
• Understanding the completion audit
• Budget guidance and lifecycle behavior
• Examples: migration campaigns, test coverage, lint sweeps

Tracing

pi-goal writes structured Pino JSON logs for goal state changes, /goal commands, model tools, lifecycle hooks, hidden continuation scheduling, context pruning, token accounting, and suppression decisions.

Default log file:

~/.pi/logs/pi-goal.log

Environment variables:

PI_GOAL_LOG_LEVEL=debug
PI_GOAL_LOG_FILE=/tmp/pi-goal.log
PI_GOAL_LOG_FILE=stdout
PI_GOAL_LOG=0

Logs intentionally include goal ids, statuses, counters, usage, and scheduling reasons, but not full continuation prompts or objective text.