monotonic-pi-extensions/README.md

monotonic-pi-extensions

Experimental monorepo for Pi coding agent extensions.

Extensions

pi-turn-limit

Limits the number of turns (agent round-trips) in a Pi session. When the limit is reached, the user is prompted to continue or abort. Use when you want to be in-the-loop, or when a model misbehaves and does too many tool calls. It is a good way to control the Time To Next Interaction.

• Default limit: 25 turns
• Override: set PI_MAX_TURNS environment variable to a positive integer
• Unlimited: set PI_MAX_TURNS=unlimited or run the turn-limit unlimited command to disable the boundary check entirely (the counter still increments for observability)
• Re-enable: switch from unlimited back to a number via turn-limit <N>; the counter resets to 0

See packages/pi-turn-limit/README.md for details and the Allium spec.

pi-notifications

Audio alerts via afplay when the agent finishes a turn. Run the agent and step away — you'll hear when input is needed. No multi-tasking required, but it gives you the breathing room to stretch, grab a coffee, or write something down without staring at the screen.

• Config: PI_NOTIFICATION_ENABLED, PI_NOTIFICATION_AGENT_END, PI_NOTIFICATION_AUDIO (defaults to macOS Glass sound)
• Platform: macOS (uses afplay)

See packages/pi-notifications/README.md for details.

pi-llm-performance

Captures and displays LLM inference performance metrics (TTFT, prefill/generation throughput, combined speed) after each prompt. Lets you benchmark shiny new local inference server optimizations at a glance — no need to dig through different server logs.

• Output: TUI notification + status bar (📊 tok/s) + JSONL log at .pi/llm-metrics.log
• Sanity checks: Warns when generation speed exceeds 500 tok/s (physically impossible)

See packages/pi-llm-performance/README.md for details.

Installation

This is an early release — not on npm yet. To install from source:

# Clone the repo
git clone <repo-url>
cd pi-extensions

# Install dependencies
pnpm install

# Link the extension (or reference it directly in your Pi config)

Starting pi in this repository will load the turn-limit extension. Make sure you sandbox it properly, e.g. with 'nono', Docker or a VM. Extensions have not been security checked etc.

Repository Status

Experimental. APIs and behavior may change without notice. Feedback welcome.