{"record":{"id":"dec5f0958e4528a0","repo":"Yeachan-Heo/oh-my-codex","slug":"team-mode-requires-running-inside-tmux-current-lea","errorCode":null,"errorMessage":"Team mode requires running inside tmux current leader pane","messagePattern":"Team mode requires running inside tmux current leader pane","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"src/team/runtime.ts","lineNumber":3516,"sourceCode":"  });\n  for (const workerLaunchPolicy of workerLaunchPolicyPlan) {\n    assertTeamWorkerCliPolicyCompatibility(\n      workerLaunchPolicy.workerCli,\n      [...workerLaunchPolicy.workerLaunchArgs],\n    );\n  }\n  if (workerLaunchMode === 'prompt') {\n    assertPromptModeWorkerCliSupported(\n      workerLaunchPolicyPlan.map((workerLaunchPolicy) => workerLaunchPolicy.workerCli),\n      launchEnv,\n    );\n  }\n  if (workerLaunchMode === 'interactive') {\n    if (!isTmuxAvailable()) {\n      throw new Error('Team mode requires tmux. Install with: apt install tmux / brew install tmux');\n    }\n    if (!hasCurrentTmuxClientContext()) {\n      throw new Error('Team mode requires running inside tmux current leader pane');\n    }\n  }\n\n  await detectAndCleanStaleTeam(sanitized, leaderCwd, workerCount, options.confirmStaleCleanup);\n\n  if (activeWorktreeMode) {\n    for (let i = 1; i <= workerCount; i++) {\n      const workerName = `worker-${i}`;\n      const planned = planWorktreeTarget({\n        cwd: leaderCwd,\n        scope: 'team',\n        mode: effectiveWorktreeMode,\n        teamName: sanitized,\n        workerName,\n      });\n      const ensured = ensureWorktree(planned);\n      provisionedWorktrees.push(ensured);\n      if (ensured.enabled) {","sourceCodeStart":3498,"sourceCodeEnd":3534,"githubUrl":"https://github.com/Yeachan-Heo/oh-my-codex/blob/3ad79a8a6fe6e95fdbb8c00e40716fffe4011ce2/src/team/runtime.ts#L3498-L3534","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Start or attach a tmux session first (tmux new -s team or tmux attach) and rerun the command from inside it","Verify TMUX and TMUX_PANE environment variables are set in the shell (echo $TMUX $TMUX_PANE)","If running headless/CI, use a detached/non-interactive worker launch mode instead of 'interactive'","Ensure tmux is installed and on PATH if isTmuxAvailable() also fails"],"exampleFix":"// before\nawait startTeam({ workerLaunchMode: 'interactive', ... }); // run from plain shell\n// after\n// $ tmux new -s team\nawait startTeam({ workerLaunchMode: 'interactive', ... }); // run inside tmux pane","handlingStrategy":"validation","validationCode":"import { isTmuxAvailable, hasCurrentTmuxClientContext } from './team/tmux';\nfunction canRunInteractiveTeam(): boolean {\n  return isTmuxAvailable() && hasCurrentTmuxClientContext();\n}\nif (workerLaunchMode === 'interactive' && !canRunInteractiveTeam()) {\n  workerLaunchMode = 'detached'; // or abort with a friendly message\n}","typeGuard":"const isInteractiveTmuxReady = (): boolean =>\n  Boolean(process.env.TMUX && process.env.TMUX_PANE);","tryCatchPattern":null,"preventionTips":["Always launch interactive team mode from inside an attached tmux session","Check $TMUX/$TMUX_PANE before invoking the team API","Fall back to detached mode in scripts/CI where no tmux client exists"],"tags":["tmux","team-mode","environment","interactive"],"backgroundTag":"missing-tmux-session-context","analyzedSha":"3ad79a8a6fe6e95fdbb8c00e40716fffe4011ce2","analyzedAt":"2026-08-27T22:18:39.783Z","schemaVersion":2},"datasetVersion":"2026-08-28T00:17:15.603Z"}