iTerm2: CLI launches as daemon child session, blocking Agents panel / session switching

Status Open

Reported on v2.1.201

Maintainer reply ✓ Yes — bcherny

Activity 3 comments · opened Jul 6, 2026

💡 Likely answer: A maintainer (bcherny, collaborator) responded on this thread — see the highlighted reply below.

Description

On iTerm2 (macOS), running claude starts the process routed through the background daemon as a child session (CLAUDE_CODE_CHILD_SESSION=1), even for a normal top-level terminal launch. This blocks the Agents panel and session switching.

Steps to reproduce

Open iTerm2, run claude in a new session.
Try to open the Agents panel / switch sessions (left-arrow in session picker).
Error: Cannot open agents — session persistence is disabled, so this conversation cannot be backgrounded.

Observed

echo $CLAUDE_CODE_CHILD_SESSION → 1
echo $CLAUDE_JOB_DIR → /Users/<user>/.claude/jobs/<id>
ps -e | grep claude shows a persistent claude daemon run --origin transient --spawned-by {...} process, and the current session's claude process appears spawned under --bg-pty-host / --bg-spare daemon plumbing rather than as a standalone top-level process.
No shell alias/function wraps claude — type claude resolves directly to /Users/<user>/.local/bin/claude.
No custom iTerm2 profile startup command is set.

Expected

A plain claude launch in iTerm2 should be a normal top-level session with Agents panel and session-switching available, matching behavior in VS Code's integrated terminal (where this works correctly).

Environment

Claude Code version: 2.1.201 (up to date via claude update)
Terminal: iTerm2
OS: macOS (Darwin 25.5.0)
Install method: native
Works correctly in: VS Code integrated terminal (same machine, same account)

Additional notes

Also observed a separate always-running daemon process spawned with --spawned-by {"label":"claude","cwd":"...","pid":...} with --origin transient, which may be related to how sessions get bound as children.

View original on GitHub ↗

3 Comments

biokraft · 1 month ago

Additional environment detail: this iTerm2 setup also has Starship prompt installed, plus a custom Rust binary cship wired in as Claude Code's statusLine command (~/.claude/settings.json → statusLine.command: "cship"). Neither appeared to directly launch/wrap claude (no shell alias/function override — type claude resolves straight to the real binary), but flagging both since they run in the same shell/session context and could interact with terminal detection or the daemon handshake.

biokraft · 1 month ago

Fixed this btw by reinstalling iTerm 🤷

bcherny collaborator · 14 days ago

Thanks for the detailed report — and glad the iTerm reinstall sorted it. Your own observation explains it: echo $CLAUDE_CODE_CHILD_SESSION printed 1 in a plain iTerm2 shell. Claude Code sets that variable only in processes it launches itself; when it shows up in a fresh terminal tab it means the terminal app (or its login shell) inherited it — typically because iTerm2 was started or restarted from inside a Claude Code session. Every new tab then carries the marker, and Claude Code treats those sessions as nested: no transcript is saved, so they can't be backgrounded and the Agents panel / session switching aren't offered. Reinstalling relaunched iTerm2 with a clean environment, which is why it went away. VS Code's terminal worked because VS Code wasn't launched that way. The claude daemon run --origin transient process is normal and unrelated.

I tried this on 2.1.233: launching claude with CLAUDE_CODE_CHILD_SESSION=1 in the environment shows a footer warning (Transcript saving is off — inherited CLAUDE_CODE_CHILD_SESSION marker · restart with CLAUDE_CODE_FORCE_SESSION_PERSISTENCE=1 ...) and no longer advertises the ← agents shortcut, so the situation is now explained instead of silently failing (that warning shipped in 2.1.217). Without the marker, ← opens the Agents panel as expected.

If it ever recurs: unset the variable in that terminal (or relaunch the app), or set CLAUDE_CODE_FORCE_SESSION_PERSISTENCE=1. Docs: https://code.claude.com/docs/en/env-vars (see CLAUDE_CODE_CHILD_SESSION and CLAUDE_CODE_FORCE_SESSION_PERSISTENCE). Closing since it's resolved and the confusing part has been improved — reply to reopen.

🤖 Generated with Claude Code