Documentation

pibarm is a pi package — the extensions and skills I use for planning, worktrees, presets, and watching agents work. Install it into whatever project you like.

Quick start

Install pibarm; its Pi package settings load Marionette independently, like Ponytail. Marionette owns planning and traversal while pibarm adds routing, task UI, notifications, and delegation context.

bash

pi install git@github.com:leemeichin/pibarm.git

ℹ

Nerd Font glyphs

The TUI uses Nerd Font icons for the statusline and task widget. Install a Nerd Font, or they render as boxes.

Main workflow

Plan first, edit later. pi inspects read-only, asks questions, and only executes after you approve — ideally in an isolated worktree.

text

/plan <task>
  ↓  pi inspects read-only, asks questions
/approve-plan worktree <name>
  ↓  changes happen in .pi/wt/<name>, not your checkout
/worktree-diff .pi/wt/<name>

▲

Plan mode is read-only

edit and write are disabled and bash is restricted until you approve the captured plan.

Commands

A selection of the slash-commands pibarm adds. Press / in pi to browse them all.

/plan <task>

Enter read-only plan mode and ask for a plan.

/execute-plan worktree <name>safe

Execute the captured plan in a new repo-local git worktree.

/worktree-diff <path>

Show status + diff stat for a worktree before you merge.

/agents [name]panes

List managed agents or capture one agent log.

/agents-attachpanes

Focus a managed pane or show its attach command.

/agents-kill [name|all]panes

Stop managed panes without touching the parent session.

/preset planner

Apply the planner model / tool / thinking preset.

/repo-status

Show git / forge / CI status and update the statusline.

/review [#number|url]

Start a PR / patch review; findings posted inline.

/obsidian-export

Export the current session to your Obsidian vault.

Automatic agent panes

The standard subagent and worktree tools use a shared runner with matching tmux and Zellij adapters. The active multiplexer gets managed panes; outside one, pibarm creates a detached native session and prints its attach command. Without either, the same calls fall back headlessly.

bash

run_subagents → automatic tmux/Zellij panes
run_worktree_agent → isolated branch in the same session
/agents            # list or capture logs
/agents-attach     # focus or print native attach command
/agents-kill all   # stop children, never the parent session

✓

No second agent API

Models keep using run_subagent, run_subagents, and run_worktree_agent; configuration chooses only the renderer.

Notifications

waiting-notify.ts sends a local notification when a question is waiting — Kitty's escape, terminal-notifier, or an iTerm2-style fallback.

bash

export PI_NOTIFY_COOLDOWN_SECONDS=60
export PI_NOTIFY_INCLUDE_QUESTION=1