One hotkey + one command to switch work modes in the Pi coding agent by cycling model + thinking level together.
- Mode switch is atomic: you never end up in a mismatched “model changed but thinking didn’t” state.
- Defaults that actually work: prefers Pi’s
enabledModelsto avoid recommending unusable models. - Doesn’t get stuck: cycles past unauthorized/unsupported models with a warning.
- No UI clutter: no footer/status artifacts (pairs nicely with
pi-oneliner). - Self-diagnosing:
/cycle doctorproduces a report you can paste into issues.
Quick facts:
- Hotkey: F8 (default) → cycle next profile
- Command:
/cycle→ menu UI (all actions live under/cycle ...) - Provider focus: OpenAI / OpenAI Codex
- Tested with Pi: v0.70+
If this helps your daily Pi loop, star the repo → it directly drives maintenance time.
This repo includes a demo.tape for VHS, but the README GIF is rendered as a still-montage (more reliable than a single take).
To re-render demo.gif locally (WSL recommended):
git clone https://github.com/jerryfan/pi-cycle
cd pi-cycle
bash tools/vhs/render-demo.shInstall with Pi, not npm:
pi install npm:pi-cycleThen in Pi:
/reload
Project-local install (shared via .pi/settings.json):
pi install npm:pi-cycle -l- Open the menu:
/cycle - Cycle next: press
F8(or/cycle next) - Pick a specific profile:
/cycle pick - Configure profiles/hotkey:
/cycle config - Self-check:
/cycle doctor
| Order | Profile | Model | Thinking | Good for |
|---|---|---|---|---|
| 1 | deep |
openai-codex/gpt-5.5 |
xhigh |
Specs, architecture, hard debugging, high-stakes review |
| 2 | code |
openai-codex/gpt-5.5 |
high |
Implementation, debugging, refactors, code review |
| 3 | general |
openai-codex/gpt-5.5 |
medium |
Best default: strong reasoning quality with good cost and token balance |
| 4 | fast |
openai-codex/gpt-5.5 |
low |
Quick iterations, small edits, routine questions |
| 5 | value |
openai-codex/gpt-5.5 |
low |
Cheap-reasoning default; preferred over older GPT-5.x and mini variants |
Tip: gpt-5.2 and gpt-5.3-codex remain useful as legacy/fallback or quota-code profiles, but the default cycle now centers on GPT-5.5. Avoid using gpt-5.4-mini as the value preset because its output-token efficiency is poor for that job.
/cycle(menu)/cycle next/cycle pick(UI required)/cycle config(UI required)/cycle doctor/cycle help/cycle <name>(direct set)
Config file:
~/.pi/agent/pi-cycle.json
Migration note:
pi-cyclewill also read legacy config at~/.pi/agent/py-cycle.jsonif present.- Any save action writes to
pi-cycle.json.
No-UI behavior:
- If Pi is running without interactive UI,
/cyclefalls back to cyclingnext. /cycle pickand/cycle configrequire interactive UI.
pi-cycle can optionally cap thinking when the current session context window is nearly full.
This helps avoid surprises near the limit.
Configure via:
/cycle config→low-context
Note: this uses context window usage, not provider billing quota.
-
Installed but
/cycleis unknown- run
/reload(or restart Pi)
- run
-
Model activation errors (e.g. “model not supported with this account”)
- remove that model from the cycle via
/cycle config - run
/cycle doctorto see which profile is failing
- remove that model from the cycle via
-
Hotkey doesn’t fire
- some terminals don’t transmit certain key combos reliably
- change it via
/cycle config→hotkey(reload required)
Local dev install:
pi install -l <path-to-pi-cycle>Then in Pi:
/reload
/cycle
MIT