Yeachan-Heo/oh-my-codex · error

--tmux-pane requires a pane id. ${SPARKSHELL_USAGE}

Error message

--tmux-pane requires a pane id.
${SPARKSHELL_USAGE}

What it means

The sparkshell CLI was invoked in tmux-pane mode (--tmux-pane) but the flag was not followed by a pane id: either it was the last token or the next token looked like another option. The parser guards this invariant before building the tmux capture-pane argv.

Source

Thrown at src/cli/sparkshell.ts:332

    if (!script.trim()) throw new Error(`--shell requires a command string.\n${SPARKSHELL_USAGE}`);
    if (args.length !== 1) throw new Error(`--shell does not accept additional arguments.\n${SPARKSHELL_USAGE}`);
    return { kind: 'command', argv: resolveFallbackShellArgv(script, options) };
  }

  const paneStart = args.findIndex((arg) => arg === '--tmux-pane' || arg.startsWith('--tmux-pane='));
  if (paneStart < 0) {
    return { kind: 'command', argv: [...args] };
  }

  let paneId: string | undefined;
  let tailLines = 200;
  let sawTailLines = false;

  for (let index = 0; index < args.length; index += 1) {
    const token = args[index];
    if (token === '--tmux-pane') {
      const next = args[index + 1];
      if (!next || next.startsWith('-')) throw new Error(`--tmux-pane requires a pane id.\n${SPARKSHELL_USAGE}`);
      paneId = next;
      index += 1;
      continue;
    }
    if (token.startsWith('--tmux-pane=')) {
      const value = token.slice('--tmux-pane='.length).trim();
      if (!value) throw new Error(`--tmux-pane requires a pane id.\n${SPARKSHELL_USAGE}`);
      paneId = value;
      continue;
    }
    if (token === '--tail-lines') {
      const next = args[index + 1];
      if (!next || next.startsWith('-')) throw new Error(`--tail-lines requires a numeric value.\n${SPARKSHELL_USAGE}`);
      const parsed = Number.parseInt(next, 10);
      if (!Number.isFinite(parsed) || parsed < 100 || parsed > 1000) {
        throw new Error(`--tail-lines must be an integer between 100 and 1000.\n${SPARKSHELL_USAGE}`);
      }
      tailLines = parsed;

View on GitHub (pinned to 3ad79a8a6f)

Solutions

1. Supply a pane id: `sparkshell --tmux-pane 3`
2. Use the equals form: `sparkshell --tmux-pane=3`
3. Get valid ids via `tmux list-panes -F '#{pane_id}'`

Example fix

# before
sparkshell --tmux-pane --tail-lines 200
# after
sparkshell --tmux-pane %1 --tail-lines 200

const ok = (args: string[]) =>
  !args.includes('--tmux-pane') ||
  args.some((a, i) => (a === '--tmux-pane' && args[i+1] && !args[i+1].startsWith('-')) || a.startsWith('--tmux-pane=') && a.length > '--tmux-pane='.length);

When it happens

Trigger: Running `sparkshell --tmux-pane` with no argument, or `sparkshell --tmux-pane --tail-lines 200` where the next token starts with '-'.

Common situations: Shell quoting mistakes, forgetting to run `tmux list-panes` to get the pane id first, or writing flags in an order that puts another option right after --tmux-pane.

Understand the failure class

Background: "no subcommand specified" and "... is required": CLI errors when a required argument is missing — this error's family across 13 libraries.

Related errors

• --tail-lines requires a numeric value. ${SPARKSHELL_USAGE}
• tmux pane mode does not accept an additional command. ${SPAR
• --keep-policy must be one of: score_improvement, pass_only
• Unknown capabilities subcommand: ${parsed.subcommand}
• Unknown capabilities option: ${arg}

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