Skip to content

espennilsen/pi / extensions/pi-cmux

Orchestrate cmux terminal panes — split terminals, run parallel processes, read output from other panes, and use the built-in browser. Use when working inside cmux and you need to run a dev server, watch tests, spawn sub-agents, or preview web pages.

FileKindSize
AGENTS.mdmarkdown2.2 KB
CHANGELOG.mdmarkdown520 B
README.mdmarkdown1.5 KB
SKILL.mdskill md2.8 KB
client.tsscript24.3 KB
index.tsscript10.0 KB
logger.tsscript582 B
package-lock.jsonmanifest135.9 KB
package.jsonmanifest876 B
tools.tsscript32.7 KB
tsconfig.jsonconfig274 B
---
name: pi-cmux
description: cmux terminal app integration — notifications, pane management, screen reading, and browser automation
---

## Overview

Integrates Pi with the [cmux](https://cmux.dev) macOS terminal app. Communicates via cmux's Unix socket JSON-RPC API at `/tmp/cmux.sock`. Auto-detects cmux via environment variables and no-ops gracefully outside cmux.

## Architecture

```
index.ts          Entry point — detection, lifecycle hooks, commands, shortcuts
client.ts         CmuxClient — Unix socket JSON-RPC client
tools.ts          Agent tools — cmux_list, cmux_split, cmux_read, cmux_send, etc.
logger.ts         Structured logger via pi-logger event bus
```

### Three integration layers:

1. **Passive (lifecycle hooks)**: Pushes notifications and status updates automatically via `agent_start`, `agent_end`, `tool_execution_start/end` hooks. No agent involvement.

2. **Agent tools**: Registers 7 tools so the LLM can drive cmux: `cmux_list`, `cmux_split`, `cmux_read`, `cmux_send`, `cmux_close`, `cmux_notify`, `cmux_browser`.

3. **Skill file**: `SKILL.md` teaches the agent orchestration patterns (dev server + code, parallel tests, sub-agent spawning).

### Detection

cmux injects these env vars into every terminal it spawns:
- `CMUX_WORKSPACE_ID` — current workspace ref
- `CMUX_SURFACE_ID` — current surface (pane) ref
- `CMUX_SOCKET_PATH` — socket path (default: `/tmp/cmux.sock`)

If any are missing or the socket doesn't exist, the extension does nothing.

### Socket protocols

Two protocols over the same Unix domain socket:

**JSON-RPC** — for workspace, surface, notification, browser, and system commands:
```
→ {"id":"uuid","method":"surface.list","params":{}}\n
← {"id":"uuid","ok":true,"result":{"surfaces":[...]}}\n
```

**Text-based** — for sidebar metadata (status pills, progress bars, logs):
```
→ set_status pi thinking... --tab=<workspace-uuid>\n
← OK\n
```

## Conventions

- All cmux calls in lifecycle hooks are wrapped in `safe()` — never throw/crash from hooks
- Tools throw errors (standard Pi pattern) — the LLM gets structured error feedback
- Socket has 10s RPC timeout and 3s connect timeout
- No dependencies beyond Pi and Node.js built-ins
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 322kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 322kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 322kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 198kUpdated Claude CodeCodexVerifiedInstall