2.8 KiB
pi-turn-limit
Pi coding agent extension to limit the number of turns taken by a model in a session.
Why
Pi agents can run indefinitely, consuming tokens and time, and taking focus. This extension gives you a circuit breaker: when the agent reaches a configurable turn limit, you decide whether to continue or abort.
This is useful for:
- Interaction — Shorter Time To Next Interaction (TTNI) keeps you in the loop. Focus, clarity, single-tasking mode.
- Cost control — prevent runaway sessions from burning through API credits
- Quality control — if an agent needs more turns than expected, something may be wrong with the prompt or task
How it works
The extension tracks turns (agent round-trips) per session. Each new user prompt resets the counter.
| Event | Behavior |
|---|---|
agent_start |
Counter resets to 0 |
turn_start |
Counter increments; widget updates |
| Counter reaches limit | User prompted: continue (counter resets) or abort |
| No UI available | Silent abort at limit |
When the limit is reached and the user confirms continuation, the counter resets to 0, allowing another round of turns. This repeats — there's no maximum number of continuations.
Configuration
Environment variable
Set PI_MAX_TURNS before starting pi:
# 50 turns
PI_MAX_TURNS=50 pi
# Unlimited — no boundary check fires
PI_MAX_TURNS=unlimited pi
# Default (25 turns)
pi
Runtime command
Adjust the limit during a session with the turn-limit command:
/turn-limit 50 # Set to 50 turns
/turn-limit unlimited # Disable the limit
/turn-limit 25 # Re-enable with 25 turns (counter resets from 0)
Unlimited mode
Setting the limit to unlimited disables the boundary check entirely. The turn counter still increments and the widget still displays ∞, so you retain observability without enforcement.
Switching from unlimited back to a number triggers the LimitReEnabled rule: the counter resets to 0 so the new limit applies from a clean starting point.
Widget
When a UI is available, the extension displays a widget showing Turns: N/M (or Turns: N/∞ in unlimited mode).
Spec
This extension was developed using Allium, a formal language for specifying software behavior. The Allium spec captures the turn counting, limit enforcement, unlimited mode, and re-enable rules:
Contributing
This is an experimental extension. To contribute:
- Fork the repository
- Make your changes
- Contact Willem through qwan.co.uk to discuss your contribution
License
MIT