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

[github-actions[bot]]

Executive Summary

A developer who uses Claude Code and avoids GitHub Copilot can adopt gh-aw today: Claude is a fully documented first-class engine (auth, ~63 examples, CLI flags). The friction is not "can't"—it's "Copilot is the default at every step." The most surprising gap for this persona: a Claude Code user's existing OAuth/subscription auth (Max/Pro) is explicitly not supported—gh-aw needs a separate pay-as-you-go ANTHROPIC_API_KEY, documented only in reference pages, not in onboarding.

Overall: 7/10 (up from 6/10 on 2026-05-31).

Persona Context

• GitHub ✅
• Claude Code ✅ (primary AI tool)
• GitHub Copilot ❌ (actively avoided)
• Copilot CLI ❌

Severity Findings

No critical blockers — a Claude Code user is never hard-stopped. Findings are 4 Major / 4 Minor.

⚠️ Major Obstacles (4) — significant friction

M1 — Claude Code subscription auth does not transfer; API key required (persona-critical).
CLAUDE_CODE_OAUTH_TOKEN is explicitly not supported — only ANTHROPIC_API_KEY works, and OAuth tokens (Claude Teams/Max billing) are ignored if set (reference/auth.mdx:121-123, reference/faq.md:337-339). A Claude Code user authenticates via a Pro/Max subscription OAuth flow and will assume that carries over. It does not — they must create a separate pay-as-you-go Anthropic API key. Documented only in reference/auth, never in the quick start. Fix: add a callout under the ANTHROPIC_API_KEY note: "Claude Code/Max subscription tokens are not supported — gh-aw needs an Anthropic API key (billed per use)."

M2 — Default engine is Copilot; the no-engine path silently runs Copilot.
DefaultEngine = CopilotEngine (pkg/constants/engine_constants.go:34). 31 shipped example workflows declare no engine: field and so run on Copilot. In the quick start, engine: claude appears only as an optional Step-4 customization (quick-start.mdx:129-133), not the primary flow. Fix: state the default where examples are introduced; add engine: claude to a primary quick-start example.

M3 — gh aw init provisions Copilot-specific artifacts by default.
gh aw init enables a Copilot dispatcher skill + custom agent by default; you must pass --engine claude to "Skip Copilot-specific artifacts" (setup/cli.md:135, setup/cli.md:141). Documented only as a flag, never as a required step for non-Copilot users. Fix: make engine selection a first-class init step.

M4 — Auth reading-order frames Copilot as primary.
In quick-start.mdx Step 3, the COPILOT_GITHUB_TOKEN callout (:77-82) precedes ANTHROPIC_API_KEY (:84-88), and the Copilot token needs a more involved fine-grained-PAT + "Copilot Requests: Read" flow. Ordering signals Copilot-first. Fix: order callouts by selected engine, or use equal-weight tabs.

💡 Minor Confusion (4) — paper cuts

m1 — Example volume parity. Copilot has 126 example workflows vs Claude's 63 (~half); Codex 14, Gemini 1 (see Example Parity below). Claude coverage spans the same categories, just lower volume.

m2 — No "why Claude over Copilot?" guidance. None of the six core docs offer engine-selection rationale or a capability comparison. A Copilot-avoider gets no positive confirmation they're on a supported path.

m3 — Codex/Gemini selectable but lack inline setup callouts. The wizard lets you pick Copilot/Claude/Codex/Gemini (quick-start.mdx:70), but only Copilot and Claude get inline secret-setup callouts (quick-start.mdx:77-88); Codex (OPENAI_API_KEY) and Gemini get only a link.

m4 — web-search is engine-dependent, but Claude's requirement isn't stated. tools.md:62-67 marks web-search engine-dependent (disabled by default on Codex; "some engines require third-party MCP servers") without stating Claude's specific behavior. how-they-work.mdx:26 labels Copilot "(default)" with no Claude setup pointer beyond deferral to /reference/engines/.

Engine Comparison

Ratings out of 5 (from sub-agent data: example counts, auth extraction, default-engine constant).

Engine	Setup	Examples	Auth	Score	Notes
Copilot	5	5 (126)	4	4.7	Default engine; init artifacts; PAT setup fiddly
Claude	4	4 (63)	4	4.0	First-class; engine: claude; OAuth unsupported, API key only
Codex	3	2 (14)	3	2.7	Documented; no inline quick-start callout
Custom	1	0	1	1.0	No custom engine documented; only a command override (engines.md:231-240)

Tool Availability

