# pi-cmux usage

Detailed usage for the cmux integrations bundled with `pi-cmux`.

## Notifications

`cmux-notify` sends `cmux notify` alerts once Pi fully settles. It waits for automatic retries, compaction retries, and queued follow-up messages.

Notification fields:
- title: `Pi` by default
- subtitle: `Waiting`, `Task Complete`, or `Error`
- body: short run summary

Notification bodies are summarized from:
- changed files from `edit` and `write`
- reviewed files from `read`
- searches from `grep` and `find`
- shell activity from `bash`
- final agent errors, with first tool failure as fallback

Set `PI_CMUX_NOTIFY_INCLUDE_RESPONSE=1` to append up to 500 characters of the final assistant response to non-error notifications. This is disabled by default because assistant responses may contain sensitive text.

Noise controls:

```bash
PI_CMUX_NOTIFY_LEVEL=all       # Waiting, Task Complete, Error
PI_CMUX_NOTIFY_LEVEL=medium    # Task Complete, Error
PI_CMUX_NOTIFY_LEVEL=low       # Error only
PI_CMUX_NOTIFY_LEVEL=disabled  # off
```

## Sidebar status/log

`cmux-sidebar` updates the cmux right sidebar while Pi runs. It only activates inside a cmux workspace (`CMUX_WORKSPACE_ID` is present).

It uses:
- `cmux set-status` for a temporary Pi status pill while Pi is running, using tools, waiting, done, or errored
- `cmux set-progress` for coarse run progress and live token counts while Pi is active
- `cmux log` for run starts, changed files, warnings, final summaries, and compact session token counts, with cached input split out
- `cmux trigger-flash` once a run fully settles and the surface needs attention

Environment settings:

```bash
PI_CMUX_SIDEBAR=0                    # disable sidebar integration
PI_CMUX_SIDEBAR_FLASH=all            # all | error | disabled
PI_CMUX_SIDEBAR_LOG_TOOLS=1          # log every tool result
PI_CMUX_SIDEBAR_LOG_PROMPT=1         # include truncated prompt in start log
PI_CMUX_SIDEBAR_PROGRESS=0           # disable progress bar updates
PI_CMUX_SIDEBAR_TOKENS=0             # disable compact live session token counts
PI_CMUX_SIDEBAR_COST=1               # include reported model cost with tokens
PI_CMUX_SIDEBAR_FINAL_CLEAR_MS=2500  # clear final status/progress after this delay
PI_CMUX_SIDEBAR_STATUS_KEY=my-key    # override status key
```

## Split tab names

Split and tab creation uses the surface ID returned by cmux to target command startup and naming, rather than guessing from newly visible panes. Older cmux responses without an ID use bounded discovery; ambiguous results fail without starting a command or renaming a surface.

Commands that spawn a split rename the new cmux tab/surface as `<title> · <repo-or-dir>`, using the git repo basename when available and the working-directory basename otherwise. Examples: `Pi · pi-cmux`, `Review · pi-cmux`, `Continue · fix-sidebar`, `npm test · pi-cmux`.

## Split Pi sessions

```text
/cmv [initial prompt]
/cmh [initial prompt]
```

- `/cmv` opens a split to the right.
- `/cmh` opens a split below.
- Both start `pi` in the same working directory.
- Initial prompts are shell-quoted and passed after `--`, so text such as `--help` stays a prompt rather than becoming a Pi option. Inputs beginning with `@` retain Pi's file-input behavior.

Examples:

```text
/cmv
/cmh
/cmv Review the auth flow in this repo
```

Legacy aliases:
- `/cmux-v` → `/cmv`
- `/cmux-h` → `/cmh`

## Tool splits and tabs

```text
/cmo <command...>
/cmoh <command...>
/cmt <command...>
```

- `/cmo` opens a split to the right and runs a shell command.
- `/cmoh` opens a split below and runs a shell command.
- `/cmt` opens a new cmux tab and runs a shell command.
- Commands run via `/bin/sh -c` in the current project directory, preserving the calling Pi process's `PATH`.
- Login profiles are not loaded, and shell aliases/functions are not copied. If a command needs shell initialization, request it explicitly (for example, `/cmo zsh -lic 'my-alias'`).

Examples:

```text
/cmo hx
/cmo npm test
/cmoh npm run dev
/cmt k9s
/cmo watch -n 1 git status --short
```

Alias:
- `/cmov` → `/cmo`

## Agent-opened terminals

`pi-cmux` registers a `cmux_open_terminal` tool so Pi can open interactive terminal programs when explicitly asked.

Example requests:

```text
open k9s in a new tab
open lazygit in a right split
open npm run dev below
```

The tool supports `tab`, `right`, and `down` placements. It uses the same `/bin/sh -c` launch and caller `PATH` as the tool commands above. It is meant for TUIs, log tails, dev servers, watches, and other terminal views that should remain interactive instead of being captured through the normal shell tool.

## Pluggable tool commands

Register custom split shortcuts in Pi settings under `pi-cmux.commands`.

Supported locations:
- `~/.pi/agent/settings.json` for global commands
- `.pi/settings.json` for project-local commands

Simple form:

```json
{
  "pi-cmux": {
    "commands": {
      "edit": "hx",
      "logs": "tail -f logs/app.log"
    }
  }
}
```

