Luigit
repositories / pi-ext

pi-ext

bugabingas pi extensions

owned by admin

extensions/loop/README.md

Raw
Rendered preview
loop

loop

Keep an agent working toward a goal until commands you trust say it is done.

Use in Pi

Run /loop guide and let the agent interview you. It proposes a goal and gates from the project's instructions and task runner, then starts the run with its loop_begin tool once you agree. loop_begin works only after /loop guide; the agent cannot start a loop on its own.

To set everything yourself, run /loop start while the agent is idle. Pi asks for the goal, then for the gates as a JSON array:

[
  { "name": "types", "command": "npx", "args": ["tsc", "--noEmit"] },
  { "name": "tests", "command": "npm", "args": ["test"] }
]

A gate is a raw executable with optional args, env, and cwd; no shell is involved. On Windows, wrap .cmd shims explicitly, for example { "command": "cmd", "args": ["/c", "npm", "test"] }. One attempt runs the gates in order and stops at the first failure. The run succeeds only when every gate exits 0 in one attempt; what the agent says never counts. After each failed attempt Pi prompts the agent again with the goal, the failing gate, and the tail of its output. Older loop prompts shrink to one line, so gate output does not pile up in context.

Optional budgets follow start or guide as minutes turns attempts, with none for uncapped, for example /loop start 60 30 10.

Command Effect
/loop guide [minutes turns attempts] Brainstorm goal and gates with the agent, which then starts the run.
/loop start [minutes turns attempts] Ask for goal and gates, run the baseline attempt, then loop.
/loop pause / /loop stop [id|latest] Pause or stop; typing stop or pause also pauses.
/loop resume <id|latest> Re-arm a paused run; used turns and attempts still count, the time budget restarts.
/loop status / /loop list Show the current run or the run history.
/loop view Open the live run page in the browser.
/loop vixen [on|off] Show animation or status only; no argument toggles.

Escape, an aborted turn, an exhausted budget, or leaving the session pauses the run. Nothing resumes on its own. Returning to the same Pi session restores its interrupted or paused run immediately, with its id, last activity, interrupted gate when known, and explicit Resume, Stop, and Inspect commands. Other sessions can inspect history but do not attach to a run automatically. Explicit resume reruns the gates; exhausted turn or attempt budgets require a new run. The baseline runs in the background, so /loop status, /loop view, and /loop pause remain available while gates execute.

The agent is told to work things out on its own first. When it is truly blocked on you, for example on access or a decision outside the goal, it pauses the run with its loop_control tool and says what it needs. While paused you talk with the agent as usual; those turns do not count against the budget. Once you have unblocked it, the agent resumes the run with the same tool, or you run /loop resume or /loop stop.

Companion

In the terminal UI, a compact widget above the editor shows gate progress, attempts, and turns in at most three rows, with animation on or off. There is no separate loop footer status. An animated red-haired pin-up in a pastel orange bikini appears in a bottom-right corner overlay without taking keyboard focus from the editor or your open dialog. The portrait reserves no inline transcript or editor rows; its rectangle can obscure transcript text underneath it. Empty outer raster margins are trimmed; the character is enlarged 1.5× on both axes while preserving zoom and camera movement. The portrait uses up to 48 columns by 23 rows, with a one-column right margin and nine rows of bottom clearance for progress, editor, and footer. Terminals smaller than 60 columns or 32 rows hide the portrait instead of downscaling it. Gate output and cancellation guidance remain in the inline widget during checks. She holds slow, calm poses while the camera glides between close-ups of her face, bust and hips. She reacts to the loop: she waits with a hand at her collarbone while gates run, looks unimpressed after a failed attempt, lounges while paused, and stretches slowly with her arms over her head, then blows kisses, when every gate passes. She leaves when the run stops, and about 40 seconds after it succeeds; status remains. /loop vixen off removes the animation and its refresh timer, keeping progress and counters; /loop vixen on starts animation again, rather than freezing a frame. The toggle lasts for the current extension runtime, not across reloads or restarts. The native overlay is rectangular, not alpha-transparent: remaining empty cells use the terminal background and obscure Pi text, even if that background is transparent. In fullscreen mode, Pi also intercepts mouse events within the portrait rectangle; use /loop vixen off when you need text or mouse access beneath it. Stopping, leaving the session, or reloading removes the portrait and its animation timer without dismissing other overlays.

Set PI_LOOP_ANIM before starting Pi to use an original copper-and-cream tabby kitten instead of the vixen. Presence alone selects the kitten, including empty, 0, false, or arbitrary values; remove the variable to restore the default vixen. The kitten watches gates with a moving paw, bats loop-shaped yarn while working, puzzles over failures, curls up while paused, and celebrates success. /loop vixen off and /loop vixen on control either animation without changing progress or counters. Selection resolves once per session through env, trusted project settings, user settings, then default; untrusted project settings are ignored. Settings files accept boolean loop.anim; invalid values warn and select the safe-for-work kitten rather than falling back to the vixen.

