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

[github-actions[bot]]

Executive Summary

A Claude Code user can adopt gh-aw today: Claude is a first-class documented engine with its own auth callout, an engine: claude quick-start snippet, and 63 example workflows. There are no critical blockers. The friction is real but bounded — example coverage skews ~2:1 toward Copilot, and the single sharpest paper cut for this exact persona is that CLAUDE_CODE_OAUTH_TOKEN (the Claude Code / Max subscription token) is silently ignored; only a pay-as-you-go ANTHROPIC_API_KEY works.

Key finding: the docs are engine-neutral in structure but Copilot-first in defaults and density, and the Claude-Code-subscription auth path is a dead end that is not surfaced where users look first.

Persona Context

• GitHub ✅
• Claude Code ✅
• GitHub Copilot ❌
• Copilot CLI ❌

Severity Findings

No 🚫 Critical Blockers found. Claude setup is documented end-to-end: engine selection (quick-start.mdx:70), ANTHROPIC_API_KEY callout (quick-start.mdx:84-88), and a working engine: claude example (quick-start.mdx:129-133).

⚠️ Major Obstacles (3) — significant friction

M1 — Claude Code / Max OAuth token is unsupported and the failure is silent.
CLAUDE_CODE_OAUTH_TOKEN is not honored by the Claude engine; if set it is silently ignored, and there is no support for Claude Teams / Max subscription billing (reference/auth.mdx:121-123, reference/faq.md:337-339). This is the one gap that hits the Claude Code persona squarely: the token they already have does not work, and a pay-as-you-go Anthropic Console key is mandatory. The Quick Start does not warn about this, so a user pastes their OAuth token and gets a confusing inference failure.
Fix: add a one-line NOTE under the ANTHROPIC_API_KEY callout (quick-start.mdx:84-88): Claude Code / Max OAuth tokens are not supported — use a pay-as-you-go API key from the Anthropic Console.

M2 — Does the wizard write engine: claude into the added workflow?
add-wizard step 2 says Select an AI Engine and sets the secret (quick-start.mdx:67-73), but the sample daily-repo-status workflow ships with no engine field, and gh-aw defaults a missing engine to Copilot (engines.md:24). The docs never state whether choosing Claude in the wizard injects engine: claude into the .md. If it does not, a Claude-only user who selects Claude still runs against the Copilot default on their first run — the exact scenario captured in the historical attribution candidate issue #32423 (Quick Start sample workflow defaults to Copilot — Claude-only users will fail their first run, README.md:240).
Fix: state explicitly in step 2 whether the wizard rewrites the workflow engine: field, or instruct Claude users to confirm/add engine: claude before the first run.

M3 — Keyless Anthropic auth (WIF) is documented only in an ADR.
Workload Identity Federation support for Anthropic lives in docs/adr/35939-anthropic-wif-support-in-compiler.md and is absent from user-facing reference/auth.mdx. A Claude user wanting keyless auth has no setup steps and would not know ANTHROPIC_API_KEY can be omitted under WIF.
Fix: promote a short WIF section into reference/auth.mdx.

💡 Minor Confusion (4) — paper cuts

m1 — Copilot-first ordering. Engine lists and secret lists put Copilot/COPILOT_GITHUB_TOKEN first (quick-start.mdx:71). Harmless but reinforces a Copilot-default mental model.

m2 — custom engine is a misnomer. There is no literal engine: custom; custom means Copilot engine.command/engine.harness/BYOK overrides, all still riding on COPILOT_GITHUB_TOKEN unless BYOK provider creds are set (engines.md:231-265). A reader scanning for a generic custom engine auth path finds none.

m3 — web-search is engine-divergent but tools.md does not flag it inline. Native only on Codex (opt-in); every other engine, including Claude, gets web search only via MCP (tools.md:56-67, engines.md:40). The per-engine difference is not obvious at the tool documentation point.

m4 — Feature asymmetry is not summarized for newcomers. max-turns is Claude-only, max-continuations/custom-agents/harness are Copilot-only (engines.md:37-47). Useful, but there is no single what you give up by picking Claude line in the onboarding path.

Engine Comparison

Ratings out of 5 (5 = best documented experience for a non-Copilot user).

Engine	Setup	Examples	Auth	Score
Copilot (default)	4	5	4	4.3
Claude	4	4	3	3.7
Codex	3	2	3	2.7
Custom / BYOK	2	1	2	1.7

Rationale

