pi-goal

Goal-directed autonomous work loops for pi.

Set a goal as a single completion condition. After every turn, a lightweight evaluator checks whether the condition is met. If it isn't, the agent is automatically prompted to keep working — turn after turn — until the goal is satisfied or you stop it. It's the autonomous counterpart to a plain prompt: you describe the end state, not each step.

/goal all tests in test/auth pass and the lint step is clean

---

Features

• Single-condition goals — describe a verifiable end state; the agent drives toward it.
• Self-evaluating loop — after each turn the configured model judges progress with a cheap yes/no call.
• Live status — a footer timer shows elapsed time and turn count while a goal runs.
• Resumes across sessions — an in-progress goal is restored automatically when you reopen the session.
• Bounded — a hard turn cap prevents a goal that never resolves from looping forever.

Requirements

• pi (@earendil-works/pi-coding-agent).
• A configured model — the same model that powers your session is reused for evaluation.

Installation

From npm:

pi install npm:@koltmcbride/pi-goal

From git:

pi install git:github.com/kolt-mcb/pi-goal@v0.1.1

⚠️ Pi packages run with full system access. Review the source before installing.

Usage

/goal <condition>    Set a goal and start working immediately
/goal                Show the active goal's status
/goal status         Alias for /goal
/goal clear          Clear the active goal

clear also accepts the aliases stop, off, reset, none, and cancel. The subcommands are offered as autocompletions when you type /goal and press Tab.

Re-issuing /goal <condition> while a goal is active replaces the condition and restarts the loop with it.

Writing effective conditions

A good condition has one measurable end state and a clear way for the agent to demonstrate it in its output:

/goal all tests in test/auth pass and the lint step is clean
/goal refactor src/database to use connection pooling, verified by tests in test/db.test.ts
/goal every exported symbol in src/api has a docstring

Goals work best for substantial, verifiable work — migrating a module until every call site compiles, implementing a design doc until its acceptance criteria hold, or working through a backlog until the queue is empty.

Status display

While a goal is active, the footer shows a live timer:

⏱ 3t · 2m 15s

/goal (or /goal status) prints the full state:

Condition: all tests in test/auth pass and the lint step is clean
Running:   2m 15s
Turns:     3
Last reason: one failing test remains in test/auth/login.test.ts

On completion the footer reports ✓ Goal achieved in 3 turns.

How it works

1. Set — /goal <condition> records the condition and sends it as the first prompt, kicking off work immediately.
2. Evaluate — at the end of each turn, the agent's text and tool results are summarized and passed to a minimal evaluator call on the same configured model: has the condition been met?
3. Continue or stop — if not met, a hidden continuation message is queued as the next turn with the latest evaluation reason, and the agent keeps working. When the evaluator returns yes, the loop stops and the result is reported.

A goal stops automatically when the condition is met, when you run /goal clear, or after a safety cap of 120 turns without success. State is persisted as custom session entries, so a goal that was still running when a session ended is restored on resume.

Relationship to Claude Code's /goal

pi-goal mirrors the /goal interface from Claude Code, with a few differences:

	Claude Code	pi-goal
Slash interface	✓	✓
Session persistence	✓	✓
Footer timer	✓	✓
Evaluation model	separate small model	your configured model (minimal reasoning)

Development

npm install        # install dev + peer dependencies
npm run typecheck  # tsc --noEmit
npm test           # run the smoke test

The extension is plain TypeScript; pi loads the source directly via the pi manifest in package.json, so there is no build step.

License

MIT © Kolt McBride