A Pi package that turns cmux into your coding workspace. Start parallel chats, run tools beside your agent, annotate browser pages, and carry a task into a fresh worktree without leaving the terminal.

Install · Capabilities · Commands · Configuration · Usage guide

• Parallel Pi sessions. Start a fresh chat in a named sidebar workspace or split Pi beside your current session, in the current project or another directory.
• Tools within reach. Open tests, dev servers, and interactive tools in splits or tabs. Define shortcuts for commands you use often.
• Browser feedback. Preview a page beside Pi, select an element, and send a note back after confirming it in Pi.
• Handoffs with context. Continue a task in another split or a new branch worktree with handoff context.
• Quick project jumps. Start Pi in another directory using a path or a zoxide match.
• Progress at a glance. See status, progress, token counts, and logs in the cmux sidebar, with optional cost reporting and notifications.

Requires Pi 0.85.1 or newer and Node.js 22.19.0 or newer. The pi executable on your PATH must also meet this requirement. Update Pi if needed:

npm install -g --ignore-scripts @earendil-works/pi-coding-agent@latest

Then install the package:

pi install npm:pi-cmux

Or install/update with the package installer:

npx pi-cmux

Run Pi inside cmux to use the integrations. For native notifications, session restore, and prompt previews, install cmux's Pi hooks:

cmux hooks pi install

Package notifications are opt-in to avoid duplicating native hook notifications. Directory matching with /cmz and /cmzh uses zoxide; explicit paths work without it.

New Pi sessions and tool terminals preserve the calling Pi process's PATH, so executables such as Pi, Node, and Hunk remain discoverable even when cmux has a different terminal environment. Tool commands use an inner /bin/sh -c, but cmux 0.64.25 wraps respawns in /bin/sh -lc. Login profiles may run before our command restores PATH; profile side effects are not prevented. This does not copy the caller's shell aliases or functions.

New workspaces use cmux --json workspace create, verified against cmux 0.64.25 (106). Creation targets the caller's window and is never automatically retried; if identification or startup fails, inspect cmux before retrying because the workspace may already exist. Older cmux versions have not been verified.

Detailed command examples: docs/usage.md.

/cmn Investigate the slow startup
/cmv Review the auth flow
/cmo npm test
/cmt k9s
/cmb http://localhost:3000
/cmz mono
/cmcv focus on tests
/cmcv -c fix/sidebar --from main

For a quieter sidebar, set export PI_CMUX_SIDEBAR_MODE=minimal before starting Pi. Minimal mode suppresses all package logs and progress even if their individual flags are enabled. Tokens appear on the existing status line; set PI_CMUX_SIDEBAR_TOKENS=0 to hide them. Cost remains opt-in via PI_CMUX_SIDEBAR_COST=1. It does not remove existing logs or hide cmux's native message previews, activity, branch, or path. See sidebar modes.

Conversation tab titles are opt-in. After successful settlement, a background LLM request summarizes up to four recent text messages (300 characters each) and renames only the current cmux tab. This sends conversation excerpts to the selected model provider and may incur additional usage charges. It runs only in interactive Pi inside cmux, uses the session's provider registry, and never creates a child Pi session. /name takes priority; automatic titles are saved in the session so reload/resume does not repeat the request. See conversation tab titles for configuration and lifecycle behavior.

Custom split shortcuts can be registered under pi-cmux.commands, and tool-start notifications can be enabled under pi-cmux.notify.tools, in ~/.pi/agent/settings.json or .pi/settings.json; see docs/usage.md and tool notification settings.

Example tool notification settings:

{
  "pi-cmux": {
    "notify": {
      "tools": {
        "ask_user_question": true
      }
    }
  }
}

Set PI_CMUX_NOTIFY_LEVEL=all, medium, or low to enable notifications too; the default disabled suppresses both final-run and tool-start notifications. Configured tools notify at any enabled level, only while Pi runs interactively inside a cmux surface unless PI_CMUX_NOTIFY_FORCE=1. Run /reload after changing settings.

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.

Ask "start a fresh Pi session in a right split in ~/src/other-repo" to use cmux_start_pi with cwd. The optional path accepts absolute paths, paths relative to the current session, and ~/…; it must be an existing directory. Omit it to keep the current directory. cwd cannot be combined with continueSession: true; handoffs keep the source directory or use the new branch worktree.

Ask "open http://localhost:3000 beside Pi" to use cmux_open_browser. An Annotate toggle appears automatically, initially off. Switch it on, select an element, write a note, and Send; Pi shows a compact note preview with Cancel / Send to Pi before steering. Switch it off to browse normally without losing your draft. Page scripts can forge submissions, so approve only notes you recognize. See browser usage and lifecycle.

cmux workspace/surface targeting uses CMUX_WORKSPACE_ID and CMUX_SURFACE_ID automatically. New terminal splits and tabs use cmux's returned surface IDs; older terminal-creation responses fall back to bounded discovery that rejects ambiguous matches. Browser opening requires validated UUIDs and does not use discovery fallbacks. A session-scoped cmux event listener removes closed browser bindings and stops their annotation bridges quietly, with retrying inventory checks to recover missed events. Sidebar integration only activates inside a cmux workspace.