First-run on Windows blocks non-developers: app demands Git despite docs saying it's optional — bundle or offer to install it

Status Open
Maintainer reply None cached
Activity 1 comment · opened Aug 3, 2026

Problem

The desktop app refuses to start local sessions without Git for Windows ("Install Git, Git for Windows is required to run local sessions..."), while the official docs (setup) state Git for Windows is optional and PowerShell is the fallback. Two issues compound:

  1. Docs/implementation mismatch — either the PowerShell fallback should let first-run proceed, or the docs are wrong.
  2. The error language assumes a developer audience. A first-time user cannot distinguish "Git" from "GitHub". In practice they wander off to create a GitHub account or install GitHub Desktop — a confusing detour that happens to fix the symptom (it puts git on disk) while teaching them the wrong lesson about what was missing.

Real-world data point

On 2026-08-03 I onboarded a family member in their 80s, zero git/GitHub experience, Windows 11. First launch of Claude Code in the desktop app: blocked by the Git error. They read it as "I don't have GitHub", installed a "GitHub app", restarted, and it worked — but only because a relative who develops software was on hand to interpret.

The punchline: once past that single gate, the same person shipped six well-formed pull requests to an upstream repo that same day (their GitHub account was created that morning), with Claude doing the git mechanics. The barrier is not the concepts — Claude absorbs those. The barrier is one missing developer-tool install that the app neither performs nor explains in non-developer language.

Suggested fixes (any subset helps)

  1. Offer to install Git on first run — detect absence, prompt, run winget install Git.Git (winget ships with Windows 11), re-detect. No elevation gymnastics needed for the common case.
  2. Honor the documented PowerShell fallback so first-run works with zero extra installs, even if degraded.
  3. Rewrite the gate error for non-developers — e.g. "Claude Code needs a free helper tool called Git (this is not GitHub, and no account is needed). Install it now?" with a one-click action.

Related but distinct: #72976, #34496, #57448 report detection failures when Git IS installed. This issue is about the first-run experience when Git is genuinely absent — the fresh-user path.

View original on GitHub ↗

This issue has 1 comment on GitHub. Read the full discussion on GitHub ↗