Run page

/loop view serves a page on 127.0.0.1 behind a random token and opens it in the browser. It shows the run with its budgets, each running gate's elapsed time and bounded live output, completed failures, a timeline of turns and attempts, the event feed, and the run history. It updates live and follows the system light or dark theme. The page only observes; its resume button copies the /loop resume command for you to run in Pi.

State

Runs, gate attempts, and events live in .pi/loop/state.db inside the project, or wherever loop.statePath points. Gate output is stored there, so add the file to .gitignore unless your team wants the history in version control. /loop guide mentions this when Git does not ignore the file.

A run owned by a live process cannot be resumed or stopped from another controller. Dead local owners can be recovered; remote or unverifiable owners and reused live process ids remain blocked conservatively. Resume also refuses a recorded gate process that may still be alive after its controller crashed. Inspect and stop that process before resuming; process groups are checked on POSIX, while Windows can only probe the recorded gate process, not surviving detached grandchildren. Use separate state files on separate machines; local ownership checks assume the same host and process namespace.

Legacy runs have no reliable ownership identity. First stop every old Pi instance that could access the database, then run /loop recover <id> and confirm offline recovery. This restores the run paused without executing gates, preserving its goal, gates, budgets, counters, and completed results. Only then use /loop resume <id> to execute again. The offline prerequisite cannot be verified automatically; never confirm while an old instance might still be running.

Installation

Reference

Commands

Command Purpose
/loop Goal-gated agent loop: start|guide|resume|pause|stop|status|view|list|recover|vixen

Setting names

Setting Environment
loop.anim PI_LOOP_ANIM
loop.statePath PI_LOOP_STATE_PATH

Setting values

Setting Default Valid values Purpose
loop.anim false Parser-validated Kitten animation: Use the safe-for-work kitten instead of the vixen. Any present PI_LOOP_ANIM value, including empty, 0, or false, enables it; settings files accept booleans only. Invalid configuration warns and selects the kitten.
loop.statePath ".pi/loop/state.db" Parser-validated State database: SQLite file holding runs, gate attempts, and events; relative paths resolve against the project directory.
<img src="assets/banner.svg" alt="loop" height="70">

# loop

Keep an agent working toward a goal until commands you trust say it is done.

## Use in Pi

Run `/loop guide` and let the agent interview you.
It proposes a goal and gates from the project's instructions and task runner, then starts the run with its `loop_begin` tool once you agree.
`loop_begin` works only after `/loop guide`; the agent cannot start a loop on its own.

To set everything yourself, run `/loop start` while the agent is idle.
Pi asks for the goal, then for the gates as a JSON array:

```json
[
  { "name": "types", "command": "npx", "args": ["tsc", "--noEmit"] },
  { "name": "tests", "command": "npm", "args": ["test"] }
]
```

A gate is a raw executable with optional `args`, `env`, and `cwd`; no shell is involved.
On Windows, wrap `.cmd` shims explicitly, for example `{ "command": "cmd", "args": ["/c", "npm", "test"] }`.
One attempt runs the gates in order and stops at the first failure.
The run succeeds only when every gate exits 0 in one attempt; what the agent says never counts.
After each failed attempt Pi prompts the agent again with the goal, the failing gate, and the tail of its output.
Older loop prompts shrink to one line, so gate output does not pile up in context.

Optional budgets follow `start` or `guide` as `minutes turns attempts`, with `none` for uncapped, for example `/loop start 60 30 10`.

| Command | Effect |
| --- | --- |
| `/loop guide [minutes turns attempts]` | Brainstorm goal and gates with the agent, which then starts the run. |
| `/loop start [minutes turns attempts]` | Ask for goal and gates, run the baseline attempt, then loop. |
| `/loop pause` / `/loop stop [id\|latest]` | Pause or stop; typing `stop` or `pause` also pauses. |
| `/loop resume <id\|latest>` | Re-arm a paused run; used turns and attempts still count, the time budget restarts. |
| `/loop status` / `/loop list` | Show the current run or the run history. |
| `/loop view` | Open the live run page in the browser. |
| `/loop vixen [on\|off]` | Show animation or status only; no argument toggles. |

Escape, an aborted turn, an exhausted budget, or leaving the session pauses the run.
Nothing resumes on its own.
Returning to the same Pi session restores its interrupted or paused run immediately, with its id, last activity, interrupted gate when known, and explicit Resume, Stop, and Inspect commands.
Other sessions can inspect history but do not attach to a run automatically.
Explicit resume reruns the gates; exhausted turn or attempt budgets require a new run.
The baseline runs in the background, so `/loop status`, `/loop view`, and `/loop pause` remain available while gates execute.

The agent is told to work things out on its own first.
When it is truly blocked on you, for example on access or a decision outside the goal, it pauses the run with its `loop_control` tool and says what it needs.
While paused you talk with the agent as usual; those turns do not count against the budget.
Once you have unblocked it, the agent resumes the run with the same tool, or you run `/loop resume` or `/loop stop`.

