pi-cmux

Pi package with cmux-powered terminal integrations

Packages

Package details

extension

Install pi-cmux from npm and Pi will load the resources declared by the package manifest.

npm repo home report

$ pi install npm:pi-cmux

Package: pi-cmux
Version: 0.6.0
Published: Nov 3, 2026
Downloads: 5,790/mo · 3,463/wk
Author: javimolina
License: MIT
Types: extension
Size: 1.8 MB
Dependencies: 0 dependencies · 2 peers

Pi manifest JSON

{
  "extensions": [
    "./extensions/index.ts"
  ]
}

Security note

Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.

README

Pi tools for cmux: parallel chats, terminal commands, browser annotations and task handoffs.

Install · Commands · Configuration · Usage guide

Capabilities

Start independent chats or related reviewers.
Jump to any cmux terminal or browser tab with /cm.
Run tools beside Pi, annotate browser pages and continue tasks in new worktrees.
Show progress, tokens and optional notifications in the sidebar.

Pi running inside a cmux workspace

Install

Requires Pi 1.3.0+ and Node.js 22.19.0+, with pi on your PATH or a Pi-compatible wrapper selected via PI_CMUX_BINARY.

pi install npm:pi-cmux
# Or install/update with:
npx pi-cmux

For native notifications, session restore and prompt previews:

cmux hooks pi install

Package notifications default to off to avoid duplicate alerts. Zoxide is needed only for fuzzy directory matching.

Commands

Task	Command
Diagnose/setup cmux and panel	`/cmdoctor`
New sidebar chat	`/cmn <prompt>`
Pi right/below	`/cmv [prompt]`, `/cmh [prompt]`
Tool right/below/tab	`/cmo <cmd>`, `/cmoh <cmd>`, `/cmt <cmd>`
Browser	`/cmb [--down] [--focus] <url>`
Browser annotations	Turn on Annotate; sending requires confirmation in Pi
Jump directory	`/cmz <path-or-query>`, `/cmzh <path-or-query>`
Return to origin	`/cmbk` or Ctrl+Alt+B
Jump to pane	`/cm` or optional `PI_CMUX_SWITCHER_KEY`
Continue task	`/cmcv [note]`, `/cmch [note]`
Continue in worktree	`/cmcv -c <branch> [--from <ref>] [note]`
Peer messages	`/cmmsg inbox`, `/cmmsg status`, `/cmmsg on`, `/cmmsg off`

Tabs use an available task name, otherwise the project name plus role/task tag. Explicit launch titles and /name take priority; this policy makes no extra model calls. See naming.

You can also ask Pi to open a tool, browser or another Pi session. Independent tasks default to new workspaces; the first active same-task agent/reviewer opens beside its creator, additional/background collaborators and handoffs use tabs.

Experimental SSH

Connect to javi
# Or choose a project:
Connect to javi in /srv/project

Pi and its credentials/session files stay local; ssh_read, ssh_write, ssh_edit and ssh_bash use the explicit remote target.See selection, guards and migration.

Resume/child launches restore selection, not readiness. Remote-owned layouts, SSH handoffs/worktrees and new browser previews are unsupported. See SSH setup, controls and limits.

Configuration

Set environment variables before starting Pi. Package settings belong in ~/.pi/agent/settings.json or project .pi/settings.json; project settings override global settings.

Variable	Default	Purpose
`PI_CMUX_BINARY`	`pi`	Pi-compatible executable name or path, e.g. `sumocode`; no arguments or shell commands
`PI_CMUX_PI_PATH_MODE`	`minimal`	Prepend selected executable/Node directories to child PATH; `full` preserves caller PATH
`PI_CMUX_SSH`	`1`	`0` disables SSH execution/connections; saved remote intent stays blocked until explicit clear
`PI_CMUX_SSH_DISCOVERY`	`1`	`0` disables SSH suggestions
`PI_CMUX_SSH_ALIAS_SAVE`	`1`	`0` disables alias saving
`PI_CMUX_NOTIFY_LEVEL`	`disabled`	Opt in with `all`, `medium` or `low`
`PI_CMUX_SIDEBAR_MODE`	`detailed`	`minimal` shows status/tokens without package logs/progress
`PI_CMUX_RETURN_KEY`	`ctrl+alt+b`	Change shortcut or set `off`; `/cmbk` remains
`PI_CMUX_SWITCHER_KEY`	`off`	Pi-local shortcut for `/cm`, e.g. `ctrl+alt+p`; not a cmux-wide binding
`PI_CMUX_AUTOTITLE`	`0`	Enable model-generated topics; sends conversation excerpts and may incur charges

All settings and shortcuts · PATH behavior · Browser privacy

Sidebar

The packaged agent state right panel shows live state symbols/colors, foldable workspace groups, exact current-agent highlighting and surface actions only for workspaces with open tracked agents (including idle agents). Closed (ended) sessions are hidden, and closing the last session removes its workspace from the panel.

Auto-open (opt-in)

After separately installing the panel, manually add this to Pi's settings.json:

{ "pi-cmux": { "panel": { "autoOpen": true } } }