Merge pull request #1750 from Yeachan-Heo/fix/issue-1749-cmux-team-mode

fix(team): support cmux alongside tmux for team mode

Author: Yeachan-Heo

docs/REFERENCE.md

@@ -245,6 +245,11 @@ omc team api claim-task --input '{"team_name":"auth-review","task_id":"1","worke
 
 Supported entrypoints: direct start (`omc team [N:agent] "<task>"`), `status`, `shutdown`, and `api`.
 
+Topology behavior:
+- inside classic tmux (`$TMUX` set): reuse the current tmux surface for split-pane or `--new-window` layouts
+- inside cmux (`CMUX_SURFACE_ID` without `$TMUX`): launch a detached tmux session for team workers
+- plain terminal: launch a detached tmux session for team workers
+
 ### `omc session search`
 
 ```bash

skills/omc-teams/SKILL.md

@@ -36,7 +36,7 @@ Spawn N CLI worker processes in tmux panes to execute tasks in parallel. Support
 ## Requirements
 
 - **tmux binary** must be installed and discoverable (`command -v tmux`)
-- **Active tmux session** required to launch worker panes (`$TMUX` set, or start/attach tmux first)
+- **Classic tmux session optional** for in-place pane splitting (`$TMUX` set). Inside cmux or a plain terminal, `omc team` falls back to a detached tmux session instead of splitting the current surface.
 - **claude** CLI: `npm install -g @anthropic-ai/claude-code`
 - **codex** CLI: `npm install -g @openai/codex`
 - **gemini** CLI: `npm install -g @google/gemini-cli`
@@ -52,8 +52,10 @@ command -v tmux >/dev/null 2>&1
 ```
 
 - If this fails, report that **tmux is not installed** and stop.