## Companion

In the terminal UI, a compact widget above the editor shows gate progress, attempts, and turns in at most three rows, with animation on or off.
There is no separate loop footer status.
An animated red-haired pin-up in a pastel orange bikini appears in a bottom-right corner overlay without taking keyboard focus from the editor or your open dialog.
The portrait reserves no inline transcript or editor rows; its rectangle can obscure transcript text underneath it.
Empty outer raster margins are trimmed; the character is enlarged 1.5× on both axes while preserving zoom and camera movement.
The portrait uses up to 48 columns by 23 rows, with a one-column right margin and nine rows of bottom clearance for progress, editor, and footer.
Terminals smaller than 60 columns or 32 rows hide the portrait instead of downscaling it.
Gate output and cancellation guidance remain in the inline widget during checks.
She holds slow, calm poses while the camera glides between close-ups of her face, bust and hips.
She reacts to the loop: she waits with a hand at her collarbone while gates run, looks unimpressed after a failed attempt, lounges while paused, and stretches slowly with her arms over her head, then blows kisses, when every gate passes.
She leaves when the run stops, and about 40 seconds after it succeeds; status remains.
`/loop vixen off` removes the animation and its refresh timer, keeping progress and counters; `/loop vixen on` starts animation again, rather than freezing a frame.
The toggle lasts for the current extension runtime, not across reloads or restarts.
The native overlay is rectangular, not alpha-transparent: remaining empty cells use the terminal background and obscure Pi text, even if that background is transparent.
In fullscreen mode, Pi also intercepts mouse events within the portrait rectangle; use `/loop vixen off` when you need text or mouse access beneath it.
Stopping, leaving the session, or reloading removes the portrait and its animation timer without dismissing other overlays.

Set `PI_LOOP_ANIM` before starting Pi to use an original copper-and-cream tabby kitten instead of the vixen.
Presence alone selects the kitten, including empty, `0`, `false`, or arbitrary values; remove the variable to restore the default vixen.
The kitten watches gates with a moving paw, bats loop-shaped yarn while working, puzzles over failures, curls up while paused, and celebrates success.
`/loop vixen off` and `/loop vixen on` control either animation without changing progress or counters.
Selection resolves once per session through env, trusted project settings, user settings, then default; untrusted project settings are ignored.
Settings files accept boolean `loop.anim`; invalid values warn and select the safe-for-work kitten rather than falling back to the vixen.

## Run page

`/loop view` serves a page on `127.0.0.1` behind a random token and opens it in the browser.
It shows the run with its budgets, each running gate's elapsed time and bounded live output, completed failures, a timeline of turns and attempts, the event feed, and the run history.
It updates live and follows the system light or dark theme.
The page only observes; its resume button copies the `/loop resume` command for you to run in Pi.

## State

Runs, gate attempts, and events live in `.pi/loop/state.db` inside the project, or wherever `loop.statePath` points.
Gate output is stored there, so add the file to `.gitignore` unless your team wants the history in version control.
`/loop guide` mentions this when Git does not ignore the file.

A run owned by a live process cannot be resumed or stopped from another controller.
Dead local owners can be recovered; remote or unverifiable owners and reused live process ids remain blocked conservatively.
Resume also refuses a recorded gate process that may still be alive after its controller crashed.
Inspect and stop that process before resuming; process groups are checked on POSIX, while Windows can only probe the recorded gate process, not surviving detached grandchildren.
Use separate state files on separate machines; local ownership checks assume the same host and process namespace.

Legacy runs have no reliable ownership identity.
First stop every old Pi instance that could access the database, then run `/loop recover <id>` and confirm offline recovery.
This restores the run paused without executing gates, preserving its goal, gates, budgets, counters, and completed results.
Only then use `/loop resume <id>` to execute again.
The offline prerequisite cannot be verified automatically; never confirm while an old instance might still be running.

[Installation](../../README.md#install)

## Reference

<!-- config:start -->
### Commands

| Command | Purpose |
| --- | --- |
| `/loop` | Goal-gated agent loop: start\|guide\|resume\|pause\|stop\|status\|view\|list\|recover\|vixen |

### Setting names

| Setting | Environment |
| --- | --- |
| `loop.anim` | `PI_LOOP_ANIM` |
| `loop.statePath` | `PI_LOOP_STATE_PATH` |

#### Setting values

| Setting | Default | Valid values | Purpose |
| --- | --- | --- | --- |
| `loop.anim` | `false` | Parser-validated | Kitten animation: Use the safe-for-work kitten instead of the vixen. Any present PI_LOOP_ANIM value, including empty, 0, or false, enables it; settings files accept booleans only. Invalid configuration warns and selects the kitten. |
| `loop.statePath` | `".pi/loop/state.db"` | Parser-validated | State database: SQLite file holding runs, gate attempts, and events; relative paths resolve against the project directory. |
<!-- config:end -->