[claude-code-user-docs-review] 🔍 Claude Code User Documentation Review - 2026-09-30

[github-actions[bot]]

Executive Summary

Onboarding without GitHub Copilot is possible — Claude Code, Codex, Gemini, and Pi are all first-class documented engines with their own auth paths. The previously critical CLAUDE_CODE_OAUTH_TOKEN trap (a Claude Code CLI user's local claude login token silently failing in CI) remains resolved for the 2nd consecutive run, now explicitly documented in 4 places. The live friction has shifted to asymmetric tooling and example coverage: gh aw init auto-scaffolds a custom agent + MCP wiring only for Copilot, and Claude has roughly half of Copilot's example/smoke-test coverage with zero equivalents for several backend/auth variants.

Severity Findings (Critical → Major → Minor)

Critical Blockers: None found this run.

Major Obstacles:

1. gh aw init only auto-creates the custom-agent file and MCP wiring for --engine copilot; Claude/Codex users must hand-author their own agent file with only a one-line pointer ("Claude Code subagents, Codex prompts") and no template or link (docs/src/content/docs/setup/cli.md:115, :139).
2. Example/smoke-test parity gap: Claude has 58 engine declarations vs Copilot's 113 (~1.95x) across .github/workflows/*.md. Copilot has an 8-variant backend/auth smoke matrix (smoke-copilot-arm.md, -sdk.md, -aoai-entra.md, -aoai-apikey.md, -mai.md, -sub-agents.md, -auto.md, -small.md) that Claude has no counterparts for.
3. Anthropic Workload Identity Federation is mentioned as a keyless alternative to ANTHROPIC_API_KEY but deferred entirely to an external reference page with no inline summary (docs/src/content/docs/setup/quick-start.mdx:151).
4. No single explicit statement that gh-aw requires Anthropic API/console billing, not a Claude Pro/Max subscription — the docs disclose that the subscription OAuth token fails, but never state the billing-model mismatch plainly.

Minor Confusion:

1. Prerequisites framing implies Copilot needs "no extra account setup" while Claude needs an account + API key — technically true but reads as favoring Copilot as the default/easy path (quick-start.mdx:72).
2. "Built-in engines are GitHub Copilot (default), Claude Code, ..." — a skimming reader may think Copilot is required unless explicitly overridden, rather than just the frontmatter default (docs/src/content/docs/introduction/how-they-work.mdx:26).
3. web-search: is disabled by default is stated for Codex/Claude/Copilot but Gemini/Pi behavior is left ambiguous (docs/src/content/docs/reference/tools.md:128).

Reverse-parity note: Claude has a 5-file "agent task permission" smoke family (smoke-agent-all-none.md, -all-merged.md, -public-approved.md, -public-none.md, -scoped-approved.md) that Copilot has no equivalent for — coverage gaps run in both directions, not just against Claude.

Engine & Tool Matrix

Engine	Setup	Examples (declarations)	Auth	Score /5
Copilot	gh aw init auto-scaffolds agent file + MCP wiring (cli.md:115)	113 (8 backend/auth smoke variants, ~33 daily/scheduled)	copilot-requests: write perm or COPILOT_GITHUB_TOKEN PAT — most detailed multi-path doc (quick-start.mdx:135-143)	5.0
Claude	Manual agent-file authoring only, no template (cli.md:139)	58 (0 backend/auth smoke variants, ~15 daily/scheduled)	ANTHROPIC_API_KEY clear; WIF link-only; OAuth-token gap now documented (quick-start.mdx:147-155, cli.md:240)	3.5
Codex	Same manual-authoring gap as Claude (cli.md:139)	75	OPENAI_API_KEY/CODEX_API_KEY — straightforward (quick-start.mdx:159-163)	3.5
Custom	Fully manual, minimal doc coverage	1 (nested only in shared/genaiscript.md)	Not centrally documented	1.5

Tool classification (reference/tools.md): of 16 documented tool types, 12 are engine-agnostic (edit, github, bash, web-fetch, playwright, cache-memory, etc.); only web-search and tools.timeout defaults vary by engine — Claude/Codex/Copilot are otherwise treated as peers in the tool surface, so the imbalance is concentrated in onboarding scaffolding and example coverage, not the tool API itself.

Auth Gaps

• Resolved (2 consecutive runs): CLAUDE_CODE_OAUTH_TOKEN from claude login is now explicitly documented as unsupported and silently ignored, in 4 places: quick-start.mdx:153, cli.md:240, plus 2 more per prior run's auth.mdx:218-220/428 and engines/claude.md:22.
• Still open: Anthropic WIF setup is link-only with no inline summary of steps (quick-start.mdx:151), unlike the level of inline auth detail given to Copilot's PAT/org-billing choice.
• Still open: No plain statement that a Claude subscription (Pro/Max) cannot be used at all — only that the specific OAuth token fails. A Claude Code user without console.anthropic.com API access has no clear signal that gh-aw is unusable for them until they hit the failure.

Recommended Actions

Priority 1 — Add a concrete Claude Code subagent template (and Codex prompt template) that gh aw init --engine claude can scaffold, mirroring what Copilot gets, closing cli.md:115/139.

Priority 2 — Add 2-3 Claude equivalents to the Copilot backend/auth smoke matrix (at minimum an SDK-mode and ARM variant) to validate parity claims in the engine table.

Priority 3 — Inline a 3-step WIF summary in quick-start.mdx next to the Claude auth section (matching Gemini's WIF treatment), and add one explicit sentence: "gh-aw requires Anthropic API console billing; Claude Pro/Max subscriptions are not supported."

References:

• §36716911073

Generated by 📝 Claude Code User Documentation Review · claude · agent · 207.5 AIC · ⌖ 5.77 AIC · ⊞ 4.9K · ◷

• expires on Oct 1, 2026, 4:54 AM UTC-08:00

[github-actions[bot]]

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

A newer discussion is available at Discussion #64769.