[BUG] remote-control rejects all of its own flags when any global flag precedes the subcommand

Status Open
Reported on v2.1.241
Maintainer reply None cached
Activity 0 comments · opened Aug 23, 2026

Preflight Checklist

  • [x] I have searched existing issues and this hasn't been reported yet
  • [x] This is a single bug report
  • [x] I am using the latest version of Claude Code

What's Wrong?

claude remote-control parses its flags in bridgeMain via process.argv.slice(3), which hardcodes the subcommand at argv[2]. Any global flag before it shifts the window, and every documented flag (--name, --spawn, --capacity, --session-id, --continue, --sandbox, --verbose) fails as an unknown option.

The cli.tsx fast path checks args[0] === 'remote-control'. A preceding global flag makes that check miss, and execution falls into the Commander action whose own comment says it is unreachable:

r.command("remote-control", { hidden: true }).alias("rc")
 .action(async () => { await bridgeMain(process.argv.slice(3)) })

No wrapper is required to trigger this. It reproduces on a stock install.

What Should Happen?

The flags parse regardless of what precedes the subcommand. Pass Commander's own cmd.args instead of slicing process.argv by index.

Steps to Reproduce

  1. Install Claude Code 2.1.241, no wrapper, no shim.
  2. Run claude remote-control --spawn bogus. The parser is reached and answers with its own validation message:

``
Error: --spawn requires one of: session, same-dir, worktree (got: bogus)
``

  1. Run the same command with any global flag first, claude --debug remote-control --spawn bogus. The parser is never reached:

``
error: unknown option '--spawn'
``

  1. Same result for --verbose, --dangerously-load-development-channels, or any other global flag.

Wrappers that inject a global flag hit this on every invocation with no way to avoid it: cmux (--session-id), home-manager's programs.claude-code (--plugin-dir, added whenever mcpServers is set).

Error Messages/Logs

error: unknown option '--spawn'

With -- to force passthrough, the shifted argv leaks the injected value:

$ claude remote-control -- --spawn worktree
Error: Unknown argument: /nix/store/...-claude-code-hm-plugin

Is this a regression?

No, this never worked.

Claude Code Version

2.1.241 (Claude Code). Also reproduced on 2.1.240.

Platform

Anthropic API

Operating System

Other Linux (NixOS, x86_64)

Terminal/Shell

Other (Ghostty, fish)

Additional Information

This has been reported three times and closed three times without the code path being touched. All three are locked.

  • #35894 was diagnosed as the cmux wrapper injecting --session-id, and closed once cmux added remote-control to its own passthrough list. That fixed cmux's symptom, not the bug. Claude Code was never changed, so every other wrapper and any user typing a global flag still hits it. It was later auto-closed as NOT_PLANNED for inactivity.
  • #42485 carried the correct root-cause trace, including the slice(3) line and the unreachable-fallback comment. A duplicate-detection bot closed it against #35894 fifteen minutes after filing, before a maintainer read it. Because #35894's resolution was a third-party patch, closing #42485 against it left the real defect untouched.
  • #36897 is the same failure reached through --dangerously-load-development-channels, also closed.

The common thread is that each report was attributed to whichever wrapper the reporter happened to use, so the shared cause was never treated as a Claude Code bug. Step 3 above removes wrappers from the argument entirely.

View original on GitHub ↗