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

[github-actions[bot]]

Executive Summary

A Claude Code user can adopt gh-aw — Claude is a first-class engine with quick-start ANTHROPIC_API_KEY setup, and Claude actually leads inline engine: claude declarations in real workflows (48 vs Copilot's 36 in .github/workflows). No critical blockers (overall score 7.5/10, stable across 9 reviews). Key finding: the single most persona-relevant obstacle persists unchanged — CLAUDE_CODE_OAUTH_TOKEN (the Claude Pro/Max/Teams subscription auth Claude Code users already have) is explicitly unsupported and silently ignored; only ANTHROPIC_API_KEY or WIF work, and this caveat lives in reference/auth.mdx:199-201, never surfaced in quick-start.

Severity Findings (Critical → Major → Minor)

🚫 Critical Blockers

None. Claude has documented prerequisites, quick-start auth (quick-start.mdx:84-87), and runnable examples. A Claude Code user is not blocked from getting started.

⚠️ Major Obstacles

1. CLAUDE_CODE_OAUTH_TOKEN silently ignored — reference/auth.mdx:199-201. The exact Claude Code persona (Pro/Max/Teams subscriber) assumes existing subscription/OAuth billing works. It does not — only ANTHROPIC_API_KEY (or WIF, auth.mdx:207-271) works, and the caveat is absent from quick-start.mdx. Fix: add a NOTE in quick-start "Select an AI Engine" stating Claude needs an API key, not a Claude subscription token.
2. gh aw init defaults to Copilot artifacts — setup/cli.md:133,139-140. Init creates Copilot-specific skill/agent files unless --engine claude is passed, but quick-start never shows that flag. Fix: show gh aw init --engine claude in quick-start.
3. Engine omitted = silent Copilot default; secret callouts cover only Copilot+Anthropic — quick-start.mdx:71,84-91, how-they-work.mdx:26. Codex/Gemini have no inline secret NOTE. Fix: add per-engine secret callouts or a 4-row table.

💡 Minor Confusion

4. Copilot-first ordering everywhere; no "why Claude vs Copilot" guidance — README.md:40, how-they-work.mdx:26. No capability/cost comparison to help a Claude user justify the choice.
5. custom engine has zero standalone examples/declarations — only via per-engine *_BASE_URL env (reference/engines.md:153-217); no quick-start section. There is no first-class "custom" engine — it maps to custom endpoints / Copilot BYOK.

Engine & Tool Matrix

Engine	Setup in quick-start	Real examples (.github/workflows inline)	Auth	Score
Copilot (default)	✅ NOTE + org-billing path	36 inline / 204 combined	copilot-requests: write (no PAT) or COPILOT_GITHUB_TOKEN PAT	9
Claude	✅ ANTHROPIC_API_KEY NOTE	48 inline / 74 combined	ANTHROPIC_API_KEY or WIF keyless. ⚠️ OAuth token ignored	7
Codex	⚠️ listed, no inline NOTE	9 inline / 19 combined	OPENAI_API_KEY (or CODEX_API_KEY)	5
Custom	❌ none	0	per-engine *_BASE_URL + secret; Copilot BYOK	2

Tools (reference/tools.md): 15 documented — 14 engine-agnostic, 1 unclear (web-search: Codex disabled-by-default/opt-in via -c web_search="disabled", all other engines via MCP — tools.md:62-67, engines.md:40). Zero copilot-only, claude-only, or codex-only tools. Per-engine timeout defaults (Claude 60s / Codex 120s, tools.md:157) are the only engine-specific values. Parity: Claude is well-represented in real runnable workflows (leads inline form); Copilot dominates docs snippets; Codex under-represented; custom has no copyable example.

Auth Gaps

auth-doc-extractor findings

• Biggest surprise: CLAUDE_CODE_OAUTH_TOKEN / Claude Max-Teams subscription billing explicitly unsupported & silently ignored — auth.mdx:199-201,349. Only ANTHROPIC_API_KEY or WIF work.
• Quick-start details only COPILOT_GITHUB_TOKEN + ANTHROPIC_API_KEY; no step-by-step Codex/Gemini NOTE, and the recommended copilot-requests: write (no-secret) path is buried in auth.mdx:92-116, so new users set up a PAT unnecessarily — quick-start.mdx:71-91.
• Codex CODEX_API_KEY-over-OPENAI_API_KEY precedence only in auth.mdx:289-291; engines.md:18 table omits the alternative.
• No consolidated "custom engine" auth page; user must infer from engines.md:153-217.
• GEMINI_API_KEY referenced as prerequisite (quick-start.mdx:29) but has no inline setup NOTE like Copilot/Anthropic.

Recommended Actions

Priority 1 (close the persona gap): Add a quick-start NOTE that Claude requires ANTHROPIC_API_KEY (or WIF) — a Claude subscription / CLAUDE_CODE_OAUTH_TOKEN will not work. This 9-run-persistent gap is the single highest-leverage fix for Claude Code adopters.

Priority 2: Surface gh aw init --engine claude in quick-start, and replace the Copilot+Anthropic-only secret callouts with a 4-engine secret table (incl. Codex/Gemini); document that omitting engine: silently defaults to Copilot.

Priority 3: Add a brief "choosing an engine" comparison (capabilities/cost) and at least one custom/BYOK example workflow.

References: §28029183178

Generated by 📝 Claude Code User Documentation Review · 359.9 AIC · ⌖ 37.3 AIC · ⊞ 5.4K · ◷

• expires on Jun 24, 2026, 5:32 AM UTC-08:00

[github-actions[bot]]

Smoke ping for run 28030364860. ✅

Warning

Firewall blocked 6 domains

The following domains were blocked by the firewall during workflow execution:

• accounts.google.com
• android.clients.google.com
• clients2.google.com
• contentautofill.googleapis.com
• safebrowsingohttpgateway.googleapis.com
• www.google.com

To allow these domains, add them to the network.allowed list in your workflow frontmatter:

network:
  allowed:
    - defaults
    - "accounts.google.com"
    - "android.clients.google.com"
    - "clients2.google.com"
    - "contentautofill.googleapis.com"
    - "safebrowsingohttpgateway.googleapis.com"
    - "www.google.com"

See Network Configuration for more information.

📰 BREAKING: Report filed by Smoke Copilot · 147.2 AIC · ⌖ 13.2 AIC · ⊞ 19.2K · ◷

[github-actions[bot]]

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

A newer discussion is available at Discussion #41222.