[claude-code-user-docs-review] 🔍 Claude Code User Documentation Review - 2026-10-31

[github-actions[bot]]

Executive Summary

A Claude Code user can complete onboarding without Copilot, but the docs are Copilot-first and the Claude path is thin. Key finding: a Claude Pro/Max or claude login token is explicitly unsupported, and the docs never say that the required ANTHROPIC_API_KEY is billed separately from a Claude subscription.

Scope: README plus 5 core docs (quick-start, how-they-work, architecture, tools, cli). The linked Claude engine page and auth reference were not in the reviewed set, so some gaps below may be answered there.

Snapshot

• Copilot-free onboarding: yes, but Copilot-steered
• Claude setup clarity: partial
• Findings: 1 critical, 6 major, 8 minor (prior run 2026-10-30: 0 / 5 / 5)

Severity Findings

Critical Blockers

• Subscription login cannot authenticate; billing difference is not explained. Only a Console ANTHROPIC_API_KEY or Anthropic WIF works. A Claude Code subscriber with no API account is stuck, and nothing warns them up front. quick-start.mdx:148, quick-start.mdx:153, cli.md:207, cli.md:287. A workaround exists (create an API key), so this is a surprise-cost and dead-end issue rather than a hard stop.

Major Obstacles

• Claude setup relies on pages outside the core set; the core docs give only the secret name and engine: claude. quick-start.mdx:155, how-they-work.mdx:33
• Anthropic WIF is described in prose only; no engine.auth YAML or federation-rule steps. quick-start.mdx:151, cli.md:207
• Omitting engine: silently selects Copilot, and no failure mode is documented for someone who copies a Copilot workflow. how-they-work.mdx:26, cli.md:183-185
• gh aw init without --engine claude creates Copilot-only artifacts. cli.md:153, cli.md:174-181
• The wizard configures ANTHROPIC_API_KEY only on the pull request path; the direct-push path is unexplained. cli.md:207, quick-start.mdx:127
• Claude default tool timeout is 60s with no Claude-specific guidance for long tool calls. tools.md:253, tools.md:262

Minor Confusion

• Quick-start says "If you already have GitHub Copilot, start there - it requires no extra account setup" and claims it "requires only the GitHub CLI". quick-start.mdx:70, quick-start.mdx:51
• Non-Copilot init tells users to write Claude Code subagents themselves, with no example. cli.md:180
• Claude web search is on only when web-search: is declared; native vs MCP is not explained, and web-fetch has no Claude note. tools.md:128, tools.md:116-124
• gh aw doctor does not check ANTHROPIC_API_KEY. cli.md:303-322
• Pi with an anthropic/ model needs tools.github.mode: gh-proxy and tools.cli-proxy: true. quick-start.mdx:175-177
• Unclear whether the Claude engine uses the AWF api-proxy ("when supported by an agent"). architecture.mdx:303
• Compile scanners fall back to Docker when local binaries are missing. cli.md:410
• Runs require the workflow on the default branch with workflow_dispatch (all engines). cli.md:561-563

Engine & Tool Matrix

Example counts come from top-level .github/workflows/*.md frontmatter (shared fragments not scanned); they are repo workflows, not docs examples.

Engine	Setup	Examples	Auth	Score
Copilot	Default, 2 auth paths (quick-start.mdx:133-143)	137 (135 excl. threat-detection)	copilot-requests: write or COPILOT_GITHUB_TOKEN	5/5
Claude	Wizard / init --engine claude (cli.md:159)	65 (64 excl. threat-detection)	ANTHROPIC_API_KEY or WIF; OAuth rejected	3/5
Codex	Short section (quick-start.mdx:157-163)	78	CODEX_API_KEY or OPENAI_API_KEY	3/5
Custom	Not covered in the core docs	0	n/a	1/5
Other (Pi, Gemini, Aider, Goose, ...)	Pi and Gemini only (quick-start.mdx:167-177)	66	Model-prefix routed (Pi)	2/5

Parity observations: Claude has about 47% of Copilot example volume. Of the 65 Claude declarations, 30 use the nested id: form and 35 the inline form. Core-doc mentions are roughly 26 Claude vs 41 Copilot lines. No workflow declares engine custom.

Tool classification (14 configurable entries, 19 rows total):

Class	Tools	Claude note
Built-in / shell / GitHub	edit, bash, github	No engine caveat (tools.md:20-39, 102-114)
Engine-dependent web	web-fetch, web-search	Claude web-search off unless declared (tools.md:128)
Remote MCP	linear, jira	Secrets required (tools.md:41-100)
Memory	cache-memory, repo-memory, drive-memory (private preview)	No caveat (tools.md:146-175)
Experimental / internal	qmd, agentic-workflows, playwright	Playwright defers to an outside reference (tools.md:134-213)
Settings, not tools	cli-proxy, tools.timeout, startup-timeout	Claude timeout 60s (tools.md:215-267)

Auth Gaps

• Claude secret: ANTHROPIC_API_KEY; keyless: Anthropic WIF with permissions.id-token: write. Unsupported: CLAUDE_CODE_OAUTH_TOKEN (quick-start.mdx:147-153).
• Missing: API vs subscription billing note (quick-start.mdx:148); WIF engine.auth example (quick-start.mdx:151); doctor check for engine keys (cli.md:303-322); behavior on invalid or expired key; Claude model and cost guidance (architecture.mdx:809); whether GITHUB_TOKEN alone suffices.
• Copilot-only items a Claude user cannot use: copilot-requests: write, assign-to-agent (needs a PAT; engine interaction unstated, cli.md:320), and Copilot agent/MCP wiring files not generated for Claude (cli.md:180-181).

Recommended Actions

Priority 1

• Add a callout near quick-start.mdx:148-153: Claude subscriptions do not work, API keys are billed separately, with a link to Anthropic Console.
• Add a complete Anthropic WIF engine.auth YAML example.

Priority 2

• Make the quick-start engine-neutral (Copilot not first) and fix the "requires only the GitHub CLI" claim (quick-start.mdx:51, :70).
• Document what happens when engine: is omitted and how to convert a Copilot example to Claude (cli.md:183-185).
• Explain wizard secret storage on the direct-push path (cli.md:207).

Priority 3

• Extend gh aw doctor and its docs to check ANTHROPIC_API_KEY.
• Add a Claude subagent example (cli.md:180) and a web-search/web-fetch engine matrix (tools.md:116-128).
• Add Claude guidance for the 60s tool timeout (tools.md:253).

Note: claude example counts shift from 63 to 65 since the last run due to the counting method (top-level workflows only); trend is not a real change.

Generated by 📝 Claude Code User Documentation Review · claude · routed: sonnet55 high · ~49 AIC · ⌖ ~1 AIC · ⊞ 2.7K · ◷

• expires on Nov 1, 2026, 4:31 AM UTC-08:00