@parke.dev/pi-gauntlet

A goal / gauntlet loop for the pi coding agent. Set a goal plus a gauntlet — named shell checks that must all exit 0 (tests, typecheck, lint, anything). After each agent run settles, the extension runs the gauntlet; failures are injected back into the conversation and the agent keeps iterating until the whole gauntlet passes, max iterations are hit, or you stop it.

While the loop is active a widget shows the goal, the iteration count, and a ✓ / ✗ / · state per check.

Install

pi install npm:@parke.dev/pi-gauntlet

Usage

Slash commands:

/gauntlet add tests npm test
/gauntlet add types npx tsc --noEmit
/gauntlet                      # list checks with last status
/gauntlet rm types

/goal make the refactor land cleanly   # set goal, start the loop
/goal status                           # goal, iteration, per-check state
/goal stop                             # stop the loop

The same surface is available to the model through the gauntlet tool, so "keep going until the tests pass" works in prose:

| Action | Fields | Effect | | -------------- | ----------------- | ----------------------------------------------------- | | add_check | name, command | Add or replace a named check | | remove_check | name | Remove a check | | start | goal | Set the goal and start the loop | | stop | — | Stop the loop | | status | — | Goal, iteration, per-check state | | run | — | Run all checks once, return results, without the loop |

Checks run via bash -lc in the project cwd, sequentially, each with its own timeout. State (goal, checks, iteration, last results) is stored in session entries, so resuming or branching a session carries the loop with it.

Project seed

A trusted project can seed initial checks with .pi/gauntlet.json:

{
  "checks": {
    "tests": "npm test",
    "types": "npx tsc --noEmit"
  }
}

The seed only applies when the session has no gauntlet state of its own, and only when ctx.isProjectTrusted() is true. Session state always wins.

Configuration

Defaults ← ~/.pi/gauntlet.json ← environment.

| Field | Default | Env | Notes | | ---------------- | -------- | ------------------------------ | ---------------------------------- | | maxIterations | 10 | PI_GAUNTLET_MAX_ITERATIONS | Failures injected before giving up | | checkTimeoutMs | 300000 | PI_GAUNTLET_CHECK_TIMEOUT_MS | Per-check timeout |

Security note

This extension runs arbitrary shell commands automatically, without asking, on every settled agent run while the loop is active. That is the point of a gauntlet — but it means check commands should be treated like postinstall scripts. Project seeds (.pi/gauntlet.json) are therefore only loaded in trusted projects, and a malicious or careless check (e.g. one that hangs, or mutates state) will run unattended up to maxIterations times. Keep checks read-only-ish: build, test, lint, verify.

Design decisions

• Exit-0 shell checks, nothing fancier. Every project already expresses "is this good?" as commands — tests, typecheck, lint, a curl against a dev server. Reusing that means no new DSL, no per-project plugin, and the same command the user runs by hand is the command the loop runs.
• followUp injection. Failure reports are sent with deliverAs: "followUp" + triggerTurn, so a report never interrupts a turn mid-tool-call: it lands exactly when the agent has no more work queued, and immediately starts the next iteration. The report itself is the goal reminder plus each failing check's name, exit code, and a ~2KB output tail — enough to act on, small enough to keep context healthy.
• Session-scoped checks. Checks live in session entries, not on disk, so branching or resuming a session carries the loop with it and nothing leaks between projects. The optional .pi/gauntlet.json seed exists for projects that want a standing gauntlet, gated behind project trust.
• The loop pauses on abort. If a check run is aborted (Esc), the loop does not immediately re-trigger. /goal stop is the explicit escape hatch.

License

MIT