pi-cycle

One hotkey + one command to switch work modes in the Pi coding agent by cycling model + thinking level together.

Why this is worth starring

• 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 enabledModels to 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 doctor produces 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.

---

Demo (VHS)

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.sh

---

Install

Install with Pi, not npm:

pi install npm:pi-cycle

Then in Pi:

/reload

Project-local install (shared via .pi/settings.json):

pi install npm:pi-cycle -l

---

Quickstart

• 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

---

Default OpenAI profile cycle

Order	Profile	Model	Thinking	Good for
1	deep	openai-codex/gpt-5.5	xhigh	Specs, architecture, high-stakes review
2	code	openai-codex/gpt-5.3-codex	high	Implementation, debugging, refactors
3	general	openai-codex/gpt-5.4	medium	Everyday questions + balanced deep work
4	fast	openai-codex/gpt-5.4-mini	low	Quick iterations and small edits
5	value	openai-codex/gpt-5.2	medium	Throughput / value mode

Tip: gpt-5.3-codex-spark is usually best as a dedicated spark profile (fast coding-oriented, no images, smaller context) rather than your general daily mode.

---

Commands

• /cycle (menu)
• /cycle next
• /cycle pick (UI required)
• /cycle config (UI required)
• /cycle doctor
• /cycle help
• /cycle <name> (direct set)

---

Config

Config file:

• ~/.pi/agent/pi-cycle.json

Migration note:

• pi-cycle will also read legacy config at ~/.pi/agent/py-cycle.json if present.
• Any save action writes to pi-cycle.json.

No-UI behavior:

• If Pi is running without interactive UI, /cycle falls back to cycling next.
• /cycle pick and /cycle config require interactive UI.

Adaptive thinking cap (optional)

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.

---

Troubleshooting

• Installed but /cycle is unknown

  • run /reload (or restart Pi)

• Model activation errors (e.g. “model not supported with this account”)

  • remove that model from the cycle via /cycle config
  • run /cycle doctor to see which profile is failing

• Hotkey doesn’t fire

  • some terminals don’t transmit certain key combos reliably
  • change it via /cycle config → hotkey (reload required)

---

Development

Local dev install:

pi install -l <path-to-pi-cycle>

Then in Pi:

/reload
/cycle

---

License

MIT