@kmiyh/pi-plan-mode

⚠️ Test mode / experimental release. This extension is currently in active testing. The core workflow is usable, but behavior, UX details, and internal implementation may still change between updates.

@kmiyh/pi-plan-mode adds a stable, Claude Code / Codex / OpenCode-style plan mode to Pi without forcing Pi out of planning after a plan is produced.

The extension is built around a simple idea:

• /plan puts Pi into a restricted planning mode
• Pi can inspect the repo, reason, and maintain a plan file
• Pi stays in plan mode after replying normally
• /build or /plan off returns Pi to regular implementation mode

What this extension does

When plan mode is active, the extension changes Pi in four ways:

1. Restricts the toolset to planning-safe tools
2. Guards bash so only read-only inspection commands are allowed
3. Allows writes only to a session-scoped plan file under .pi/plans/<session-id>.md
4. Shows an inline plan indicator in the footer next to the model / thinking text without replacing the rest of the footer

The goal is to keep planning explicit, safe, and continuously visible.

Current behavior

Entering plan mode

You can enter plan mode in any of these ways:

• /plan
• /plan on
• /plan enter
• /plan <prompt> — enter plan mode and immediately send a planning request
• pi --plan — start Pi directly in plan mode
• Ctrl+Alt+P — shortcut to enter plan mode

When plan mode is enabled:

• Pi switches to a restricted planning toolset
• Pi is instructed to stay in a planning / analysis phase
• the current session gets its own plan file
• the footer shows • plan inline next to the model/thinking text

Staying in plan mode

After Pi returns a plan, the extension does not open an approval dialog and does not auto-switch back to build mode.

Instead:

• the assistant reply finishes normally
• the plan is extracted and remembered
• /todos can show the latest steps
• Pi remains in plan mode until you explicitly leave it

This is intentional: plan mode behaves like a persistent planning state, not a one-shot toggle.

Leaving plan mode

Use either of these commands:

• /build
• /plan off

When plan mode is disabled:

• the original active tool set is restored
• normal write/edit/tool behavior returns
• the inline plan footer indicator disappears

Session-scoped plan files

Each session writes to its own plan file:

.pi/plans/<session-id>.md

This avoids the earlier problem where a single shared current-plan.md was overwritten by different sessions.

Why this matters

• different Pi sessions no longer clobber each other’s plans
• /resume, /reload, and /fork can restore the correct plan context more safely
• plan mode can treat the plan file as a real working artifact for the current session

Tool restrictions in plan mode

Plan mode is intentionally limited.

Allowed tool family

The extension enables only planning-safe tools when available, including:

• read
• grep
• find
• ls
• bash
• write
• edit
• web_search
• code_search
• fetch_content
• get_search_content
• question
• questionnaire
• glob

Write/edit policy

write and edit are allowed only for the session plan file.

Everything else is blocked while plan mode is active.

Bash policy

bash is allowed only for read-only inspection commands.

Allowed examples:

• ls -la
• find src -name '*.ts' | wc -l
• rg AuthProvider src
• git diff --stat
• sed -n '1,120p' src/index.ts

Blocked examples:

• rm -rf tmp
• git commit -m "..."
• npm install
• cat file > other-file
• echo hi && touch foo
• curl ...

Plan extraction and /todos

After a planning reply finishes, the extension tries to extract a numbered Plan: list.

It prefers, in this order:

1. the session plan file
2. the assistant response

The extracted steps are stored in session state and exposed through:

/todos

Task markers use squares:

• □ pending
• ■ completed

Footer behavior

The extension keeps plan status visible inline in the footer.

In plan mode

The footer appends:

• plan

Styling is intentional:

• • uses the same dim/gray footer style as the rest of the footer separators
• plan is shown in the theme warning color

Compatibility goal

The extension does not replace the whole footer anymore.

Instead, it patches footer rendering so the plan label is appended to the existing model/thinking line. This is meant to preserve:

• built-in footer content
• extension statuses
• third-party footer indicators such as limit/status extensions

Persistence model

The extension persists lightweight custom entries in the session so plan state can be restored when appropriate.

Restored on

• /resume
• /reload
• /fork

Not restored on fresh startup

A brand-new session starts in build mode unless you explicitly pass:

pi --plan

This avoids stale plan-mode state leaking into unrelated new sessions.

Commands

Command	Description
/plan	Enter plan mode
/plan <prompt>	Enter plan mode and immediately ask Pi to start planning
/plan off	Leave plan mode
/plan status	Show the current mode and the plan-file path
/build	Leave plan mode and return to normal implementation mode
/todos	Show the latest extracted plan steps

Installation

From npm

pi install npm:@kmiyh/pi-plan-mode

Local development

cd repo-pi-plan-mode
npm install
npm run typecheck
pi -e ./src/index.ts

Repository layout

repo-pi-plan-mode/
  package.json
  package-lock.json
  README.md
  LICENSE
  src/
    index.ts
    utils.ts

Design notes

This implementation intentionally follows a few design decisions:

• Explicit modes instead of a fragile toggle flow
• Session-scoped plan files instead of one shared file
• Normal post-plan conversation flow instead of an approval dialog after every plan
• Inline footer augmentation instead of replacing the full footer UI
• Restricted writes so planning can still produce an artifact without unlocking the full repo

Known scope

This package is focused on planning mode first.

It is not trying to be a full task runner, branch manager, or autonomous execution framework. The main objective is to give Pi a reliable planning state that behaves predictably across turns and sessions.

License

MIT