Each configured command opens a right cmux split by default and runs via `/bin/sh -c` in the current project directory, preserving the calling Pi process's `PATH` without loading login profiles.

Examples:

```text
/edit
/logs
```

Use object form for arguments, lower splits, custom tab titles, or descriptions:

```json
{
  "pi-cmux": {
    "commands": {
      "edit": {
        "run": "hx",
        "acceptArgs": true,
        "description": "Open Helix in a cmux split"
      },
      "dev": {
        "run": "npm run dev",
        "direction": "down",
        "title": "dev",
        "description": "Run the dev server below"
      }
    }
  }
}
```

Then use:

```text
/edit src/auth.ts
/dev
```

Supported object keys:
- `run` — shell command to execute
- `acceptArgs` — append slash-command arguments to `run` when set to `true`
- `direction` — `right` or `down`; defaults to `right`
- `title` — optional base tab title before ` · <repo-or-dir>` is appended
- `description` — optional slash-command description
- `disabled` — set to `true` in project settings to remove a global configured command

Configured command names cannot reuse built-in Pi commands such as `/settings`, `/model`, or `/reload`, and they cannot replace `pi-cmux` commands such as `/cmv`, `/cmo`, `/cmz`, `/cmrv`, or `/cmcv`.

If the same command exists in both global and project settings, the project setting wins. After changing settings, run `/reload` in Pi.

No app-specific shortcuts are bundled by default; define the tools you want as configured commands.

## Zoxide directory jumps

```text
/cmz <query>
/cmzh <query>
```

- `/cmz` resolves a zoxide match or direct directory path, then starts Pi in a right split.
- `/cmzh` does the same in a lower split.

Examples:

```text
/cmz mono
/cmzh ~/src/project
```

Legacy aliases:
- `/z` → `/cmz`
- `/zh` → `/cmzh`

## Continuation and worktree handoff

```text
/cmcv [note]
/cmch [note]
/cmcv -c <branch> [--from <ref>] [note]
/cmch -c <branch> [--from <ref>] [note]
```

- `/cmcv` opens a continuation split to the right.
- `/cmch` opens a continuation split below.
- Notes are added as focus context.
- `-c <branch>` creates a new branch worktree and starts Pi there.
- `--from <ref>` chooses the base ref for the new worktree branch.

Examples:

```text
/cmcv
/cmcv focus on tests
/cmcv -c fix/notify-bug
/cmcv -c fix/notify-bug --from main
/cmcv -c fix/notify-bug --from main review the existing changes
/cmch -c feature/review-ui focus on edge cases
```

Same-checkout continuation creates a related handoff session and adds a summary of the current context. If the current Pi session is persisted, the new pane also inherits the current conversation path.

Worktree continuation starts a new session in the target worktree and seeds it with structured handoff context from the source pane.

## Review workflows

Split review commands:

```text
/cmrv
/cmrh
/cmrv [--bugs|--refactor|--tests] <target>
/cmrh [--bugs|--refactor|--tests] <target>
/cmrv --diff [focus]
/cmrh --diff [focus]
```

- `/cmrv` opens a review split to the right.
- `/cmrh` opens a review split below.
- With no arguments, both default to reviewing the current git diff.
- A GitHub PR URL switches the prompt to PR review and asks Pi to inspect it with `gh pr view` and `gh pr diff`.
- If another Pi package provides `code-review`, the generated prompt asks Pi to use it when available.

Examples:

```text
/cmrv
/cmrh
/cmrv src/auth.ts
/cmrv --bugs src/auth.ts
/cmrh --refactor src/auth/
/cmrv --diff
/cmrh --diff focus on token refresh and retries
/cmrv https://github.com/owner/repo/pull/123
```

Legacy aliases:
- `/review-v` → `/cmrv`
- `/review-h` → `/cmrh`

`pi-cmux` does not ship generic in-place `/review`, `/review-diff`, or `code-review` resources. Use those from another package if installed.

## Environment variables

```bash
PI_CMUX_NOTIFY_LEVEL=all|medium|low|disabled
PI_CMUX_NOTIFY_THRESHOLD_MS=15000
PI_CMUX_NOTIFY_DEBOUNCE_MS=3000
PI_CMUX_NOTIFY_TITLE=Pi
PI_CMUX_NOTIFY_INCLUDE_RESPONSE=0|1

PI_CMUX_SIDEBAR=0|1
PI_CMUX_SIDEBAR_FLASH=all|error|disabled
PI_CMUX_SIDEBAR_LOG_TOOLS=0|1
PI_CMUX_SIDEBAR_LOG_PROMPT=0|1
PI_CMUX_SIDEBAR_PROGRESS=0|1
PI_CMUX_SIDEBAR_TOKENS=0|1
PI_CMUX_SIDEBAR_COST=0|1
PI_CMUX_SIDEBAR_FINAL_CLEAR_MS=2500
PI_CMUX_SIDEBAR_PROGRESS_CLEAR_MS=2500  # legacy alias for PI_CMUX_SIDEBAR_FINAL_CLEAR_MS
PI_CMUX_SIDEBAR_STATUS_KEY=<key>
PI_CMUX_SIDEBAR_STATUS_PRIORITY=80
PI_CMUX_SIDEBAR_SOURCE=pi
```

cmux uses the current `CMUX_WORKSPACE_ID` / `CMUX_SURFACE_ID` automatically.