[claude-code-user-docs-review] 🔍 Claude Code User Documentation Review - 2026-07-08

[github-actions[bot]]

Executive Summary

A Claude Code user can fully adopt gh-aw without any Copilot account: --engine claude + ANTHROPIC_API_KEY are both surfaced in the quick-start, and every built-in tool is engine-agnostic (0 Copilot-only, 0 Claude-only). The single most persona-relevant gap persists for the 22nd run straight: CLAUDE_CODE_OAUTH_TOKEN — the credential a Claude Code / Claude Max/Teams subscriber already holds — is explicitly unsupported and silently ignored (auth.mdx:206-208), and this caveat never appears in the quick-start. Overall score 7.5/10, 0 critical blockers.

Severity Findings (Critical → Major → Minor)

Critical Blockers: None. Claude is a first-class engine; onboarding is Copilot-free.

Major Obstacles

1. OAuth-token dead end. auth.mdx:208: "CLAUDE_CODE_OAUTH_TOKEN is not supported... If you have set [it] as a repository secret, it will be ignored — configure ANTHROPIC_API_KEY instead." A Claude Code user's most likely existing credential fails silently. The caveat lives only in auth.mdx:206-208 and :356 — the quick-start Claude tab (quick-start.mdx:97-100) never mentions it.
2. Silent Copilot default. quick-start.mdx:75: removing engine: from frontmatter makes the runtime default to Copilot; gh aw init emits Copilot-specific artifacts unless --engine claude is passed (cli.md:142,147). 36 of 258 workflow files omit engine: and thus default to Copilot. A Claude-only user who edits frontmatter can silently land on an engine they can't authenticate.
3. Uneven secret callouts. The quick-start Tabs (quick-start.mdx:88-114) give step-by-step secret setup for Copilot, Anthropic, and Codex, but Gemini is prerequisite-only (quick-start.mdx:30) with no auth block, and the keyless WIF (github-oidc) path for Claude — ideal for a secrets-averse Claude user — is documented only in auth.mdx:214-278, never surfaced in the quick-start.

Minor Confusion
4. Copilot-first framing. quick-start.mdx:30: "If you already have GitHub Copilot, start there — it requires no extra account setup." No "why Claude vs Copilot" guidance anywhere.
5. Loose ends. custom engine has 0 standalone workflow examples (only shared/genaiscript.md); crush appears in the gh aw secrets bootstrap --engine list (cli.md:258) but isn't in the primary engine list (how-they-work.mdx:26); no default Claude model/version is documented (architecture.mdx:279).

Engine & Tool Matrix

Engine	Setup in quick-start	Workflow examples	Auth secret	Score
Copilot (default)	✅ full Tab + PAT-free copilot-requests:write	123 explicit (+36 omitted ≈ 159)	none / COPILOT_GITHUB_TOKEN PAT	9
Claude	✅ Tab (ANTHROPIC_API_KEY) + --engine claude (qs:69)	60	ANTHROPIC_API_KEY; WIF keyless (not in QS)	7
Codex	⚠️ Tab present, thinner	14	OPENAI_API_KEY/CODEX_API_KEY	6
Custom	❌ none	0 standalone	via engine.env/base-url	3

Built-in tools: 14 documented, all engine-agnostic — 0 Copilot-only, 0 Claude-only, 0 Codex-only. Only web-search is engine-dependent (Codex disables it by default unless declared, tools.md:67) and tools.timeout has per-engine defaults (Claude 60s / Codex 120s, tools.md:157); neither excludes Claude. This is the strongest positive for Claude adoption.

Parity observations (engine-example-counter): Copilot outnumbers Claude ~2.6:1 effective. Form preference is inverted — Claude authors favor inline engine: claude (46 inline / 14 object), Copilot skews object-form for model pinning (92 object / 31 inline). Every engine has a dedicated smoke test, but Copilot has 6+ variants (arm/sdk/aoai/entra/sub-agents) vs Claude's smoke-claude family. pi (21) is unexpectedly the 3rd-most-common engine, ahead of Codex.

Auth Gaps

• Claude: ANTHROPIC_API_KEY (console.anthropic.com) ✅ in quick-start; WIF github-oidc keyless ✅ supported but only in auth.mdx:214-278; CLAUDE_CODE_OAUTH_TOKEN ❌ unsupported/ignored (auth.mdx:206-208). Claude + GitHub MCP needs "additional configuration" deferred to the engines reference (auth.mdx:210).
• Copilot: PAT-free copilot-requests:write + ${{ github.token }} (auth.mdx:15,95-118), or fine-grained COPILOT_GITHUB_TOKEN; OAuth gho_ tokens rejected (auth.mdx:148).
• Codex: OPENAI_API_KEY or CODEX_API_KEY (precedence) — auth.mdx:282-298.
• Gemini: GEMINI_API_KEY — documented in auth.mdx:324-336 but not in the quick-start.

Recommended Actions

Priority 1 — Add a one-line note to the quick-start Claude Tab (quick-start.mdx:97-100): "CLAUDE_CODE_OAUTH_TOKEN (Claude Max/Teams subscription tokens) is not supported — use ANTHROPIC_API_KEY." This closes the single highest-impact persona gap with one sentence.

Priority 2 — Surface the silent-default behavior earlier (near quick-start.mdx:30, not :75) and add the keyless WIF path + a Gemini auth block to the setup Tabs so all four prerequisite engines have parity.

Priority 3 — Add a short "choosing an engine" section (Claude vs Copilot trade-offs), document the default Claude model, add at least one custom-engine standalone example, and reconcile crush between cli.md:258 and how-they-work.mdx:26.

Trend: Stable vs 2026-07-07 (22 runs running) — 7.5/10, 0 critical, identical 3 major gaps. This run re-read auth.mdx and confirmed the OAuth-token caveat verbatim at auth.mdx:206-208. No Copilot-only or Claude-only tools remain — parity is strong; the OAuth-token wording is the one durable paper cut.

References: §28944070081

Generated by 📝 Claude Code User Documentation Review · 556.7 AIC · ⌖ 21.3 AIC · ⊞ 5.2K · ◷

• expires on Jul 9, 2026, 5:12 AM UTC-08:00

[github-actions[bot]]

This discussion was automatically closed because it expired on 2026-07-09T13:12:09.624Z.

Closed by Workflow