CMUX Operator & Attention Plane Standard¶

1. Role & Authority Boundary¶

CMUX is strictly the operator surface and attention plane for BLU, Gas City, GitLab, Drupal/DDEV, Oracle, and NAS. It is never a work or source authority.

THOMAS (Operator)
   │
   ▼
CMUX (Operator Surface / Attention Plane)
   ├── Human Attention (Feed Approvals, Notifications, Unread Routing)
   ├── Agent Visibility (Claude, Codex, OpenCode, Teams, Subagents)
   ├── Workspace State (Status, Progress, Logs, Roles, MRs, Ports)
   ├── Verification Plane (Embedded Programmable Browser)
   └── Event Stream (`cmux events` → Signals to BLU)
         │
         ▼
      BLU Orchestrator
         │
         ▼
   Gas City / Beads (Work Authority) ──► GitLab (Source & Release Authority)

What CMUX Does NOT Own:¶

Work graph: Owned by Gas City Beads (bd).
Source code & PRs: Owned by GitLab (glab).
Doctrine & Standards: Owned by BluCity-Docs.
Runtime Execution: Owned by Oracle K3s and NAS Docker.

2. Standard 4-Pane Operator Cockpit¶

┌───────────────────────────────┬───────────────────────────────┐
│ AGENT (Top-Left)              │ VERIFICATION & GITLAB (Top-R) │
│                               │                               │
│ Primary Agent Execution Loop  │ Embedded CMUX Browser:        │
│ Claude / Codex / OpenCode     │ - DDEV Local Site / Preview   │
│ Injected with `gc prime`      │ - GitLab MR & CI Traces       │
│ Hooks wired to Feed & Events  │ - DOM Snapshot Verification   │
├───────────────────────────────┼───────────────────────────────┤
│ WORKSPACE (Bottom-Left)       │ CONTEXT & CONTROL (Bottom-R)  │
│                               │                               │
│ Governed Shell / CLI Surface  │ Diagnostic & Monitoring Stream│
│ git / glab / gc / bd ops      │ - Gas City Hook & Mail Feed   │
│ Remote SSH to Oracle / NAS    │ - QMD Standards Lookup        │
│ DDEV Runtime Container        │ - Live Log & Blast Radius     │
└───────────────────────────────┴───────────────────────────────┘

3. Event-Driven Coordination (`cmux events`)¶

BLU consumes the reconnectable CMUX event stream (cmux events --category feed --category agent --reconnect) rather than polling terminal panes.

Signal Loop:¶

CMUX Event Emitted (Agent Needs Permission / Task Done / Turn Complete)
   │
   ▼
BLU receives event signal
   │
   ▼
BLU queries authoritative state from Gas City (`bd show`) and GitLab (`glab mr view`)
   │
   ▼
BLU routes next governed action

4. Feed & Inline Approval Surface¶

All agent permission prompts, questions, and plan-mode decisions route into CMUX Feed via cmux hooks setup: - Claude Code: Native wrapper hook integration. - Codex: Installed via ~/.codex/hooks.json & config.toml. - OpenCode: Installed via ~/.config/opencode/plugins/cmux-feed.js & cmux-session.js. - Gemini / Cursor / Amp: Standard hook configurations.

The operator resolves permissions centrally in the Feed without terminal context switching.

5. Workspace State & Telemetry¶

Workspaces publish structured operational status using native CMUX primitives: - cmux set-status <key> <value>: e.g. bead=hq-123, mr=!88, ci=running. - cmux set-progress <0.0-1.0>: Visual progress bar in the sidebar. - cmux log <message>: Non-polluting operational trace log.

6. Project-Local Configuration (`.cmux/cmux.json`)¶

Global ~/.config/cmux/cmux.json holds universal operator shortcuts, colors, and security policies (socketControlMode: "automation").

Individual project repositories define scoped <project>/.cmux/cmux.json for: - Project workspace layouts (e.g. Drupal + DDEV + Browser split). - Scoped actions and commands. - Local browser target URLs (https://<project>.ddev.site).

7. Notification Policy & Focus Guard¶

To eliminate alert fatigue across multi-agent fleets, notifications follow severity tiers: 1. P0 / Human Required (Permissions / Blockers): Unread ring + Dock badge + Feed alert. 2. Task Done (Turn Complete / Green CI): Marked in sidebar, non-intrusive. 3. Routine Activity / Subagents: Suppressed from desktop notifications (suppressSubagentNotifications: true).