espennilsen/pi / extensions/pi-cmux
cmux
FlaggedOrchestrate 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.
| File | Kind | Size |
|---|---|---|
| AGENTS.md | markdown | 2.2 KB |
| CHANGELOG.md | markdown | 520 B |
| README.md | markdown | 1.5 KB |
| SKILL.md | skill md | 2.8 KB |
| client.ts | script | 24.3 KB |
| index.ts | script | 10.0 KB |
| logger.ts | script | 582 B |
| package-lock.json | manifest | 135.9 KB |
| package.json | manifest | 876 B |
| tools.ts | script | 32.7 KB |
| tsconfig.json | config | 274 B |
AGENTS.md
View on GitHub---
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
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |