[BUG] Fullscreen renderer (CLAUDE_CODE_NO_FLICKER=1) suspends with SIGTTIN on launch in iTerm2 3.6.1164; mouse tracking leaks into shell (works in Ghostty)

[nozikov]

What's Wrong?

Summary: With the fullscreen renderer active (CLAUDE_CODE_NO_FLICKER=1), Claude Code loses the TTY foreground process group immediately after rendering the welcome banner and gets suspended by the shell with zsh: suspended (tty input) (SIGTTIN). Mouse tracking and terminal queries are not cleaned up, so after the suspend the shell is flooded with mouse-tracking escape reports (35;20;10M...) and the terminal's Primary Device Attributes response (>|iTerm2 3.6.1164;1;2;4;6;17;18;21;22;52c) leaks into the prompt.

The same failure occurs on the fullscreen-renderer promo prompt path: with settings.json removed entirely, Claude Code shows "Try the new fullscreen renderer?" and suspends at that prompt the same way. So both entry points into the fullscreen code path are affected.

The identical setup works perfectly in Ghostty. Only iTerm2 is affected.

Environment

• Claude Code: 2.1.217 (native install), commit 9963b018d22c
• Platform: darwin-arm64 (macOS, Apple Silicon)
• Terminal: iTerm2 3.6.1164
• Shell: zsh + starship prompt (no oh-my-zsh framework; cross-terminal .zshrc shared with Ghostty, where everything works)
• Auth: Claude Max (claude.ai OAuth)
• claude doctor: "No installation issues found"

Steps to Reproduce

1. iTerm2 3.6.1164 on macOS (Apple Silicon), zsh.
2. ~/.claude/settings.json containing "env": { "CLAUDE_CODE_NO_FLICKER": "1" }.
3. Run claude in any directory (reproduces in project dirs and in /tmp).
4. Welcome banner renders, then immediately: zsh: suspended (tty input) claude.
5. Shell prompt returns with mouse tracking still enabled — moving the mouse spews 35;x;yM sequences; the DA response >|iTerm2 3.6.1164;...c appears at the prompt.

Variant B (promo prompt path):

1. Remove/rename ~/.claude/settings.json.
2. Run claude — the "Try the new fullscreen renderer?" prompt renders.
3. Process suspends with zsh: suspended (tty input) at that prompt. Same escape-sequence leakage afterward.

What I ruled out

• Project state: reproduces in /tmp with no project files. Largest per-session .jsonl files are ~14 MB (no oversized session files).
• User settings/plugins: reproduces with ~/.claude/settings.json removed (variant B above).
• The binary itself / global environment: the exact same binary, shell config, and settings work flawlessly in Ghostty — including the fullscreen renderer.

Expected Behavior

claude starts the interactive TUI in the foreground in iTerm2, as it does in Ghostty. If startup fails, terminal state (mouse tracking, alternate screen, pending queries) should be restored/consumed so escape sequences don't leak into the shell.

Workaround

Removing CLAUDE_CODE_NO_FLICKER and setting "tui": "default" in ~/.claude/settings.json avoids the fullscreen code path; Claude Code then starts normally in iTerm2. Alternatively, using Ghostty works with fullscreen enabled.

Notes

Possibly related to #11898 (CLI suspends / raw mode failures in iTerm2) — same SIGTTIN symptom, but here it is deterministically gated on the fullscreen renderer code path and is 100% reproducible on this setup.

[IsabelaValls14]

Adding another data point: this also reproduces without CLAUDE_CODE_NO_FLICKER set, and in the VS Code integrated terminal rather than iTerm2 — so it doesn't look specific to that flag or terminal.

Environment

• macOS (Darwin 25.5.0, arm64)
• Claude Code 2.1.219 (native install)
• VS Code integrated terminal, zsh; also seen intermittently in Terminal.app

Symptoms

• claude suspends with SIGTTIN right at startup: [1] + suspended (tty input) claude
• SGR mouse-tracking sequences leak into the shell afterwards — keystrokes render as escape-code garbage until a stty sane + printf '\e[?1000l\e[?1002l\e[?1003l\e[?1006l\e[?1049l\e[?2004l' reset
• fg brings the session back (we've automated this with a zsh precmd hook that detects (tty input) claude jobs and resumes them), but the redraw is garbled and the suspension keeps recurring across sessions and reboots

This was originally reported in #47382 (SIGTTIN after a Bash-tool child exits), which was auto-closed as stale without a fix; #11898 and #11439 look like the same underlying foreground-process-group loss. Happy to provide more diagnostics if useful.

[bcherny]

Thanks for the detailed report. I tried to reproduce this on the released 2.1.233 build on macOS (Apple Silicon): started claude with CLAUDE_CODE_NO_FLICKER=1 from an interactive zsh in /tmp, in tmux. The fullscreen UI came up, accepted input, and exited cleanly — no suspended (tty input), and no mouse-tracking sequences leaked to the shell afterwards. I don't have a way to drive iTerm2 3.6.1164 directly here, so I couldn't test that terminal specifically.

suspended (tty input) means the shell moved Claude Code out of the terminal's foreground while it was reading input, which is usually caused by something between the shell and the process rather than by Claude Code itself. To narrow it down, could you share:

1. Whether it still happens on the latest version (2.1.233 or newer), and the output of claude doctor.
2. Whether it reproduces with iTerm2's Shell Integration disabled, and with a bare shell (zsh -f, then run claude) so starship and your .zshrc are out of the picture.
3. Whether iTerm2's tmux integration (tmux -CC) or any precmd/preexec hooks are active in that session.
4. A debug log: run claude --debug-file /tmp/claude-debug.txt, reproduce, and attach the file (redact anything sensitive).

With that we can figure out what is taking the terminal away from the process, and also make sure mouse tracking is cleaned up if it happens.

🤖 Generated with Claude Code

[github-actions]

We weren't able to reproduce this. Could you provide steps to trigger the issue — what you ran, what happened, and what you expected? This issue will be closed automatically if there's no activity within 7 days.