pi-modekit

Plan & build modes for Pi — one key to switch, and the restrictions actually hold. Adding a mode of your own takes one command.

Mode	Tools	What it gives you
plan	every read-only tool: read, grep, find, ls + save_plan, web_fetch, web_search, npm_info, git_inspect	Safe research and design before any edit
build	read, bash, edit, write, grep, find, ls + save_plan, web_fetch	Full implementation power

---

Why you'll like it

🖱️ One-key switching — press Tab to toggle plan ↔ build. No typing, no menus.

🛡️ Plan mode that actually holds — the moment you switch to plan, edit, write, bash and powershell are gone from the tool set. A restricted mode also cannot delegate to an unrestricted subagent, and cannot read your secrets. These guards are enforced mechanically — not by asking the model to be nice.

📋 Plan mode that ships, not just talks — plan stays productive:

• save_plan — write the plan to .pi/plans/ so build can execute it.
• web_fetch — research external docs with read-only GET requests, limited to your own domain allowlist.
• npm_info — look up npm packages (version, description, homepage).
• git_inspect — read-only git history: log, show --stat, diff --stat, status, blame.
• web_search — find pages and docs (DuckDuckGo by default; Brave with an apiKey).

🧩 Modes grow with you — two modes are a great start, and creating another one is a single command: /mode add <name>.

🧰 Works everywhere — the safety guard reads the live tool set, so it also protects a plain pi --tools read,grep,find,ls run, not only these two modes.

⚖️ MIT licensed, fully independent.

---

Install

pi install npm:pi-modekit

Or from source:

pi install git:github.com/NgThachThanh/pi-modekit
pi install /path/to/pi-modekit   # local checkout

Start new sessions in build by default:

{ "defaultMode": "build" }

in ~/.pi/agent/settings.json (or per project in .pi/settings.json).

Usage

Input	Action
Tab	Cycle modes
Alt+S	Search modes
/mode	Mode selector
/mode <name>	Switch directly
/mode add <name>	Create a new mode (guided)
/mode edit <name>	Edit a mode in place
/mode remove <name>	Delete a mode you created
/modes	List all modes
pi --start-mode plan	Start in a given mode

The active mode, its model and its tools are shown in a banner above the editor.

📖 Full user guide: docs/GUIDE.md · System prompt snapshot: docs/pi-system-prompt.md.

Mode behavior stays consistent

• Mode instructions live at the end of the system prompt — the position models follow best — and a fresh mode marker is re-injected on every turn, so switching modes mid-conversation takes effect immediately and no stale message leaks into the next role.
• The tool set is re-applied on every turn, so tools that connect later (MCP, other extensions) join seamlessly without weakening the mode.

Guard

The guard extension enforces the current mode at call time. When the active mode cannot edit and write:

Rule	You are protected from
R1 · Delegation	A restricted mode handing the task to an unrestricted subagent — the classic escape hatch. Read-only subagents still work.
R2 · Shell & writes	bash/powershell calls, and edits outside plan files, being slipped through.
R3 · Secrets	.env and .env.* files being read by a restricted session.

The guard inspects the live tool set, so it is independent of the mode switcher and protects any tool-restricting mechanism you pair it with.

Add a mode

/mode add review

You are then walked through four quick steps:

1. Where to save — project (.pi/agents/) or user (~/.pi/agent/agents/)
2. Starting tool set — plan-like, build-like, everything, or empty
3. A visual checklist — toggle the real tools available on your machine (the list is read from pi, so you never have to remember tool names)
4. Write the instructions — the body of the mode opens in an editor, prefilled with a sensible template, ready for you to shape

The mode is written as a markdown file, activated immediately, and joins the Tab cycle and /mode selector. Tune it later by editing the file and running /reload.

Remove a mode

Delete a mode you created (the bundled kit modes plan/build are kept):

/mode remove review

Don't remember the name? /mode remove (no argument) opens a list to choose from. Every deletion asks for confirmation first.

Modes by hand

Modes are markdown files with YAML frontmatter:

---
name: review
description: Read-only review with tests allowed
tools: read, grep, find, ls, bash
model: anthropic/claude-sonnet-4-5
---

Body becomes the mode's instructions.

Field	Notes
name	Used by /mode <name>
description	Shown in selector and banner
tools	Whitelist of builtin tools; declare it explicitly for fully predictable tool sets
model	provider/model-id, or inherit the session model

Discovery, lowest precedence first: bundled agents/ → ~/.pi/agent/agents/ → <project>/.pi/agents/. A later source overrides an earlier one by name.

Layout

pi-modekit/
├── agents/              # bundled plan.md, build.md
├── lib/modes.ts        # shared mode discovery
└── extensions/
    ├── modes/           # switching, Tab, /mode add, banner, prompt shaping
    ├── guard/           # R1/R2/R3 enforcement
    └── tools/           # save_plan, web_fetch

License

MIT.