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

[github-actions[bot]]

Executive Summary

A developer who uses Claude Code (and avoids GitHub Copilot products) can adopt gh-aw — Claude is a first-class engine with a dedicated reference/engines.md, an ANTHROPIC_API_KEY note in Quick Start, and add-wizard / init --engine claude paths. The friction is defaults and discoverability, not missing capability: Copilot is the implicit default engine, the Quick Start narrative never sets engine: claude inline (only optional Step 4), and the most likely persona trap — CLAUDE_CODE_OAUTH_TOKEN is silently ignored — is buried in auth.mdx and absent from Quick Start.

Key finding: A Claude Code user's instinct is to reuse their subscription via OAuth. gh-aw does not support CLAUDE_CODE_OAUTH_TOKEN (auth.mdx:121-123) — only a pay-as-you-go ANTHROPIC_API_KEY. Quick Start never warns about this, so the persona's first attempt can fail with no in-context explanation.

Persona Context

• GitHub ✅ — standard GitHub features & Actions
• Claude Code ✅ — primary AI tool
• GitHub Copilot ❌ — actively avoided, no license/token
• Copilot CLI ❌ — not installed

Severity Findings

🚫 Critical Blockers (0 hard blockers — one silent auth trap)

No absolute blockers: the full flow completes via gh aw add-wizard (engine menu includes Claude, quick-start.mdx:70) or gh aw init --engine claude (cli.md:141). The closest thing to a blocker is a silent auth trap:

• CLAUDE_CODE_OAUTH_TOKEN unsupported & undocumented in Quick Start. Only ANTHROPIC_API_KEY works; OAuth / Claude Max / Teams subscription billing is explicitly not supported, and the OAuth token is ignored if set (auth.mdx:121-123, 199). Quick Start's ANTHROPIC_API_KEY note (quick-start.mdx:84-88) omits this. For the Claude Code persona this is the most likely first-run failure.

⚠️ Major Obstacles (Copilot-first defaults & narrative)

• Copilot is the silent default engine. Omitting engine: resolves to Copilot (engines.md:24; how-they-work.mdx:26). Of 236 workflow files, 29 declare no engine and default to Copilot. A Claude-only user copying such a sample needs COPILOT_GITHUB_TOKEN, which they cannot obtain.
• Quick Start narrative never sets engine: claude inline. It installs daily-repo-status and shows engine: claude only in optional Step 4 (quick-start.mdx:129-133). The sample's own default engine is unstated — if Copilot, the first run fails until overridden.
• gh aw init generates Copilot-specific artifacts by default (dispatcher skill + custom agent); user must pass --engine claude to skip them (cli.md:135).
• COPILOT_GITHUB_TOKEN is listed first in prerequisites and the secrets step, with the most detailed PAT walkthrough (quick-start.mdx:71, 77-82). Claude users must scan past Copilot setup.

💡 Minor Confusion (paper cuts)

• Copilot-first ordering everywhere: prerequisites (quick-start.mdx:29), wizard list (:70), secrets bootstrap examples (cli.md:246).
• "Which engine should I choose?" frames Copilot as most capable: "Copilot supports the broadest gh-aw feature set" (engines.md:28) — true, but no "why pick Claude" counterpoint beyond max-turns.
• engines.md is not linked from Quick Start, so the persona may never find the (excellent) Claude engine reference, feature table, and permission-mode security model.
• web-search for Claude needs a third-party MCP server (engines.md:40; tools.md:65), but only the Codex behavior is spelled out — Claude users get no heads-up.

Engine Comparison

Ratings /5 (Setup clarity / Examples / Auth docs), from sub-agent data.

Engine	Setup	Examples	Auth	Score
Copilot	5 — default, full PAT walkthrough	5 — 125 (+29 default = 154)	5 — detailed, license caveats	5.0
Claude	4 — engines.md strong; QS note present	4 — 63 (~27%)	3 — OAuth-unsupported gotcha hidden	3.7
Codex	3 — steps in auth.mdx	2 — 14	3 — OPENAI_API_KEY/CODEX_API_KEY	2.7
Custom/Gemini	3 — BYOK & api-target documented	1 — Gemini 1, custom 0	3 — GEMINI_API_KEY, BYOK vars	2.3