• Copilot — best example density (126 explicit + 30 default ≈ 156 effective), but PAT setup is fiddly (user-account-only fine-grained PAT, Copilot license required).
• Claude — clean Console-key setup and a dedicated quick-start callout; docked for the silent OAuth-token dead end (M1) and ~2:1 fewer examples.
• Codex — works, but Quick Start gives no inline OPENAI_API_KEY/CODEX_API_KEY setup note (only Copilot and Anthropic get inline NOTEs at quick-start.mdx:77-88); just 14 examples.
• Custom/BYOK — no first-class engine, 0 standalone examples, auth threaded through Copilot BYOK env vars.

Tool Availability

All built-in tools documented in reference/tools.md are engine-agnostic — none are Claude-, Copilot-, or Codex-locked.

Class	Count	Tools
Engine-agnostic	12	edit, github, bash, web-fetch, playwright, cache-memory, repo-memory, qmd, agentic-workflows, cli-proxy, custom mcp-servers, tool timeout/startup-timeout
Unclear / divergent	2	web-search (Codex-native opt-in vs. via MCP elsewhere), copilot
Engine-locked	0	—

Notes: copilot is not a tool — it is the default engine; it appeared in the brief but has no tools: entry. safe-outputs is a top-level frontmatter section, not a tools: entry. agentic-workflows, playwright, and github are all confirmed engine-agnostic — good news for Claude users.

Authentication Gaps

Engine	Required secret	Documented?	Gap
Copilot	COPILOT_GITHUB_TOKEN	✅ inline NOTE	PAT must be user-account fine-grained + active Copilot license
Claude	ANTHROPIC_API_KEY	✅ inline NOTE	OAuth/Max token unsupported & silent (M1); WIF only in ADR (M3)
Codex	OPENAI_API_KEY (or CODEX_API_KEY)	⚠️ no inline quick-start note	precedence CODEX_API_KEY→OPENAI_API_KEY only in auth.mdx:143-145
Custom/BYOK	COPILOT_GITHUB_TOKEN (+ COPILOT_PROVIDER_*)	⚠️ scattered	no generic custom auth path; BYOK vars in engines.md only

Example Parity

Engine	Explicit examples	Notes
Copilot	126	+ 30 files with no engine field default to Copilot → ~156 effective
Claude	63	first-class but ~2:1 behind Copilot
Codex	14	smallest of the named engines
Custom	0	only appears in a shared include, not a standalone workflow

238 total .github/workflows/*.md. Claude examples are plentiful enough to learn from (e.g. api-consumption-report.md, ci-doctor.md, audit-workflows.md), so this is friction, not a blocker.

Recommended Actions

Priority 1 — Add a Quick Start NOTE that Claude Code / Max OAuth tokens are unsupported; only a pay-as-you-go ANTHROPIC_API_KEY works (fixes M1, the worst persona-specific trap).

Priority 2 — Clarify in add-wizard step 2 whether selecting Claude rewrites the workflow engine: field; if not, tell Claude users to add engine: claude before the first run (fixes M2).

Priority 3 — Promote Anthropic WIF from ADR into reference/auth.mdx (M3); add an inline Codex secret NOTE to Quick Start; add a short what differs if you pick Claude callout summarizing max-turns vs max-continuations and the web-search MCP requirement.

Conclusion

Can Claude Code users adopt gh-aw? Yes — comfortably. Claude is a documented, first-class engine with working examples and a clear secret-setup path; nothing forces a user toward Copilot. The remaining work is closing one sharp auth trap (the unsupported subscription OAuth token), removing a first-run ambiguity in the wizard, and surfacing WIF. None block adoption.

Overall adoption score: 8 / 10.

Methodology & trend tracking

Findings synthesized from four specialist passes (doc facts, per-engine auth, example counts, tool classification) over README.md and docs/src/content/docs/{setup,introduction,reference}. Counts grep-verified across .github/workflows/*.md. Historical signals (README.md:240-241) are attribution candidates — past closed issues, not current doc text — and may already be addressed. A trend snapshot for 2026-06-02 was written to cache-memory (claude-docs-review-trend.json); prior snapshots were not enumerable from the sandbox this run, so day-over-day deltas are unavailable.

References: §26823742776

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

• expires on Jun 3, 2026, 1:58 PM UTC

[github-actions[bot]]

This discussion was automatically closed because it expired on 2026-06-03T13:58:42.673Z.

Closed by Workflow