branch-workspace

Pi extension that gives each git branch its own workspace and a read-only / edit mode guard.

Install

pi install npm:@po.dev/pi-branch-workspace

Or load locally:

pi -e ./branch-workspace/index.ts

Features

• Each git branch gets .pi/<branch>/workspace.md injected as context every session
• read-only mode — reads and traces the codebase before answering; blocks direct writes outside .pi/** while allowing reads, chmod, and operations outside the project
• edit mode — full access; commits only when you explicitly run /ws commit
• Switching to edit mode automatically kicks off whatever was agreed on in the conversation
• AGENTS.md (or .pi/agents.md) injected as shared repo instructions

Commands

/mode                  show current mode
/mode read-only, /mode r  switch to read-only
/mode edit, /mode e       switch to edit and start implementing
/r                       shortcut for read-only mode
/e                       shortcut for edit mode
/ws                    pick a workspace section to update from conversation
/ws plan               update the Plan section
/ws <section>          update or create any section
/ws commit             commit all uncommitted changes as "wip: <agent summary>"

Workspace layout

.pi/
  agents.md                   shared repo instructions
  <branch>/
    workspace.md              plan, discussion, progress notes
    .mode                     current mode (read-only | edit)

Mode rules

• Every session start / /reload resets .mode to read-only — /mode edit only lasts the current session
• Missing .mode → defaults to read-only
• Invalid value → resets to read-only with a warning
• In read-only mode, direct write and edit calls can change only .pi/**; .mode itself can still be changed only through /mode, /r, or /e