Yeachan-Heo/oh-my-codex · error · Error

Team mode requires running inside tmux current leader pane

Error message

Team mode requires running inside tmux current leader pane

What it means

Thrown during team mode startup when the launch mode is 'interactive' but the current process is not running inside a tmux pane with a current client context (i.e., $TMUX_PANE/TMUX environment is absent). The runtime requires a tmux leader pane to spawn and manage worker panes, so it refuses to start outside tmux.

Source

Thrown at src/team/runtime.ts:3516

  });
  for (const workerLaunchPolicy of workerLaunchPolicyPlan) {
    assertTeamWorkerCliPolicyCompatibility(
      workerLaunchPolicy.workerCli,
      [...workerLaunchPolicy.workerLaunchArgs],
    );
  }
  if (workerLaunchMode === 'prompt') {
    assertPromptModeWorkerCliSupported(
      workerLaunchPolicyPlan.map((workerLaunchPolicy) => workerLaunchPolicy.workerCli),
      launchEnv,
    );
  }
  if (workerLaunchMode === 'interactive') {
    if (!isTmuxAvailable()) {
      throw new Error('Team mode requires tmux. Install with: apt install tmux / brew install tmux');
    }
    if (!hasCurrentTmuxClientContext()) {
      throw new Error('Team mode requires running inside tmux current leader pane');
    }
  }

  await detectAndCleanStaleTeam(sanitized, leaderCwd, workerCount, options.confirmStaleCleanup);

  if (activeWorktreeMode) {
    for (let i = 1; i <= workerCount; i++) {
      const workerName = `worker-${i}`;
      const planned = planWorktreeTarget({
        cwd: leaderCwd,
        scope: 'team',
        mode: effectiveWorktreeMode,
        teamName: sanitized,
        workerName,
      });
      const ensured = ensureWorktree(planned);
      provisionedWorktrees.push(ensured);
      if (ensured.enabled) {

View on GitHub (pinned to 3ad79a8a6f)

Solutions

1. Start or attach a tmux session first (tmux new -s team or tmux attach) and rerun the command from inside it
2. Verify TMUX and TMUX_PANE environment variables are set in the shell (echo $TMUX $TMUX_PANE)
3. If running headless/CI, use a detached/non-interactive worker launch mode instead of 'interactive'
4. Ensure tmux is installed and on PATH if isTmuxAvailable() also fails

Example fix

// before
await startTeam({ workerLaunchMode: 'interactive', ... }); // run from plain shell
// after
// $ tmux new -s team
await startTeam({ workerLaunchMode: 'interactive', ... }); // run inside tmux pane

import { isTmuxAvailable, hasCurrentTmuxClientContext } from './team/tmux';
function canRunInteractiveTeam(): boolean {
  return isTmuxAvailable() && hasCurrentTmuxClientContext();
}
if (workerLaunchMode === 'interactive' && !canRunInteractiveTeam()) {
  workerLaunchMode = 'detached'; // or abort with a friendly message
}

const isInteractiveTmuxReady = (): boolean =>
  Boolean(process.env.TMUX && process.env.TMUX_PANE);

When it happens

Trigger: Calling the team startup API with workerLaunchMode 'interactive' while isTmuxAvailable() is true but hasCurrentTmuxClientContext() returns false — e.g., running from a plain shell, an SSH session without tmux attached, or a tmux session where the client context cannot be resolved.

Common situations: Running the team command directly in a terminal instead of inside tmux; tmux installed but session not attached/detached with no current client; CI or scripts that set workerLaunchMode to interactive; running from a subshell that strips TMUX env vars.

Related errors

• [sparkshell] raw fallback failed: executable not found (${in
• tmux is unavailable; omx question requires tmux for OMX-owne
• omx question cannot open a visible renderer because this pro
• startup_worker_pane_pid_unavailable:${paneId}
• tmux_session_query_unavailable

AI-assisted analysis of Yeachan-Heo/oh-my-codex@3ad79a8a6f (2026-08-27). Data as JSON: /api/errors/dec5f0958e4528a0. Report an issue: GitHub.