[claude-code-user-docs-review] 🔍 Claude Code User Documentation Review - 2026-06-05

[github-actions[bot]]

Executive Summary

A Claude Code user (GitHub + Claude, no Copilot, no Copilot CLI) can adopt gh-aw — there are no hard blockers. The interactive add-wizard lets them pick Claude and the docs fully cover ANTHROPIC_API_KEY. The persistent friction is framing: Copilot is the silent compile-time default, and the single most important caveat for this persona — that a Claude subscription / CLAUDE_CODE_OAUTH_TOKEN is not supported — lives only in reference/auth.mdx and is never surfaced in the Quick Start.

Key finding: A Claude Code user almost certainly authenticates Claude Code via a Max/Pro subscription token (claude setup-token → CLAUDE_CODE_OAUTH_TOKEN). gh-aw ignores that token; it requires a separate pay-as-you-go ANTHROPIC_API_KEY from the Anthropic Console. This is documented (auth.mdx:121-123) but absent from the onboarding path where it matters.

Persona Context

• GitHub: ✅ uses it
• Claude Code: ✅ primary AI tool
• GitHub Copilot: ❌ actively avoids
• Copilot CLI: ❌ does not use

Severity Findings

No 🚫 Critical Blockers found — every onboarding step has a working Claude path.

⚠️ Major Obstacles (significant friction)

M1 — Subscription/OAuth token unsupported, and the caveat is buried.
docs/.../reference/auth.mdx:121-123: "CLAUDE_CODE_OAUTH_TOKEN is not supported... Provider-based OAuth authentication (such as billing through a Claude Teams or Claude Max subscription) is not supported... it will be ignored." This is the #1 trap for the persona: a Claude Code user's natural credential does not work, and setup/quick-start.mdx (the page they read) never mentions it. They must obtain a separate billed API key. Fix: add a one-line callout to the ANTHROPIC_API_KEY NOTE block in quick-start.mdx:84-88. (Tracked but unresolved — see README.md:237.)

M2 — Copilot is the silent compile-time default.
introduction/how-they-work.mdx:26 and reference/engines.md:24 ("Copilot CLI is the default — engine: can be omitted"). A Claude user who edits a .md without adding engine: claude (only shown as optional Step 4, quick-start.mdx:127-133) silently compiles a Copilot workflow that then fails for lack of COPILOT_GITHUB_TOKEN. Fix: in Quick Start, state the default explicitly and show engine: claude in the primary path, not an optional afterthought.

M3 — gh aw init generates Copilot-specific artifacts by default.
setup/cli.md:135,140: must run gh aw init --engine claude to "skip Copilot-specific artifacts." This is in the CLI reference but not surfaced in quick-start.mdx, so a Claude user following onboarding generates unused Copilot scaffolding. Fix: surface --engine claude in the Quick Start init step.

💡 Minor Confusion (paper cuts)

m1 — Copilot-first ordering throughout onboarding. quick-start.mdx:71 lists COPILOT_GITHUB_TOKEN first, and :77-81 gives it a dedicated NOTE before the ANTHROPIC one (:84-88). README (:40) and how-they-work (:26) also list Copilot first. Reads as "Copilot is the intended engine." Fix: lead with engine-neutral language or alphabetize.

m2 — No "why Claude vs Copilot?" guidance. No doc helps the persona understand the trade-off or confirm feature parity; they must infer it from example counts.

m3 — No pre-flight check that the Anthropic key has billing/credits. auth.mdx:197-199 covers this reactively (401/403 troubleshooting) but Quick Start offers no proactive note that a key without credit will fail.

Engine Comparison

Engine	Setup docs	Examples	Auth docs	Score /5
Copilot	Default; wizard + dedicated NOTE	126 decls (+32 implicit default)	Full, fine-grained PAT walkthrough	5
Claude	Wizard supports it; --engine claude in CLI ref	63 decls; smoke-claude.md + MCP examples	Full ANTHROPIC_API_KEY (but OAuth caveat buried)	4
Codex	Wizard supports it	14 decls	OPENAI_API_KEY / CODEX_API_KEY documented	3
Custom / BYOK	No setup/ page at all	1 decl (shared/genaiscript.md)	Only in reference/engines.md + auth.mdx; no key-acquisition guidance	2

Tool Availability

Of the 15 tools documented in reference/tools.md, all are engine-agnostic except web-search, which is engine-dependent (native opt-in on Codex per tools.md:62-67; via third-party MCP on others). There is no copilot tool — copilot/claude/codex are engine names, not tools. agentic-workflows, playwright, github, bash, cache-memory, safe-outputs are all engine-agnostic. No tool is locked to the Copilot engine, so Claude users lose no documented tool capability. Only engine-specific defaults differ (tool timeout: Claude 60s, Codex 120s — tools.md:157).

Authentication Gaps

Engine	Required secret	Obtain-key guidance?	Gap for Claude persona
Copilot	COPILOT_GITHUB_TOKEN (fine-grained PAT)	✅ inline	—
Claude	ANTHROPIC_API_KEY	✅ (quick-start.mdx:86)	OAuth/subscription token unsupported and not surfaced in Quick Start; no billing pre-check
Codex	OPENAI_API_KEY (or CODEX_API_KEY)	✅ (auth.mdx:135)	—
Custom	per-engine secret + *_BASE_URL	❌ none	No setup/ page; assumes existing provider creds

Authoritative auth reference: reference/auth.mdx. No per-engine auth pages exist under setup/.

Example Parity

Engine declarations across .github/workflows/*.md: Copilot 126 · Claude 63 · Codex 14 · Custom 1, with 32 workflows using no explicit engine (implicit Copilot). The ~2:1 Copilot lead is largely because Copilot is the default and gets restated in nested engine.id blocks. Qualitatively, Claude has comparable coverage — dedicated smoke-claude.md (on par with smoke-copilot*.md), MCP examples, and presence across the same workflow categories. docs/.../examples/ is engine-agnostic (relies on default). No example-coverage blocker for Claude.

Recommended Actions

Priority 1 (close the persona trap): Add the CLAUDE_CODE_OAUTH_TOKEN-not-supported caveat to the ANTHROPIC_API_KEY NOTE in quick-start.mdx:84-88 (resolves the open item at README.md:237).

Priority 2 (de-Copilot the default path): State the compile-time default explicitly in Quick Start, show engine: claude in the primary flow (not optional Step 4), and surface gh aw init --engine claude.

Priority 3 (polish): Add a short "Choosing an engine" section (why Claude, parity note), use engine-neutral ordering in secret lists, and add a billing/credit pre-check note for the Anthropic key.

Conclusion

Can Claude Code users adopt gh-aw? Yes — with avoidable friction. No hard blockers; a Claude-only path exists end-to-end. The cost is that the persona must (1) discover that their subscription token won't work and get a billed API key, and (2) opt into Claude against Copilot-default framing at several steps.

Overall score: 7.5 / 10 — stable vs. the 2026-06-01 and 2026-06-04 reviews (both 7.5). No regressions; the Priority-1 fix (README.md:237) remains open across all three runs.

References:

• §27017484654
• §26954844898
• §26761037603

Generated by 📝 Claude Code User Documentation Review · 460.2 AIC · ◷

• expires on Jun 6, 2026, 1:37 PM UTC

[github-actions[bot]]

This discussion has been marked as outdated by Claude Code User Documentation Review.

A newer discussion is available at Discussion #37309.