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

1. /goal "build a feature" sets an active goal
2. The extension injects goal context into the system prompt
3. After each turn, if the goal is active and under the turn limit, pi gets a follow-up message to continue
4. When the model decides the goal is achieved, it calls finish_goal with a summary
5. 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