-- If `tmux` exists but `$TMUX` is empty, report that the user is **not currently inside an active tmux session**. Do **not** say tmux is missing; tell them to start or attach tmux, then rerun.
-- If you need to confirm the active session, use:
+- If `$TMUX` is set, `omc team` can reuse the current tmux window/panes directly.
+- If `$TMUX` is empty but `CMUX_SURFACE_ID` is set, report that the user is running inside **cmux**. Do **not** say tmux is missing or that they are "not inside tmux"; `omc team` will launch a **detached tmux session** for workers instead of splitting the cmux surface.
+- If neither `$TMUX` nor `CMUX_SURFACE_ID` is set, report that the user is in a **plain terminal**. `omc team` can still launch a **detached tmux session**, but if they specifically want in-place pane/window topology they should start from a classic tmux session first.
+- If you need to confirm the active tmux session, use:
 
 ```bash
 tmux display-message -p '#S'
@@ -143,7 +145,8 @@ If encountered, switch to `omc team ...` CLI commands.
 
 | Error                        | Cause                               | Fix                                                                                 |
 | ---------------------------- | ----------------------------------- | ----------------------------------------------------------------------------------- |
-| `not inside tmux`            | Shell not running inside tmux       | Start tmux and rerun                                                                |
+| `not inside tmux`            | Requested in-place pane topology from a non-tmux surface | Start tmux and rerun, or let `omc team` use its detached-session fallback           |
+| `cmux surface detected`      | Running inside cmux without `$TMUX` | Use the normal `omc team ...` flow; OMC will launch a detached tmux session         |
 | `Unsupported agent type`     | Requested agent is not claude/codex/gemini | Use `claude`, `codex`, or `gemini`; for native Claude Code agents use `/oh-my-claudecode:team` |
 | `codex: command not found`   | Codex CLI not installed             | `npm install -g @openai/codex`                                                      |
 | `gemini: command not found`  | Gemini CLI not installed            | `npm install -g @google/gemini-cli`                                                 |

src/team/__tests__/tmux-session.create-team.test.ts

@@ -82,7 +82,34 @@ vi.mock('child_process', async (importOriginal) => {
   };
 });
 
-import { createTeamSession } from '../tmux-session.js';
+import { createTeamSession, detectTeamMultiplexerContext } from '../tmux-session.js';
+
+describe('detectTeamMultiplexerContext', () => {
+  afterEach(() => {
+    vi.unstubAllEnvs();
+  });
+
+  it('returns tmux when TMUX is present', () => {
+    vi.stubEnv('TMUX', '/tmp/tmux-1000/default,1,1');
+    vi.stubEnv('CMUX_SURFACE_ID', 'cmux-surface');
+
+    expect(detectTeamMultiplexerContext()).toBe('tmux');
+  });
+
+  it('returns cmux when CMUX_SURFACE_ID is present without TMUX', () => {
+    vi.stubEnv('TMUX', '');
+    vi.stubEnv('CMUX_SURFACE_ID', 'cmux-surface');
+
+    expect(detectTeamMultiplexerContext()).toBe('cmux');
+  });
+
+  it('returns none when neither tmux nor cmux markers are present', () => {
+    vi.stubEnv('TMUX', '');
+    vi.stubEnv('CMUX_SURFACE_ID', '');
+
+    expect(detectTeamMultiplexerContext()).toBe('none');
+  });
+});
 
 describe('createTeamSession context resolution', () => {
   beforeEach(() => {
@@ -98,6 +125,7 @@ describe('createTeamSession context resolution', () => {
   it('creates a detached session when running outside tmux', async () => {
     vi.stubEnv('TMUX', '');
     vi.stubEnv('TMUX_PANE', '');
+    vi.stubEnv('CMUX_SURFACE_ID', '');
 
     const session = await createTeamSession('race-team', 0, '/tmp');
 
@@ -111,6 +139,27 @@ describe('createTeamSession context resolution', () => {
     expect(session.sessionMode).toBe('detached-session');
   });
 
+  it('uses a detached tmux session when running inside cmux', async () => {
+    vi.stubEnv('TMUX', '');
+    vi.stubEnv('TMUX_PANE', '');
+    vi.stubEnv('CMUX_SURFACE_ID', 'cmux-surface');
+
+    const session = await createTeamSession('race-team', 1, '/tmp', { newWindow: true });
+
+    expect(mockedCalls.execFileArgs.some((args) => args[0] === 'new-window')).toBe(false);
+    const detachedCreateCall = mockedCalls.execFileArgs.find((args) =>
+      args[0] === 'new-session' && args.includes('-d') && args.includes('-P'),
+    );
+    expect(detachedCreateCall).toBeDefined();
+
+    const firstSplitCall = mockedCalls.execFileArgs.find((args) => args[0] === 'split-window');
+    expect(firstSplitCall).toEqual(expect.arrayContaining(['split-window', '-h', '-t', '%91']));
+    expect(session.leaderPaneId).toBe('%91');
+    expect(session.sessionName).toBe('omc-team-race-team-detached:0');
+    expect(session.workerPaneIds).toEqual(['%501']);
+    expect(session.sessionMode).toBe('detached-session');
+  });
+
   it('anchors context to TMUX_PANE to avoid focus races', async () => {
     vi.stubEnv('TMUX', '/tmp/tmux-1000/default,1,1');
     vi.stubEnv('TMUX_PANE', '%732');

src/team/tmux-session.ts

@@ -21,6 +21,16 @@ const TMUX_SESSION_PREFIX = 'omc-team';
 const promisifiedExec = promisify(exec);
 const promisifiedExecFile = promisify(execFile);
 
+export type TeamMultiplexerContext = 'tmux' | 'cmux' | 'none';
+
+export function detectTeamMultiplexerContext(
+  env: NodeJS.ProcessEnv = process.env,
+): TeamMultiplexerContext {
+  if (env.TMUX) return 'tmux';
+  if (env.CMUX_SURFACE_ID) return 'cmux';
+  return 'none';
+}
+
 /**
  * True when running on Windows under MSYS2/Git Bash.
  * Tmux panes run bash in this environment, not cmd.exe.
@@ -409,11 +419,15 @@ export function spawnBridgeInSession(
 /**
  * Create a tmux team topology for a team leader/worker layout.
  *
- * Must be run inside an existing tmux session ($TMUX must be set).
- * By default, creates splits in the CURRENT window so panes appear immediately
- * in the user's view. When options.newWindow is true, creates a detached
- * dedicated tmux window first and then splits worker panes there.
- * Returns sessionName in "session:window" form.
+ * When running inside a classic tmux session, creates splits in the CURRENT
+ * window so panes appear immediately in the user's view. When options.newWindow
+ * is true, creates a detached dedicated tmux window first and then splits worker
+ * panes there.
+ *
+ * When running inside cmux (CMUX_SURFACE_ID without TMUX) or a plain terminal,
+ * falls back to a detached tmux session because the current surface cannot be
+ * targeted as a normal tmux pane/window. Returns sessionName in "session:window"
+ * form.
  *
  * Layout: leader pane on the left, worker panes stacked vertically on the right.
  * IMPORTANT: Uses pane IDs (%N format) not pane indices for stable targeting.
@@ -428,7 +442,8 @@ export async function createTeamSession(
   const { promisify } = await import('util');
   const execFileAsync = promisify(execFile);
 
-  const inTmux = Boolean(process.env.TMUX);
+  const multiplexerContext = detectTeamMultiplexerContext();
+  const inTmux = multiplexerContext === 'tmux';
   const useDedicatedWindow = Boolean(options.newWindow && inTmux);
 
   // Prefer the invoking pane from environment to avoid focus races when users
@@ -441,7 +456,9 @@ export async function createTeamSession(
 
   if (!inTmux) {
     // Backward-compatible fallback: create an isolated detached tmux session
-    // so workflows can run when launched outside an attached tmux client.
+    // so workflows can run when launched outside an attached tmux client. This
+    // also covers cmux, which exposes its own surface metadata without a tmux
+    // pane/window that OMC can split directly.
     const detachedSessionName = `${TMUX_SESSION_PREFIX}-${sanitizeName(teamName)}-${Date.now().toString(36)}`;
     const detachedResult = await execFileAsync('tmux', [
       'new-session', '-d', '-P', '-F', '#S:0 #{pane_id}',