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 into another project. pi loads its extensions and skills on startup once you trust the project.

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