[BUG] remote-control: QR code not displayed on headless/non-GUI systems

[ofergr]

Preflight Checklist

• I have searched existing issues and this hasn't been reported yet
• This is a single bug report (please file separate reports for different bugs)
• I am using the latest version of Claude Code

What's Wrong?

On headless systems, running claude remote-control only outputs the session URL — no QR code is shown.

Expected: QR codes can be rendered with ASCII/Unicode block characters (█ ▀ ▄) in any terminal,
including headless. Many CLI tools do this already (e.g. qrencode -t ansiutf8,
or the npm qrcode package with toString({type: 'terminal'})).
Should always render ASCII QR, no GUI required.

Current: QR silently skipped on headless systems, requiring manual URL copy/transfer to mobile.

Steps to reproduce:

1. Run claude remote-control on headless Linux (no display server)
2. Only URL is printed, no QR code

Version: 2.1.76, Linux headless

What Should Happen?

Expected: QR codes can be rendered with ASCII/Unicode block characters (█ ▀ ▄) in any terminal,

Error Messages/Logs

no errors. only URL is presented

Steps to Reproduce

Use a headless system.
Run /remote-control

Claude Model

None

Is this a regression?

No, this never worked

Last Working Version

No response

Claude Code Version

2.1.76

Platform

Anthropic API

Operating System

Ubuntu/Debian Linux

Terminal/Shell

Xterm

Additional Information

No response

[github-actions]

Found 3 possible duplicate issues:

1. Feature Request: claude remote-control --headless — daemonizable remote control without TTY dependency #30447
2. Feature: headless mode for remote-control (--headless/--daemon flag) #29116
3. [BUG] claude remote-control works locally but fails in SSH environment for Max subscriber #28845

This issue will be automatically closed as a duplicate in 3 days.

• If your issue is a duplicate, please close it and 👍 the existing issue instead
• To prevent auto-closure, add a comment or 👎 this comment

🤖 Generated with Claude Code

[ofergr]

Those issues do not address my problem at all. My session keeps living. I just need a QR presented on my headless server to scan it with my iPhone. TTY terminals can generate QR using ASCII or unicode symbols

[nathanschram]

I tried reproducing this on a headless Linux VPS (no GUI, no DISPLAY) and from what I can tell the QR code itself does work on headless - it renders using Unicode half-block characters in the terminal. But it's not shown by default.

In the current version (2.1.76), the QR code is hidden behind a spacebar toggle - you should see a "space to show QR code" hint at the bottom of the remote-control screen. Pressing space toggles a scannable QR code made of Unicode block characters (works in any terminal with UTF-8 support).

The catch is that the spacebar toggle only works if you're running in an interactive terminal with a TTY. A couple of things worth checking on your end:

1. Are you running claude remote-control inside tmux/screen, or directly in an SSH session with ssh -t (which allocates a TTY)? If you're running it via something like nohup, ssh host 'claude remote-control' without -t, or piping the output, the interactive key handler won't pick up the spacebar press.

2. If you are in an interactive terminal and pressing space doesn't do anything - could you share what echo $TERM and locale return? Some terminal configurations (particularly TERM=dumb) might cause the UI to fall back to a simpler renderer.

In the meantime, the text URL that's always displayed (https://claude.ai/code?bridge=...) should work for connecting - you can open it on your phone's browser directly, though I appreciate that's less convenient than scanning a QR.

I do think your broader point is valid though - for headless use cases, something like a --show-qr flag that displays the QR automatically on startup (without needing the spacebar toggle) would be a nice improvement. The spacebar toggle is a bit easy to miss.

[ofergr]

Hi and thanks for the reply.
Indeed, I use Claude via SSH (wrapped in MobaXterm), and there is no space toggle. I will have to live with copy-paste the link :)
Ofer

[slyapustin]

QR code in terminal is broken on MacOS default terminal app.

[ofergr]

QR code in terminal is broken on MacOS default terminal app.

In my case, it is a headless Linux over SSH. On my personal Mac, it works great.

[jiminseong]

I experienced the same issue, and when I entered /remote-control again while remote-control was already active, an option called Show QR code appeared.

[github-actions]

This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.