[DOCS] `claude -p` slow / appearing to hang on Windows during the slash-command and skill scan is not mentioned in troubleshooting or the headless guide (regression v2.1.161–v2.1.168, fixed in v2.1.169)

Documentation Type

Unclear/confusing documentation

Documentation Location

https://code.claude.com/docs/en/troubleshoot-install

Section/Topic

The "Claude hangs on startup / claude --version works but claude hangs" troubleshooting area (the entry that begins "If claude --version prints a version but claude crashes or hangs on startup, run these checks to narrow down the cause."). The Windows-specific "scan blocks install" section ("The process cannot access the file ... during Windows install") is also adjacent and worth a cross-reference.

The claude -p headless guide at https://code.claude.com/docs/en/headless is the second-best landing spot: it already documents an earlier claude -p hang regression under "Background tasks at exit" and would be a natural place for a Windows slash-command/skill-scan note.

Current Documentation

The v2.1.169 changelog at https://code.claude.com/docs/en/changelog includes only a single one-line bullet:

* Fixed claude -p being slow or appearing to hang on Windows while waiting for the slash-command/skill scan (regression in 2.1.161)

The current troubleshoot-install page at https://code.claude.com/docs/en/troubleshoot-install has no entry that matches this symptom. The closest existing item is generic:

If claude --version prints a version but claude crashes or hangs on startup, run these checks to narrow down the cause.

That entry does not mention claude -p, does not call out Windows specifically, and does not reference the 2.1.161–2.1.168 regression range.

The headless guide at https://code.claude.com/docs/en/headless already has a precedent for documenting a claude -p regression under "Background tasks at exit":

If Claude starts a background Bash task during a claude -p run, for example a dev server or a watch build, that task is terminated about five seconds after Claude returns its final result and stdin closes. The grace period lets a task that finishes right after the result still deliver its output. Before v2.1.163, a never-exiting background process would hold the claude -p invocation open indefinitely.

There is no equivalent note for the 2.1.161–v2.1.168 Windows scan regression, even though the v2.1.169 changelog explicitly flags the same class of symptom ("slow or appearing to hang") and the same release where the matching fix was made.

What's Wrong or Missing?

A. The fix is invisible to affected users

claude -p runs on Windows that were slow or appeared to hang between v2.1.161 (June 2, 2026) and v2.1.168 (June 6, 2026) have a one-line fix in the v2.1.169 changelog. Anyone searching the docs for "claude -p slow Windows", "claude -p hang", "claude -p Windows", or "slash command scan" will not land on a troubleshooting entry that explains the regression or that upgrading to v2.1.169 resolves it.

B. The headless guide has a documented precedent for this kind of note, but no matching Windows entry

The "Background tasks at exit" paragraph in the headless guide documents a previous claude -p hang regression (v2.1.163) with version bounds, symptom, and fix in three sentences. The 2.1.161–v2.1.168 Windows scan regression is a peer case (same claude -p surface, same class of "appears to hang" symptom, same kind of version-bounded fix in a later release) and is not documented the same way.

C. The Windows troubleshooting page has no Windows claude -p hang entry

troubleshoot-install already groups Windows-specific hangs (install hangs on file lock, hangs in Docker, hangs in WSL, claude hang-on-startup). A new Windows claude -p hang entry fits the existing structure and would have caught affected users during the regression window. The current generic "hangs on startup" entry does not mention claude -p, does not distinguish Windows, and does not direct users to upgrade.

Suggested Improvement

Option A: Add a Windows-specific entry to the troubleshooting page (minimum fix)

Add a new entry under the Windows section of troubleshoot-install, alongside "The process cannot access the file" and "Claude Desktop overrides the claude command on Windows", with a title and body like:

### claude -p appears to hang on Windows between v2.1.161 and v2.1.168 On Windows, claude -p runs on v2.1.161 through v2.1.168 could be very slow or appear to hang at startup while Claude Code waited for the slash-command and skill scan to finish. Upgrading to v2.1.169 (or later) restores the previous startup time. If you cannot upgrade, run with --bare to skip the slash-command and skill auto-discovery: ``bash claude --bare -p "Summarize this file" ` claude --bare -p skips hooks, skills, plugins, MCP servers, auto memory, and CLAUDE.md` discovery, so it is the recommended mode for CI and scripts regardless.

Option B: Mirror the precedent on the headless guide (parity with the v2.1.163 note)

Add a new short note to https://code.claude.com/docs/en/headless near the existing "Background tasks at exit" section, for example under a new subheading "Windows scan delays between v2.1.161 and v2.1.168":

On Windows between v2.1.161 and v2.1.168, claude -p could be slow or appear to hang at startup while waiting for the slash-command and skill scan to finish. The scan was restored to its previous performance in v2.1.169. Use claude --bare -p for one-off Windows scripted runs that need to skip the scan entirely.

Recommended: do both

The headless-guide note reaches users who already know they are running claude -p and click through from --print / -p documentation. The troubleshooting entry reaches users searching for "claude hangs" or "claude -p slow" symptom keywords and users on older 2.1.16x versions who have not yet upgraded.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Context |
|------|---------|
| https://code.claude.com/docs/en/troubleshoot-install | Primary location; Windows hang section needs a new entry for the v2.1.161–v2.1.168 claude -p scan regression |
| https://code.claude.com/docs/en/headless | Already documents the v2.1.163 claude -p background-task hang regression; needs a matching note for the v2.1.161–v2.1.168 Windows scan regression |
| https://code.claude.com/docs/en/changelog | Source of the v2.1.169 fix bullet; no user-facing change needed beyond cross-reference from the two pages above |
| https://code.claude.com/docs/en/cli-reference | Cross-reference target: documents --bare and --disable-slash-commands, which are the two workarounds for affected users |

Total scope: 2 pages need new content (troubleshoot-install, headless); 2 pages are cross-reference targets only (changelog, cli-reference).

Versioning note: the regression was introduced in v2.1.161 and fixed in v2.1.169. The Windows-specific note applies to any user on v2.1.161 through v2.1.168 inclusive.

Related Windows items already documented on troubleshoot-install (to keep the new entry consistent with the surrounding structure):

• "The process cannot access the file ... during Windows install" — installer blocked by antivirus scan of a partial download.
• "Claude Desktop overrides the claude command on Windows" — PATH-priority issue with Claude.exe in WindowsApps.
• "Claude Code on Windows requires either Git for Windows (for bash) or PowerShell" — missing shell.
• "Claude Code does not support 32-bit Windows" — 32-bit PowerShell entry.

Workaround availability: the v2.1.169 changelog bullet does not mention that claude --bare -p sidesteps the scan, but --bare is documented on the same headless guide. Cross-linking --bare from a new troubleshooting entry would let affected users on frozen v2.1.16x versions keep working without upgrading.