# 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:

```bash
# 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](https://juxt.github.io/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](./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](https://qwan.co.uk) to discuss your contribution

## License

MIT