cru-teams 1.0.2 → 1.1.0

package/README.md

@@ -25,6 +25,7 @@ Agent teams let multiple Claude Code instances work together in parallel — cru
 - **Already using tmux?** You're good.
 - **iTerm2?** Use [`tmux -CC`](https://iterm2.com/documentation-tmux-integration.html) for native pane integration.
 - **Ghostty?** Workers still run in tmux (that's how Claude Code spawns agents), but cru mirrors them into native Ghostty splits via [AppleScript](https://ghostty.org/docs/features/applescript) — so you get Ghostty's UI instead of working inside tmux yourself. Requires Ghostty v1.3.0+.
+- **[cmux](https://www.cmux.dev)?** Native support — cru mirrors workers into cmux splits via the cmux CLI socket. Tabs get labeled with ◫ (lead) and ⚡ (workers) for quick identification. Auto-detected when running inside cmux.
 
 ## Install
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cru-teams",
-  "version": "1.0.2",
+  "version": "1.1.0",
   "description": "◫ Manage terminal layouts for Claude Code agent teams",
   "type": "module",
   "bin": {
@@ -24,6 +24,7 @@
   ],
   "license": "ISC",
   "dependencies": {
+    "ajv": "^8.18.0",
     "incur": "^0.2.2"
   },
   "devDependencies": {

package/src/cli.ts

@@ -21,9 +21,11 @@ const PREFLIGHT: Record<string, string[]> = {
   panes: ['pane-session'],
 }
 
+const pkg = require('../package.json')
+
 Cli.create('cru', {
   description: '◫ Manage pane layouts for Claude Code agent teams',
-  version: '1.0.0',
+  version: pkg.version,
 })
   .use(async (c, next) => {
     const checks = PREFLIGHT[c.command]

package/src/commands/doctor.ts

@@ -1,5 +1,5 @@
 import { z } from 'incur'
-import { hasBinary, getVersion, inTmux, inGhostty, detectTerminal } from '../lib/env'
+import { hasBinary, getVersion, inTmux, inGhostty, inCmux, detectTerminal } from '../lib/env'
 
 export const doctor = {
   description: 'Check environment requirements for cru',
@@ -68,6 +68,22 @@ export const doctor = {
       }
     }
 
+    // cmux support
+    if (inCmux()) {
+      try {
+        const { cmuxVersion, isCmuxAvailable } = require('../lib/cmux')
+        if (isCmuxAvailable()) {
+          const ver = cmuxVersion() || 'unknown'
+          checks.push({ name: 'cmux', status: 'ok', detail: `${ver} (socket connected)` })
+          checks.push({ name: 'pane-backend', status: 'ok', detail: 'cmux (native CLI)' })
+        } else {
+          checks.push({ name: 'cmux', status: 'fail', detail: 'socket not responding', fix: 'Ensure cmux is running' })
+        }
+      } catch {
+        checks.push({ name: 'cmux', status: 'fail', detail: 'cannot connect to cmux' })
+      }
+    }
+
     const bunPath = hasBinary('bun')
     if (!bunPath) {
       checks.push({ name: 'bun', status: 'fail', detail: 'not installed', fix: 'curl -fsSL https://bun.sh/install | bash' })

package/src/commands/panes.ts

@@ -7,7 +7,7 @@ import {
 } from '../lib/tmux'
 import { computeGrid } from '../lib/layout'
 import { loadPanes, savePanes } from '../lib/panes'
-import { inGhostty } from '../lib/env'
+import { inGhostty, inCmux } from '../lib/env'
 
 /**
  * Ghostty+tmux mirror flow:
@@ -135,19 +135,196 @@ function runGridGhostty(c) {
   }
 }
 
+const WORKER_COLORS = ['green', 'blue', 'yellow', 'magenta', 'cyan', 'red']
+
+/** Resolve worker names from team config, falling back to "worker-N". */
+function resolveWorkerNames(teamName: string | undefined, count: number): string[] {
+  if (teamName) {
+    try {
+      const config = readTeamConfig(teamName)
+      // Filter out the lead (role=lead or name=main/team-lead) — only want workers
+      const names = (config.members || [])
+        .filter((m: any) => m.role !== 'lead' && m.name !== 'main' && m.name !== 'team-lead')
+        .map((m: any) => m.name)
+      if (names.length >= count) return names.slice(0, count)
+    } catch {}
+  }
+  return Array.from({ length: count }, (_, i) => `worker-${i + 1}`)
+}
+
+/** Apply config overrides from CLI options. */
+function applyConfigOverrides(conf: ReturnType<typeof loadConfig>, options: any): void {
+  if (options['lead-size'] != null) conf.layout.lead.size = options['lead-size']
+  if (options['lead-position']) conf.layout.lead.position = options['lead-position']
+  if (options.fill) conf.layout.grid.fill = options.fill
+  if (options['max-cols'] != null) conf.layout.grid.maxCols = options['max-cols']
+  if (options['max-rows'] != null) conf.layout.grid.maxRows = options['max-rows']
+}
+
+/**
+ * cmux grid: mirror headless tmux workers into cmux splits.
+ *
+ * Same approach as Ghostty: workers spawn in `tmux -L claude-swarm-*`
+ * sessions. We find the swarm, break each pane into its own tmux window,
+ * create cmux splits, and attach each to a view session.
+ */
+function runGridCmux(c) {
+  const {
+    findBestSwarm,
+    getWorkerPanes,
+    mirrorWorkerToCmux,
+    setRemainOnExit,
+  } = require('../lib/mirror')
+  const {
+    currentSurface,
+    focusSurface,
+    closeSurface,
+    renameSurface,
+    getSurfaceTitle,
+  } = require('../lib/cmux') as typeof import('../lib/cmux')
+
+  const teamName = c.args.team
+  const expectedWorkers = c.options.expect
+  const leadSurface = currentSurface()
+  const deadline = Date.now() + 60_000
+
+  // Close previously-tracked workers (never arbitrary surfaces)
+  if (teamName) {
+    const existing = loadPanes(teamName)
+    if (existing?.backend === 'cmux') {
+      for (const w of existing.workers) closeSurface(w.paneId)
+      Bun.sleepSync(300)
+    }
+  }
+
+  // 1. Find the swarm socket
+  let swarm: { socket: string; session: string } | null = null
+  if (expectedWorkers) {
+    while (Date.now() < deadline) {
+      swarm = findBestSwarm(expectedWorkers)
+      if (swarm) break
+      Bun.sleepSync(200)
+    }
+  } else {
+    swarm = findBestSwarm()
+  }
+
+  if (!swarm) {
+    return c.error({
+      code: 'NO_SWARM',
+      message: 'No claude-swarm tmux session found. Is a Claude Code team running?',
+    })
+  }
+
+  console.log(`  [grid] found swarm: ${swarm.socket}/${swarm.session}`)
+  setRemainOnExit(swarm.socket)
+
+  // 2. Incrementally mirror workers into a grid layout
+  //    Row 0: split right from lead, then right from each previous
+  //    Row 1+: split down from the column above
+  const conf = loadConfig()
+  applyConfigOverrides(conf, c.options)
+  const totalExpected = expectedWorkers || 1
+  const { cols } = computeGrid(totalExpected, conf.layout)
+  const mirrored = new Map<string, { cmuxSurface: string; viewSession: string }>()
+  const mirroredSurfaces: string[] = [] // ordered list for grid positioning
+
+  while (Date.now() < deadline) {
+    const allWorkers = getWorkerPanes(swarm.socket)
+    const newWorkers = allWorkers.filter((p: string) => !mirrored.has(p))
+
+    for (const paneId of newWorkers) {
+      const idx = mirrored.size
+      const row = Math.floor(idx / cols)
+      const col = idx % cols
+
+      let splitDir: 'right' | 'down'
+      let splitTarget: string
+      if (idx === 0) {
+        // First worker: split right from lead
+        splitDir = 'right'
+        splitTarget = leadSurface
+      } else if (row === 0) {
+        // Row 0: split right from previous worker
+        splitDir = 'right'
+        splitTarget = mirroredSurfaces[idx - 1]
+      } else {
+        // Row 1+: split down from the cell above in same column
+        splitDir = 'down'
+        splitTarget = mirroredSurfaces[(row - 1) * cols + col]
+      }
+
+      const result = mirrorWorkerToCmux(
+        swarm.socket, swarm.session,
+        paneId, idx, splitTarget, splitDir,
+      )
+      mirrored.set(paneId, result)
+      mirroredSurfaces.push(result.cmuxSurface)
+    }
+
+    if (expectedWorkers && mirrored.size >= expectedWorkers) break
+
+    if (!expectedWorkers && mirrored.size > 0 && newWorkers.length === 0) {
+      Bun.sleepSync(3000)
+      const finalWorkers = getWorkerPanes(swarm.socket)
+      if (finalWorkers.filter((p: string) => !mirrored.has(p)).length === 0) break
+      continue
+    }
+
+    Bun.sleepSync(200)
+  }
+
+  if (mirrored.size === 0) {
+    return c.error({ code: 'NO_WORKERS', message: 'No worker panes found in swarm.' })
+  }
+
+  // 3. Label surfaces
+  const label = teamName || 'cru'
+  const leadOriginalTitle = getSurfaceTitle(leadSurface)
+  try { renameSurface(leadSurface, `${leadOriginalTitle} (◫ lead @ ${label})`) } catch {}
+
+  const mirrors = [...mirrored.entries()]
+  const names = resolveWorkerNames(teamName, mirrors.length)
+  const workers = mirrors.map(([, m], i) => {
+    try { renameSurface(m.cmuxSurface, `⚡ ${names[i]} @ ${label}`) } catch {}
+    return { name: names[i], paneId: m.cmuxSurface, color: WORKER_COLORS[i % WORKER_COLORS.length] }
+  })
+
+  // 4. Focus lead and save tracking
+  focusSurface(leadSurface)
+
+  if (teamName) {
+    savePanes(teamName, {
+      leadPane: leadSurface,
+      windowId: leadSurface,
+      backend: 'cmux',
+      createdAt: Date.now(),
+      workers,
+      leadOriginalTitle,
+    })
+  }
+
+  return {
+    applied: true,
+    backend: 'cmux',
+    swarm: `${swarm.socket}/${swarm.session}`,
+    workers: mirrored.size,
+  }
+}
+
 function runGrid(c) {
+  // cmux: native pane management via CLI
+  if (inCmux()) {
+    return runGridCmux(c)
+  }
+
   // Ghostty: mirror tmux panes into native splits
   if (inGhostty()) {
     return runGridGhostty(c)
   }
 
   const conf = loadConfig()
-
-  if (c.options['lead-size'] != null) conf.layout.lead.size = c.options['lead-size']
-  if (c.options['lead-position']) conf.layout.lead.position = c.options['lead-position']
-  if (c.options.fill) conf.layout.grid.fill = c.options.fill
-  if (c.options['max-cols'] != null) conf.layout.grid.maxCols = c.options['max-cols']
-  if (c.options['max-rows'] != null) conf.layout.grid.maxRows = c.options['max-rows']
+  applyConfigOverrides(conf, c.options)
 
   const teamName = c.args.team
   let windowId: string | null = null
@@ -233,7 +410,7 @@ function runGrid(c) {
 
 function runClose(c) {
   let teamName = c.args.team
-  if (!teamName && !inGhostty()) {
+  if (!teamName && !inGhostty() && !inCmux()) {
     try { teamName = findTeamForCurrentWindow() } catch {}
   }
   if (!teamName) return c.error({ code: 'NO_TEAM', message: 'No team specified and none found in current window' })
@@ -242,9 +419,14 @@ function runClose(c) {
   const cruPanes = loadPanes(teamName)
   if (cruPanes && cruPanes.workers.length > 0) {
     // Use the right kill method based on how panes were tracked
-    const killFn = cruPanes.backend === 'ghostty'
-      ? (id: string) => { try { require('../lib/ghostty').closeTerminal(id) } catch (e) { console.warn(`[close] failed to close Ghostty terminal ${id}: ${e}`) } }
-      : (id: string) => killPane(id)
+    let killFn: (id: string) => void
+    if (cruPanes.backend === 'cmux') {
+      killFn = (id: string) => { try { require('../lib/cmux').closeSurface(id) } catch (e) { console.warn(`[close] failed to close cmux surface ${id}: ${e}`) } }
+    } else if (cruPanes.backend === 'ghostty') {
+      killFn = (id: string) => { try { require('../lib/ghostty').closeTerminal(id) } catch (e) { console.warn(`[close] failed to close Ghostty terminal ${id}: ${e}`) } }
+    } else {
+      killFn = (id: string) => killPane(id)
+    }
 
     for (const w of cruPanes.workers) {
       killFn(w.paneId)
@@ -282,7 +464,21 @@ function runClose(c) {
     } catch {}
   }
 
-  if (closed.length === 0 && inGhostty()) {
+  if (closed.length === 0 && inCmux()) {
+    // Fallback: close all non-lead cmux surfaces in the caller's workspace only
+    try {
+      const { currentSurface, currentWorkspace, listAllSurfaceIds, closeSurface } = require('../lib/cmux')
+      const lead = currentSurface()
+      const ws = currentWorkspace()
+      const allSurfaces = listAllSurfaceIds(ws)
+      for (const id of allSurfaces) {
+        if (id !== lead) {
+          closeSurface(id)
+          closed.push({ name: `pane-${closed.length + 1}`, pane: id })
+        }
+      }
+    } catch {}
+  } else if (closed.length === 0 && inGhostty()) {
     // Fallback: close all non-lead Ghostty terminals
     // Uses process-tree-based currentTerminal() — works regardless of focus
     try {
@@ -310,10 +506,41 @@ function runClose(c) {
     } catch {}
   }
 
+  // Restore lead pane's original title (remove appended team label)
+  if (cruPanes?.backend === 'cmux' && cruPanes.leadOriginalTitle != null) {
+    try {
+      const { renameSurface } = require('../lib/cmux')
+      renameSurface(cruPanes.leadPane, cruPanes.leadOriginalTitle)
+    } catch {}
+  }
+
+  // Clean up pane tracking file (team data stays for `cru logs` review)
+  if (teamName && closed.length > 0) {
+    try {
+      const { unlinkSync } = require('node:fs')
+      const { join } = require('node:path')
+      const { teamsDir } = require('../lib/paths')
+      unlinkSync(join(teamsDir(), teamName, 'cru-panes.json'))
+    } catch {}
+  }
+
   return { team: teamName, closed: closed.length, panes: closed }
 }
 
 function runList(c) {
+  if (inCmux()) {
+    const { currentSurface, listSurfaces } = require('../lib/cmux')
+    let currentId: string | null = null
+    try { currentId = currentSurface() } catch {}
+    const surfaces = listSurfaces()
+    const panes = surfaces.map((s: { id: string; index: number }) => ({
+      id: s.id,
+      index: s.index,
+      current: s.id === currentId,
+    }))
+    return { backend: 'cmux', panes }
+  }
+
   if (inGhostty()) {
     const { ghostty, currentTerminal, listAllTerminals } = require('../lib/ghostty')
     const allIds = listAllTerminals()

package/src/lib/cmux.ts

@@ -0,0 +1,258 @@
+/**
+ * cmux backend — native pane management via the cmux CLI.
+ *
+ * cmux is a macOS terminal with a CLI for controlling panes/surfaces
+ * via a Unix socket (/tmp/cmux.sock).
+ *
+ * IMPORTANT: All operations pass explicit --surface/--workspace flags
+ * so they work regardless of which tab/surface the user has focused.
+ * Never rely on the "focused" or "current" surface.
+ *
+ * Surface refs (surface:N) are monotonic — they don't shift when
+ * other surfaces are created or destroyed, so they're safe to store.
+ *
+ * Environment variables set by cmux in each terminal:
+ *   CMUX_WORKSPACE_ID, CMUX_SURFACE_ID, CMUX_SOCKET_PATH
+ */
+
+import { execFileSync } from 'node:child_process'
+import { computeGrid } from './layout'
+import type { LayoutConf } from './tmux'
+
+export interface CmuxSurface {
+  id: string   // e.g. "surface:15" — monotonic ref, stable for the session
+  index: number
+  title: string
+  focused: boolean
+}
+
+// ---------------------------------------------------------------------------
+// Core
+// ---------------------------------------------------------------------------
+
+/** Run a cmux CLI command safely (no shell interpolation). */
+export function cmux(...args: string[]): string {
+  return execFileSync('cmux', args, { encoding: 'utf-8', timeout: 10_000 }).trim()
+}
+
+/** Check if cmux socket is responding. */
+export function isCmuxAvailable(): boolean {
+  try {
+    cmux('ping')
+    return true
+  } catch {
+    return false
+  }
+}
+
+/** Get cmux version. */
+export function cmuxVersion(): string | null {
+  try {
+    return cmux('version')
+  } catch {
+    return null
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Identity
+// ---------------------------------------------------------------------------
+
+/**
+ * Get the caller's surface ref and workspace ref.
+ * Uses `cmux identify` which reliably returns the calling process's context,
+ * regardless of what the user has focused.
+ */
+export function identify(): { surface: string; workspace: string } {
+  const info = JSON.parse(cmux('identify'))
+  const surface = info.caller?.surface_ref
+  const workspace = info.caller?.workspace_ref
+  if (!surface) throw new Error('cmux identify did not return caller surface_ref')
+  return { surface, workspace: workspace || 'workspace:1' }
+}
+
+/** Get the caller's surface ref. */
+export function currentSurface(): string {
+  return identify().surface
+}
+
+/** Get the caller's workspace ref. */
+export function currentWorkspace(): string {
+  return identify().workspace
+}
+
+// ---------------------------------------------------------------------------
+// Surfaces
+// ---------------------------------------------------------------------------
+
+/** List all surfaces in a workspace. Defaults to the caller's workspace. */
+export function listSurfaces(workspace?: string): CmuxSurface[] {
+  const ws = workspace || currentWorkspace()
+  const output = cmux('list-panels', '--workspace', ws)
+  if (!output) return []
+
+  return output.split('\n')
+    .filter(Boolean)
+    .map((line, i) => {
+      // Format: "* surface:15  terminal  [focused]  "Title""
+      // or:     "  surface:20  terminal  "Title""
+      const match = line.match(/^([*\s]*)(surface:\d+)\s+\S+\s*(.*)$/)
+      if (!match) return null
+      const focused = match[3].includes('[focused]')
+      const titleMatch = match[3].match(/"([^"]*)"/)
+      return {
+        id: match[2],
+        index: i,
+        title: titleMatch?.[1] || '',
+        focused,
+      }
+    })
+    .filter((s): s is CmuxSurface => s !== null)
+}
+
+/** List all surface IDs in a workspace. Defaults to the caller's workspace. */
+export function listAllSurfaceIds(workspace?: string): string[] {
+  return listSurfaces(workspace).map((s) => s.id)
+}
+
+/**
+ * Split relative to a specific surface and return the new surface ref.
+ * Always pass --surface so splits happen in the right place regardless of focus.
+ */
+export function splitSurface(
+  direction: 'right' | 'down' | 'left' | 'up' = 'right',
+  relativeTo?: string,
+): string {
+  const args = ['new-split', direction]
+  if (relativeTo) args.push('--surface', relativeTo)
+  // Output format: "OK surface:20 workspace:1"
+  const output = cmux(...args)
+  const match = output.match(/surface:\d+/)
+  if (!match) throw new Error(`Unexpected new-split output: ${output}`)
+  return match[0]
+}
+
+/** Close a surface by ref. */
+export function closeSurface(surfaceId: string): void {
+  try {
+    cmux('close-surface', '--surface', surfaceId)
+  } catch {
+    // surface may already be closed
+  }
+}
+
+/** Rename a surface's tab for identification. */
+export function renameSurface(surfaceId: string, title: string): void {
+  cmux('rename-tab', title, '--surface', surfaceId)
+}
+
+/** Get the current title of a surface. */
+export function getSurfaceTitle(surfaceId: string): string {
+  const surfaces = listSurfaces()
+  return surfaces.find((s) => s.id === surfaceId)?.title || ''
+}
+
+// ---------------------------------------------------------------------------
+// I/O
+// ---------------------------------------------------------------------------
+
+/** Send text to a surface (pastes the text). */
+export function sendText(surfaceId: string, text: string): void {
+  cmux('send', '--surface', surfaceId, text)
+}
+
+/** Send a key press to a surface. */
+export function sendKey(surfaceId: string, key: string): void {
+  cmux('send-key', '--surface', surfaceId, key)
+}
+
+/** Send text followed by Enter (like typing a command). */
+export function sendCommand(surfaceId: string, text: string): void {
+  sendText(surfaceId, text)
+  sendKey(surfaceId, 'Return')
+}
+
+/** Read the screen content of a surface. */
+export function readScreen(surfaceId: string, lines?: number): string {
+  const args = ['read-screen', '--surface', surfaceId]
+  if (lines) args.push('--lines', String(lines))
+  return cmux(...args)
+}
+
+// ---------------------------------------------------------------------------
+// Focus
+// ---------------------------------------------------------------------------
+
+/** Focus a surface. */
+export function focusSurface(surfaceId: string): void {
+  const panes = cmux('list-panes')
+  for (const line of panes.split('\n').filter(Boolean)) {
+    const paneMatch = line.match(/^[*\s]*(pane:\d+)/)
+    if (!paneMatch) continue
+    const paneSurfaces = cmux('list-pane-surfaces', '--pane', paneMatch[1])
+    if (paneSurfaces.includes(surfaceId)) {
+      cmux('focus-pane', '--pane', paneMatch[1])
+      return
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Grid builder
+// ---------------------------------------------------------------------------
+
+/**
+ * Build a grid layout using iterative splits.
+ *
+ * All splits use explicit --surface targeting so they work regardless
+ * of what the user has focused. No focus changes needed.
+ *
+ * Returns the surface refs of the created worker panes.
+ */
+export function buildGrid(
+  leadSurface: string,
+  workerCount: number,
+  conf: LayoutConf,
+): string[] {
+  const { cols, rows } = computeGrid(workerCount, conf)
+  const isHorizontal = conf.lead.position === 'left' || conf.lead.position === 'right'
+  const workerSurfaces: string[] = []
+
+  const firstSplitDir = isHorizontal
+    ? (conf.lead.position === 'left' ? 'right' : 'left')
+    : (conf.lead.position === 'top' ? 'down' : 'up')
+
+  // First worker: split relative to the lead surface
+  const firstWorker = splitSurface(firstSplitDir as 'right' | 'down' | 'left' | 'up', leadSurface)
+  workerSurfaces.push(firstWorker)
+  Bun.sleepSync(100)
+
+  if (workerCount <= 1) return workerSurfaces
+
+  const colDir = isHorizontal ? 'down' : 'right'
+  const rowDir = isHorizontal ? 'right' : 'down'
+  let created = 1
+
+  // Build columns in row 0 — each splits relative to the previous worker
+  for (let c = 1; c < cols && created < workerCount; c++) {
+    const s = splitSurface(rowDir as 'right' | 'down', workerSurfaces[workerSurfaces.length - 1])
+    workerSurfaces.push(s)
+    created++
+    Bun.sleepSync(100)
+  }
+
+  // Add additional rows by splitting column panes downward
+  for (let r = 1; r < rows && created < workerCount; r++) {
+    for (let c = 0; c < cols && created < workerCount; c++) {
+      const splitTarget = workerSurfaces[c + (r - 1) * cols]
+      if (splitTarget) {
+        const s = splitSurface(colDir as 'right' | 'down', splitTarget)
+        workerSurfaces.push(s)
+        created++
+        Bun.sleepSync(100)
+      }
+    }
+  }
+
+  return workerSurfaces
+}

package/src/lib/env.ts

@@ -43,3 +43,8 @@ export function detectTerminal(): string {
 export function inGhostty(): boolean {
   return detectTerminal() === 'ghostty' && !inTmux()
 }
+
+/** Check if we're inside a cmux terminal. */
+export function inCmux(): boolean {
+  return !!process.env.CMUX_WORKSPACE_ID
+}

package/src/lib/mirror.ts

@@ -18,7 +18,7 @@
 import { execFileSync } from 'node:child_process'
 import { readdirSync, statSync } from 'node:fs'
 import { join } from 'node:path'
-import { splitTerminal, sendCommand } from './ghostty'
+import { splitTerminal, sendCommand as ghosttySendCommand } from './ghostty'
 
 /** Run a tmux command on a specific socket (or default). */
 function tmuxSocket(args: string[], socket?: string): string {
@@ -141,9 +141,51 @@ export function mirrorSingleWorker(
   Bun.sleepSync(300)
 
   // Attach to the view session via the custom socket
-  sendCommand(newTermId, `tmux -L ${socket} attach -t ${viewName}`)
+  ghosttySendCommand(newTermId, `tmux -L ${socket} attach -t ${viewName}`)
   Bun.sleepSync(200)
 
   console.log(`  [mirror] ${windowName} (${paneId}) → ghostty:${newTermId}`)
   return { ghosttyTerminal: newTermId, viewSession: viewName }
 }
+
+/**
+ * Mirror a single tmux worker pane into a cmux split.
+ * Same approach as Ghostty mirroring but uses cmux CLI for splits.
+ */
+export function mirrorWorkerToCmux(
+  socket: string,
+  session: string,
+  paneId: string,
+  index: number,
+  splitTarget: string,
+  splitDirection: 'right' | 'down',
+): { cmuxSurface: string; viewSession: string } {
+  const { splitSurface, sendCommand: cmuxSendCommand } = require('./cmux')
+
+  const windowName = `worker-${index + 1}`
+  const viewName = `view-${index + 1}`
+
+  // Break pane into its own tmux window
+  try {
+    tmuxSocket(['break-pane', '-s', paneId, '-d', '-n', windowName], socket)
+  } catch (e: any) {
+    console.error(`  [mirror] break-pane ${paneId}: ${e.message}`)
+  }
+
+  // Create a session group member pointing at the worker's window
+  try { tmuxSocket(['kill-session', '-t', viewName], socket) } catch {}
+  tmuxSocket(['new-session', '-d', '-t', session, '-s', viewName], socket)
+  tmuxSocket(['set-option', '-t', viewName, 'status', 'off'], socket)
+  tmuxSocket(['select-window', '-t', `${viewName}:${windowName}`], socket)
+
+  // Create cmux split relative to the target surface
+  const newSurface = splitSurface(splitDirection, splitTarget)
+  Bun.sleepSync(300)
+
+  // Attach to the view session via the custom socket
+  cmuxSendCommand(newSurface, `tmux -L ${socket} attach -t ${viewName}`)
+  Bun.sleepSync(200)
+
+  console.log(`  [mirror] ${windowName} (${paneId}) → cmux:${newSurface}`)
+  return { cmuxSurface: newSurface, viewSession: viewName }
+}

package/src/lib/panes.ts

@@ -8,7 +8,8 @@ export interface PaneRecord {
   windowId: string
   workers: Array<{ name: string; paneId: string; color: string }>
   createdAt: number
-  backend?: 'tmux' | 'ghostty'
+  backend?: 'tmux' | 'ghostty' | 'cmux'
+  leadOriginalTitle?: string
 }
 
 function panePath(teamName: string): string {
@@ -34,6 +35,18 @@ export function isTeamAlive(teamName: string): boolean {
   try {
     const cruPanes = loadPanes(teamName)
 
+    // For cmux-tracked teams, check via cmux CLI
+    if (cruPanes?.backend === 'cmux') {
+      try {
+        const { listAllSurfaceIds } = require('./cmux')
+        const allSurfaces = new Set(listAllSurfaceIds())
+        return cruPanes.workers.some((w) => allSurfaces.has(w.paneId))
+      } catch (e) {
+        console.warn(`[isTeamAlive] failed to query cmux for team "${teamName}": ${e}`)
+        return false
+      }
+    }
+
     // For ghostty-tracked teams, check via AppleScript
     if (cruPanes?.backend === 'ghostty') {
       try {

package/src/lib/preflight.ts

@@ -1,4 +1,4 @@
-import { hasBinary, inTmux, inGhostty, detectTerminal } from './env'
+import { hasBinary, inTmux, inGhostty, inCmux, detectTerminal } from './env'
 
 const INSTALL_HINTS: Record<string, Record<string, string>> = {
   tmux: {
@@ -59,7 +59,16 @@ export function preflight(...checks: Check[]): { ok: boolean; errors: PreflightE
         break
 
       case 'pane-session':
-        if (inGhostty()) {
+        if (inCmux()) {
+          try {
+            const { isCmuxAvailable } = require('./cmux')
+            if (!isCmuxAvailable()) {
+              errors.push({ check: 'pane-session', message: 'cmux socket is not responding. Is cmux running?' })
+            }
+          } catch {
+            errors.push({ check: 'pane-session', message: 'Cannot connect to cmux socket' })
+          }
+        } else if (inGhostty()) {
           if (process.platform !== 'darwin') {
             errors.push({ check: 'pane-session', message: 'Ghostty AppleScript is only available on macOS' })
           } else {
@@ -73,9 +82,9 @@ export function preflight(...checks: Check[]): { ok: boolean; errors: PreflightE
             }
           }
         } else if (!hasBinary('tmux')) {
-          errors.push({ check: 'pane-session', message: 'tmux is not installed (or use Ghostty for native pane support)', hint: platformHint('tmux') })
+          errors.push({ check: 'pane-session', message: 'tmux is not installed (or use Ghostty/cmux for native pane support)', hint: platformHint('tmux') })
         } else if (!inTmux()) {
-          errors.push({ check: 'pane-session', message: 'Not inside a tmux session (or use Ghostty for native pane support)', hint: tmuxCmd })
+          errors.push({ check: 'pane-session', message: 'Not inside a tmux session (or use Ghostty/cmux for native pane support)', hint: tmuxCmd })
         }
         break