pi-cmux

Pi package with cmux-powered terminal integrations for Pi.

What it adds

pi-cmux keeps Pi terminal-native by delegating notifications, sidebar status, pane splits, tab naming, pluggable tool commands, directory jumps, review handoff, and continuation workflows to cmux.

Install

pi install npm:pi-cmux

Or install/update with the package installer:

npx pi-cmux

If Pi is already running:

/reload

Commands

| Workflow | Commands | Summary | |---|---|---| | Notifications | automatic | Sends cmux notify when Pi waits, completes work, or errors. | | Sidebar status/log | automatic | Updates cmux status, progress, logs, and surface flash while Pi runs. | | Split Pi | /cmv [prompt], /cmh [prompt] | Opens a new right/lower split with Pi in the same project. | | Run a tool | /cmo <cmd>, /cmoh <cmd>, /cmt <cmd> | Opens a split or tab and runs a shell command in the same project. | | Pluggable tools | custom /<name> | Registers cmux split shortcuts from pi-cmux.commands settings. | | Jump directory | /cmz <query>, /cmzh <query> | Resolves a zoxide match or path, then opens Pi there. | | Continue task | /cmcv [note], /cmch [note] | Opens a related handoff session in a split. | | Continue in worktree | /cmcv -c <branch> [--from <ref>] [note] | Creates a branch worktree and starts Pi there with handoff context. | | Review in split | /cmrv [flags] [target], /cmrh [flags] [target] | Starts a focused review session in a split. |

Detailed command examples: docs/usage.md.

Common examples

/cmv Review the auth flow
/cmo npm test
/cmt k9s
/cmz mono
/cmcv focus on tests
/cmcv -c fix/sidebar --from main
/cmrv --bugs src/auth.ts
/cmrv https://github.com/owner/repo/pull/123

Configuration

| Variable | Default | Purpose | |---|---:|---| | PI_CMUX_NOTIFY_LEVEL | all | all, medium, low, or disabled. | | PI_CMUX_NOTIFY_INCLUDE_RESPONSE | 0 | Append truncated final assistant response to non-error notifications. | | PI_CMUX_NOTIFY_THRESHOLD_MS | 15000 | Duration threshold for Task Complete vs Waiting. | | PI_CMUX_SIDEBAR | 1 | Set 0 to disable sidebar integration. | | PI_CMUX_SIDEBAR_FLASH | all | all, error, or disabled. | | PI_CMUX_SIDEBAR_PROGRESS | 1 | Set 0 to disable sidebar progress updates. | | PI_CMUX_SIDEBAR_TOKENS | 1 | Include compact live cumulative session token counts in sidebar progress and summaries. | | PI_CMUX_SIDEBAR_COST | 0 | Include reported model cost alongside token counts. | | PI_CMUX_SIDEBAR_LOG_TOOLS | 0 | Set 1 to log every tool result. |

Custom split shortcuts can be registered under pi-cmux.commands in ~/.pi/agent/settings.json or .pi/settings.json; see docs/usage.md.

Example Hunk review shortcut:

{
  "pi-cmux": {
    "commands": {
      "ck": {
        "run": "hunk diff --agent-notes --watch",
        "acceptArgs": true,
        "description": "Open Hunk diff with agent notes in a cmux split"
      }
    }
  }
}

Use /ck to open Hunk in a cmux split, add Hunk comments while reviewing, then ask Pi to read them.

pi-cmux also exposes an agent tool so Pi can open an explicitly requested terminal command in a cmux split or tab. For example, asking "open k9s in a new tab" lets Pi open k9s without trying to capture the TUI through a shell command.

cmux workspace/surface targeting uses CMUX_WORKSPACE_ID and CMUX_SURFACE_ID automatically. Sidebar integration only activates inside a cmux workspace.

Bundled resources

Extensions: cmux-notify, cmux-sidebar, cmux-split, cmux-open, cmux-zoxide, cmux-review, cmux-continue.

pi-cmux intentionally does not bundle generic review skills or prompt templates, so packages that provide /review, /review-diff, or code-review can own those names without conflicts.