Tool Availability

14 of 15 documented tools are engine-agnostic; none are copilot/claude/codex-only at config level.

• Agnostic (work identically for Claude): edit, github, bash, web-fetch, playwright, cache-memory, repo-memory, qmd, agentic-workflows, cli-proxy, mcp-servers, tools.timeout, tools.startup-timeout, registry.
• web-search — the one engine-dependent entry. Native opt-in on Codex; Claude & most engines route via a third-party MCP server (tools.md:62-67; engines.md:40).
• Claude engine-level feature gaps (engines.md:34-45): engine.agent custom agent files ❌, engine.harness ❌, max-continuations/autopilot ❌ are Copilot-only. Claude uniquely gets max-turns ✅. Tooling is portable; a few engine features are Copilot-exclusive.
• The copilot BYOK config (COPILOT_PROVIDER_*, engines.md:180-214) is Copilot-only — irrelevant to a Copilot-avoiding persona.

Authentication Gaps

Engine	Secret	Quick Start steps	Notes
Copilot	COPILOT_GITHUB_TOKEN	Full 3-step PAT (L77-82)	Fine-grained PAT only; user-owned; ≠ GITHUB_TOKEN
Claude	ANTHROPIC_API_KEY	2-step note (L84-88)	CLAUDE_CODE_OAUTH_TOKEN ignored (auth.mdx:121-123); no 401/403 help in QS
Codex	OPENAI_API_KEY/CODEX_API_KEY	none in QS (auth.mdx)	CODEX_API_KEY wins at runtime
Gemini	GEMINI_API_KEY	none in QS	Steps in auth.mdx

Claude-only persona gaps: (1) OAuth-unsupported warning missing from QS; (2) no pointer to extra config for Claude + GitHub MCP (auth.mdx:125); (3) no Claude 401/403 troubleshooting outside auth.mdx; (4) manual engine: claude users get no standalone "set ANTHROPIC_API_KEY" instruction.

Example Parity

From 236 .github/workflows/*.md files:

Engine	Examples	Share
Copilot	125 (154 incl. 29 default)	~53% (65% eff.)
Claude	63	~27%
Codex	14	~6%
Gemini	1	<1%
Custom	0 (shared include only)	0%

Claude is well represented (2nd, 63 examples) — not a parity blocker. Real gaps are Gemini/custom (≤1 each).

Recommended Actions

Priority 1 — remove the silent auth trap

• Add a callout at quick-start.mdx:84-88: "CLAUDE_CODE_OAUTH_TOKEN / Claude Max & Teams subscriptions are not supported — use a pay-as-you-go ANTHROPIC_API_KEY from the Anthropic Console."
• Link engines.md and auth.mdx Claude troubleshooting from Quick Start.

Priority 2 — neutralize Copilot-first defaults in onboarding

• Show engine: claude inline in the main Quick Start narrative (not just optional Step 4), or state the sample's default engine and how to override before first run.
• Add a "Using Claude instead of Copilot" box near prerequisites mirroring the Copilot PAT note.

Priority 3 — discoverability & parity paper cuts

• Add a "Why choose Claude?" line at engines.md:26-28 (max-turns, no Copilot license, model choice).
• Document Claude's web-search MCP requirement alongside the Codex note in tools.md.
• Surface the gh aw init --engine claude guidance earlier (already at cli.md:135).

Conclusion

Can Claude Code users adopt gh-aw? Yes — overall 7.5/10. Claude is a genuine first-class engine: engines.md is thorough (feature table, permission-mode security model, BYOK, timeouts), tools are 14/15 engine-agnostic, and 63 Claude examples exist. The deductions are about defaults and discoverability for the Copilot-avoiding persona: Copilot is the silent default, the Quick Start is Copilot-shaped, and the CLAUDE_CODE_OAUTH_TOKEN-ignored trap — the single most persona-relevant pitfall — is absent from Quick Start. Fixing Priority 1 & 2 raises this to ~9/10.

References: Workflow run §26684175861 — https://github.com/github/gh-aw/actions/runs/26684175861

Generated by 📝 Claude Code User Documentation Review · opus48 3.4M · ◷

• expires on May 31, 2026, 12:56 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 #36117.