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:

📄 turn-limit.allium

Contributing

This is an experimental extension. To contribute:

1. Fork the repository
2. Make your changes
3. Contact Willem through qwan.co.uk to discuss your contribution

License

MIT