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.