---
slug: "xbear-pi-goal"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/xbeark/pi-goal@main/README.md"
repo: "https://github.com/xbeark/pi-goal"
source_file: "README.md"
branch: "main"
---
# 🎯 pi-goal — Goal Mode for the Pi Coding Agent

[![npm](https://img.shields.io/npm/v/@xbear/pi-goal)](https://www.npmjs.com/package/@xbear/pi-goal) [![Pi extension](https://img.shields.io/badge/Pi-extension-blue)](https://pi.dev) [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](./LICENSE)

`@xbear/pi-goal` is a native [Pi coding agent](https://pi.dev) extension that adds session-scoped `/goal` commands and a `goal_complete({ goal_id, summary })` tool for autonomous, verifiable task completion.

> This is a fork of [`@narumitw/pi-goal`](https://github.com/narumiruna/pi-extensions) that adds **print-mode (non-interactive `pi -p`) support** — `/goal` now works both interactively (tui) and from the command line (`pi -p "/goal ..."`). See [Print mode](#-print-mode-non-interactive--pi--p) below.

Goal mode uses Codex-like persistence instructions and keeps sending guarded continuation messages until the agent calls `goal_complete`, the user pauses or clears the goal, an interrupt/error pauses the goal, or an optional token budget is reached.

## ✨ Features

- Adds `/goal <goal_to_complete>` to start goal mode, with confirmation before replacing an existing goal.
- Works in both interactive (tui) and non-interactive print/json mode — drive a goal to completion from the CLI with `pi -p "/goal ..."`.
- Bare `/goal` shows the current goal summary.
- Keeps advanced goal management inside `/goal` subcommands: `pause`, `resume`, `clear`, and `edit`.
- Exposes only one top-level command: `/goal`.
- Supports optional token budgets such as `/goal --tokens 100k <goal>`.
- Tracks `active`, `paused`, `budget_limited`, and `complete` states.
- Stores goal state in the current Pi session, following Codex's thread-owned goal model instead of using a global per-directory goal.
- Registers a `goal_complete({ goal_id, summary })` tool for explicit completion, requiring the current goal id and rejecting missing/stale ids plus plainly contradictory summaries such as “not complete” or “tests still fail”.
- Automatically prompts the agent to continue if an active turn ends early, directly triggering the next turn when Pi is idle and no pending messages are queued.
- Pauses and aborts queued goal work when the user pauses a goal or Pi reports a non-retryable aborted/errored assistant turn.
- Keeps retryable provider interruptions and Pi compaction retries active without enqueueing duplicate goal continuations while Pi retries.
- Preserves active goals across manual, threshold, and overflow compaction.
- Guards auto-follow-ups so duplicate, replaced, paused, cleared, completed, or budget-limited goals are not continued.
- Rotates the completion guard id when a goal is resumed or edited so delayed old turns cannot complete the newer goal instance.
- Blocks stale tool calls after pause or non-retryable interruption.
- Encourages requirement-by-requirement verification before the goal is marked complete.

## 📦 Install

```bash
pi install npm:@xbear/pi-goal
```

Try without installing permanently:

```bash
pi -e npm:@xbear/pi-goal
```

Install from git (no npm account needed):

```bash
pi install git:github.com/xbeark/pi-goal
# or
pi install https://github.com/xbeark/pi-goal
```

Try locally without installing permanently (from a clone of this repo):

```bash
pi -e .
```

## 🚀 Commands

```text
/goal
/goal implement snake game
/goal --tokens 100k fix the failing test and verify it
/goal edit ship the smaller fix first
/goal pause
/goal resume
/goal clear
```

- `/goal` shows the current goal, status, iteration count, elapsed time, token usage, and available `/goal` subcommands.
- `/goal <goal_to_complete>` starts goal mode. If another unfinished goal exists, Pi asks for confirmation before replacing it with a new active goal and resetting its usage counters.
- `/goal --tokens 100k <goal_to_complete>` starts or replaces goal mode with a token budget. `k` and `m` suffixes are accepted, for example `100k` or `1.5m`.
- `/goal edit <goal_to_complete>` updates the existing goal objective without resetting usage counters. Active goals stay active, paused goals stay paused, and budget-limited goals remain budget-limited if their budget is still exhausted.
- `/goal pause` stops prompt injection and auto-continuation, aborts the current turn, and keeps the goal for later resume.
- `/goal resume` resumes a paused or budget-limited goal when the token budget allows it, then queues a resume prompt so work continues.
- `/goal clear` clears the current goal state, status, pending continuation, and legacy persisted state for the current working directory without aborting any in-flight agent turn.

Goal objectives are limited to 4,000 characters. Put longer instructions in a file and reference the file path from `/goal`.

## 🖨️ Print mode (non-interactive / `pi -p`)

`/goal` also works in Pi's non-interactive print/json mode, so you can drive a goal to completion from the command line and exit:

```bash
pi -p "/goal implement snake game" --provider <provider> --model <model> -a
```

In print/json mode the `/goal` command blocks until the goal settles (`complete`, `paused`, `budget_limited`, or cleared), keeping the process alive through the whole continuation loop. In interactive (tui) mode the behavior is unchanged: `/goal` returns immediately and the goal runs in the background while you keep typing.

> Why this is needed: Pi's extension-facing `pi.sendUserMessage` is fire-and-forget, so the `/goal` command handler would otherwise return before the agent runs. In tui mode the session persists and the loop runs in the background; in print mode (`pi -p`) the process would exit and dispose the runtime the moment the handler returns, killing the just-started agent. The command therefore awaits a goal-settled signal in non-interactive mode only.

## 🔁 Session and reload behavior

Goal state is stored as Pi session state, similar to Codex's thread-owned goals. `/reload` and reopening the same Pi session can restore that session's unfinished goal. Starting a new Pi session in the same working directory does not inherit the old goal.

Older versions wrote unfinished goals to `~/.pi/agent/pi-goal-state.json` keyed by working directory. This version no longer reads that global file, and `/goal clear` removes any legacy entry for the current working directory.

## 📊 Statusline states

`pi-goal` writes compact plain status strings for statusline extensions. `@narumitw/pi-statusline` adds the default `🎯` icon unless configured otherwise:

- `active 3m` — an active goal without a token budget.
- `active 18k/100k` — an active goal with token usage and budget.
- `paused` — auto-continuation is paused.
- `budget 100k/100k` — the token budget was reached; auto-continuation stops.
- `complete` — shown briefly after `goal_complete` succeeds.

## ✅ How completion works

While a goal is active, `pi-goal` injects persistence rules, a `<goal_id>` stale-turn guard, and exposes `goal_complete`. To finish, the agent must call `goal_complete` with the exact current `goal_id` and a `summary` of completion evidence. Missing or stale `goal_id` values are rejected before summary validation, and paused goals cannot be completed until resumed. Empty or plainly contradictory summaries are also rejected; the summary is completion evidence, not the stale-turn safety token.

If a turn ends before completion, `pi-goal` records usage and sends one guarded continuation only when no other messages are pending.

## 🛑 Interruption and queued-input behavior

On user pause, abort, or non-retryable error, `pi-goal` pauses the goal, aborts stale work, and blocks stale tool calls until the next user prompt (non-extension input), `/goal resume`, or `/goal clear`. On `/goal clear`, it clears goal state, pending continuation markers, and any stale tool-call block; it does not abort the current turn. Retryable provider interruptions and overflow compaction retries stay active while Pi retries; no extra continuation is queued.

## 🧠 Use cases

- Finish implementation tasks without stopping at a plan.
- Keep debugging until the bug is verified fixed.
- Run refactors that require multiple tool cycles.
- Encourage agents to test, lint, or typecheck before completion.
- Make long-running Pi coding sessions more autonomous.

## 🗂️ Package layout

```txt
pi-goal/
├── src/
│   └── goal.ts
├── test/
│   └── goal.test.ts
├── README.md
├── LICENSE
├── tsconfig.json
└── package.json
```

The package exposes its Pi extension through `package.json`:

```json
{
  "pi": {
    "extensions": ["./src/goal.ts"]
  }
}
```

## 🔎 Keywords

Pi extension, Pi coding agent, goal mode, autonomous coding agent, AI agent workflow, task completion, agent loop, verification, TypeScript Pi package.

## 📄 License

MIT. See [`LICENSE`](https://github.com/xbeark/pi-goal/tree/HEAD/LICENSE).