@leing2021/pi-goal

pi-goal

简体中文

Pi extension for autonomous goal-driven execution.

Set a goal, and pi works on it across multiple turns — resuming across sessions — until the model calls finish_goal, the turn limit is reached, or you interrupt.

Quickstart

# Test without installing
pi -e ./goal/index.ts

# Inside pi, set a goal
/goal "Write a hello-world TypeScript CLI"

Install

# Symlink into the global extensions directory
mkdir -p ~/.pi/agent/extensions/goal
ln -s "$(pwd)/goal" ~/.pi/agent/extensions/goal/

Then in any pi session: /reload to load, or restart pi.

Commands

Command	Description
/goal "objective"	Set a new goal and start working
/goal status	Show current goal status
/goal stop	Stop and clear the current goal

Tools (LLM-callable)

Tool	Description
finish_goal	Mark the goal as completed with a summary

How it works

• /goal "build a feature" sets an active goal
• The extension injects goal context into the system prompt
• After each turn, if the goal is active and under the turn limit, pi gets a follow-up message to continue
• When the model decides the goal is achieved, it calls finish_goal with a summary
• Goal state persists across sessions — resuming pi resumes the active goal

Stop conditions

• Model calls finish_goal → completed
• Turn count reaches max (10 default, 20 in super-pi mode) → paused
• You press Esc or interrupt
• You run /goal stop

Super-pi mode

If 02-plan and 03-work skills are detected, the extension enables super-pi mode:

• Max turns: 20 (instead of 10)
• System prompt includes pipeline guidance: 02-plan → 03-work → 04-review

Development

npm install
npm test        # run all tests
npm run typecheck

Project structure

goal/
├── index.ts      # Extension factory — registers commands, tools, handlers
├── types.ts      # GoalEntry, GoalStatus types
├── state.ts      # Pure functions: createGoal, clearGoal, restoreGoalFromEntries
├── commands.ts   # Command handler: stop / status / create goal
├── loop.ts       # shouldContinueLoop, buildFollowUpMessage
├── prompt.ts     # buildGoalSystemPrompt, buildSuperPiGuidance
└── super-pi.ts   # detectSuperPi
tests/            # One test file per source module

Troubleshooting

Issue	Cause	Fix
Extension not loaded after /reload	Symlink target moved or broken	Re-run the ln -s command from the repo root
Goal resets after restart	/reload clears in-memory state	State is recovered from session branch on next session_start — this is expected
pi asks for API key	No provider configured	Run pi --login or pi --provider <name> --api-key <key>

Installation Guide

Should you install pi-goal?

pi-goal is a lightweight, standalone extension. Whether you need it depends on your existing setup:

If you have super-pi installed

You likely don't need pi-goal. Super-pi already provides a complete goal-driven workflow:

Feature	pi-goal	super-pi
Goal-driven execution	/goal command	Built-in 5-step loop
Cross-session resume	✅ Turn-based	✅ Unit-based checkpoint
Multi-turn autonomy	10 / 20 turns	Full pipeline with TDD gates
Stop conditions	Manual / turn limit	TDD gates + 5-axis review
Planning & review	❌	✅ brainstorm → plan → review → learn

Super-pi's 03-work skill already provides checkpoint resume at the implementation-unit level, which is more granular than pi-goal's turn-based approach. Its 06-next skill recommends the next step automatically.

Principle: don't install what you already have.

When pi-goal is the right choice

• Standalone pi user — you use pi without super-pi and want a simple autonomous loop
• Quick tasks — you need a lightweight "set and forget" mechanism without the full planning/review overhead
• Learning / experimentation — you want to understand how pi extensions work, or build your own extension based on this pattern
• Custom pipeline — you want to combine pi-goal with your own skills, not super-pi's built-in pipeline

Install

# Symlink into the global extensions directory
mkdir -p ~/.pi/agent/extensions/goal
ln -s "$(pwd)/goal" ~/.pi/agent/extensions/goal/

Then in any pi session: /reload to load, or restart pi.

Uninstall

rm ~/.pi/agent/extensions/goal

Safety

• Hard stop at turn limit — no runaway loops
• Follows pi's built-in permission system — won't auto-approve destructive actions
• Esc always interrupts

License

MIT