[BUG] Welcome screen flashes and collapses to the minimal header once a project has a CLAUDE.md — driven by a sticky hasCompletedProjectOnboarding flag

[BUG] Welcome screen flashes and collapses to the minimal header once a project has a CLAUDE.md — driven by a sticky hasCompletedProjectOnboarding flag

Summary

The full welcome screen (banner + "Recent activity"/"Tips" + "What's new") renders for ~0.1s on startup and then immediately collapses to the minimal one-line header. After isolating it, the trigger is not terminal size, MCP servers, project settings, the render race alone, or session count. It is the per-project hasCompletedProjectOnboarding flag in ~/.claude.json:

• hasCompletedProjectOnboarding: false (or absent) → full welcome screen renders and stays.
• hasCompletedProjectOnboarding: true → full screen draws, then onboarding-complete logic collapses it to the minimal header. This is the "flash then disappear."

The flag gets set to true the first time you launch claude in a directory that contains a CLAUDE.md. Crucially, the flag is sticky: deleting the CLAUDE.md afterward does not reset it, so the welcome screen stays collapsed forever. And for any project that keeps a CLAUDE.md, resetting the flag manually is futile — the next launch re-runs onboarding and re-sets it to true, so the screen flashes on every single launch.

Environment

• Claude Code version: v2.1.160
• OS: macOS (Darwin)
• Shell: zsh
• Terminal: reproduced regardless of terminal emulator and window size (including maximized)

Minimal reproduction

1. Create a brand-new directory with no CLAUDE.md. Run claude.

→ Full welcome screen renders and stays. ✅

1. Run a couple more sessions in that same directory (no CLAUDE.md).

→ Still stays. ✅ (rules out session/transcript count as the cause)

1. Add a CLAUDE.md to the directory — an empty file is enough. Run claude.

→ Welcome screen flashes for ~0.1s and collapses to the minimal header. ❌

1. Delete the CLAUDE.md. Run claude again.

→ Still collapses. ❌ (the breakage persists even though the file is gone)

1. Inspect ~/.claude.json → projects["<that dir>"].hasCompletedProjectOnboarding is now true (it was false/absent before step 3).
2. Set it back to false (with no CLAUDE.md present) and run claude.

→ Full welcome screen returns and stays. ✅ (confirms the flag is the gate)

1. Now repeat on a project that keeps a CLAUDE.md: set the flag to false, launch claude.

→ It flashes again, and the flag is back to true in ~/.claude.json. The CLAUDE.md re-triggers onboarding completion on every launch, so there is no durable way to keep the full welcome screen.

Root cause

projects[<path>].hasCompletedProjectOnboarding in ~/.claude.json gates the full-vs-collapsed welcome screen. It is auto-set to true whenever a session starts in a directory containing a CLAUDE.md, and it is never reset when the CLAUDE.md is removed.

Net effect for real-world usage: any project with a CLAUDE.md permanently shows the collapsed welcome screen, with the brief full-screen "flash" on each launch.

Expected behavior

• Presence of a CLAUDE.md should not permanently suppress the full welcome screen (or, if this is intended once onboarding is genuinely complete, it should render the collapsed header directly without the jarring flash).
• Removing the CLAUDE.md should restore the prior behavior (the flag should not be sticky in a way that outlives the file).
• At minimum, provide an explicit opt-out setting to always show (or always hide) the full welcome screen, independent of CLAUDE.md presence.

Notes / what was ruled out

• Not terminal height — reproduced maximized/fullscreen.
• Not MCP — reproduced with claude --strict-mcp-config (zero MCP servers).
• Not project-local settings — reproduced with claude --setting-sources user (global settings only).
• Not session/transcript count — a directory with a single short prior session stays full; a directory breaks the moment a CLAUDE.md is introduced, even with the same (or fewer) sessions.
• The "flash" is the full screen rendering before the onboarding-complete collapse fires, consistent with the render-race reports below.

Related issues

• #43504 — CLAUDE.md presence collapses the welcome screen UI (closed as inactive/NOT_PLANNED; this report adds the underlying hasCompletedProjectOnboarding mechanism + the sticky-flag detail)
• #47271 — Make welcome screen layout consistent regardless of CLAUDE.md presence (closed as duplicate of #43504)
• #50612 — Welcome screen flashes and disappears on startup (open; same symptom, framed as a render race)
• #54887 — Welcome screen disappears instantly on startup (open)
• #2254 — Disable the welcome banner (open; tracks the lack of an opt-out toggle)
• #18153 — "Recent activity" empty despite valid session data (related welcome-screen area)