All 13 documented tools in reference/tools.md are engine-agnostic (edit, github, bash, web-fetch, playwright, cache-memory, repo-memory, qmd, agentic-workflows, cli-proxy, mcp-servers, tools.timeout, tools.startup-timeout). Tooling is not gated by engine — good news for Claude users.

• Only web-search is engine-conditional (tools.md:62-67: disabled by default on Codex; "some engines require third-party MCP servers"; Claude's behavior unstated).
• There is no copilot tool in tools.md — the engine name is not a tool, so a Claude user meets nothing Copilot-only here.

Authentication Gaps

Per-engine auth facts (from auth-doc-extractor)

Engine	Required secret	Obtaining key documented?	Inline quick-start callout?
Copilot	COPILOT_GITHUB_TOKEN (fine-grained PAT, Copilot Requests: Read)	✅	✅
Claude	ANTHROPIC_API_KEY	✅ (console.anthropic.com, quick-start.mdx:86)	✅ (quick-start.mdx:84-88)
Codex	OPENAI_API_KEY / CODEX_API_KEY	✅	❌ (link only)
Custom	none documented	❌	❌

Gaps relevant to Claude Code users:

• CLAUDE_CODE_OAUTH_TOKEN not supported — subscription OAuth ignored; only ANTHROPIC_API_KEY works (reference/auth.mdx:121-123, reference/faq.md:337-339). See Major M1. Not in the core six docs.
• Anthropic WIF (workload identity federation) is an alternative that needs no ANTHROPIC_API_KEY, but it is documented only in an ADR (adr/35939-...:36,67,69), not user-facing.
• Claude auth reaches near-parity in reference/auth.mdx (equal sections + summary table), but in quick-start.mdx it follows Copilot in order.

Example Parity

Standalone workflow files under .github/workflows/*.md (from engine-example-counter):

Engine	Count	Representative files
Copilot	126	research.md, release.md, daily-news.md, smoke-copilot.md
Claude	63	ci-doctor.md, blog-auditor.md, scout.md, deep-report.md, smoke-claude.md
Codex	14	smoke-codex.md, ai-moderator.md, grumpy-reviewer.md
Custom	0	(only shared/genaiscript.md fragment)
No engine field	31	implicitly run the Copilot default — agentic-token-audit.md, security-review.md, code-simplifier.md

Claude has genuine category parity (smoke tests, daily agents, reviewers, reporting) at roughly half Copilot's volume. The 31 no-engine files effectively pad the Copilot column.

Recommended Actions

Priority 1 (persona-critical, low effort):

• Add a quick-start callout: Claude Code/Max OAuth tokens are not supported — an Anthropic API key (ANTHROPIC_API_KEY, billed per use) is required (addresses M1).
• Add a primary quick-start example that explicitly sets engine: claude rather than relegating it to optional Step 4 (M2).

Priority 2 (reduce Copilot-default bias):

• Make engine selection an explicit, documented step of gh aw init; clarify --engine claude skips Copilot artifacts (M3).
• Order/format the auth callouts as equal-weight (tabs or selected-engine-first) (M4).
• Add engine: fields to no-engine example workflows, or document that they inherit the Copilot default (M2).

Priority 3 (polish):

• Add a short "Choosing an engine" page with a capability/cost comparison and a "why Claude" note (m1, m2).
• Add inline secret-setup callouts for Codex and Gemini (m3).
• State Claude's web-search behavior in tools.md (m4).

Conclusion

Can Claude Code users adopt gh-aw? Yes — gh-aw is engine-neutral in substance. Claude is first-class: documented auth, 63 examples, agnostic tooling, full CLI support. The friction is presentation (Copilot is the default at every fork) plus one genuine surprise: your Claude Code subscription auth won't work — you need a pay-as-you-go API key. None of this is a hard blocker, but a Copilot-avoider must opt in at every step and discover the API-key requirement on their own.

Score: 7/10 (↑ from 6/10 on 2026-05-31). Improvement: the quick-start wizard now has an explicit "Select an AI Engine" step and a Claude setup callout at near-parity. Unchanged: default engine remains Copilot, init scaffolds Copilot artifacts, examples 126 vs 63. Closing the API-key-vs-OAuth surprise (Priority 1) would be the highest-leverage single fix for this persona.

---

_{Trend: score 6→7 · critical 0→0 · major 4→4 · minor 4→4 · Claude examples 52→63 · Copilot examples 110→126. Review date 2026-06-03.}

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

• expires on Jun 4, 2026, 2:17 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 #36916.