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

[github-actions[bot]]

Executive Summary

Good news for Claude Code users: gh-aw fully supports the Claude engine — there are no critical blockers. The tool layer is engine-agnostic and engine: claude is a first-class option with ~62 example workflows. The friction is positional: every default (CLI commands, quick-start, prerequisites) points at Copilot, and the single caveat most likely to trip a Claude Code user — CLAUDE_CODE_OAUTH_TOKEN is unsupported/ignored — is buried in auth.mdx, absent from the quick-start a newcomer actually reads.

Severity Findings (Critical → Major → Minor)

🚫 Critical Blockers

• None. Claude is fully documented and supported. ANTHROPIC_API_KEY path is clear (quick-start.mdx:84-87), engine: claude works in frontmatter (quick-start.mdx:138), and the entire tool surface is engine-neutral.

⚠️ Major Obstacles

1. OAuth/subscription billing silently unsupported. A Claude Code user typically authenticates via OAuth / Claude Max. CLAUDE_CODE_OAUTH_TOKEN is NOT supported and is ignored (auth.mdx:199-201,349) — but the quick-start never says this. The user will assume their existing Claude auth carries over and only discover otherwise after a failed run. Highest-impact gap.
2. Everything defaults to Copilot. Engine is default copilot (how-they-work.mdx:26, pkg/constants/engine_constants.go:36); gh aw init/new/add-wizard create Copilot-specific artifacts unless --engine claude is passed (cli.md:134,139,207). Claude is opt-in at every step but never surfaced as a prominent prerequisite.
3. Uneven example & feature parity. ~126 Copilot examples vs ~62 Claude. Several features are Copilot-only: engine.copilot-sdk, max-tool-denials, and max-continuations/autopilot mode. A Claude user copying a Copilot sample may hit unsupported fields.

💡 Minor Confusion

1. No "Why Claude vs Copilot?" guidance or capability comparison anywhere.
2. Manual (non-wizard) path: engine: claude step (quick-start.mdx:136-140) is decoupled from the ANTHROPIC_API_KEY step (only in earlier wizard NOTE, :84-87) — easy to miss the secret.
3. Claude web-search status undocumented — only Codex's default-disabled behavior is spelled out (tools.md:65-67).
4. Keyless WIF and ANTHROPIC_BASE_URL/proxy paths exist only in auth.mdx:195-271, not quick-start.

Engine & Tool Matrix

Engine	Setup docs	Examples	Auth	Score
Copilot (default)	Prominent, default everywhere	~126	Org-billing (no PAT) or COPILOT_GITHUB_TOKEN PAT	🟢 5/5
Claude	Supported, but opt-in (--engine claude)	~62	ANTHROPIC_API_KEY; WIF keyless (auth.mdx only)	🟡 3.5/5
Codex	Supported	~15	OPENAI_API_KEY/CODEX_API_KEY	🟡 3/5
Custom (no real id; overrides a base engine)	Sparse (engines.md)	1 (shared/genaiscript.md)	Inherits base engine secret	🔴 2/5

Tool surface is engine-agnostic (tool-classifier): of 15 documented tools, 13 engine-agnostic, 0 engine-exclusive, 2 engine-dependent — web-search: (Codex-specific default) and tools.timeout (Claude 60s / Codex 120s, tools.md:157). No tool is locked to Copilot, Claude, or Codex.

Parity observations

• Both engine: claude (string) and engine:+id: claude (block) forms are valid; Copilot examples skew to block form due to copilot-sdk options.
• no-system-prompt/bare maps to engine-specific flags (--no-custom-instructions copilot, --bare claude, --no-system-prompt codex) — same field, different behavior.
• max-turns and run-control have parity across engines; SDK/autopilot features do not.
• custom/pi engines barely represented (1 example), uneven coverage.

Auth Gaps (Claude Code user)

• ❌ Quick-start never warns that CLAUDE_CODE_OAUTH_TOKEN / Claude Max OAuth billing is unsupported — only in auth.mdx:199-201,349.
• ❌ Only the static ANTHROPIC_API_KEY path is in quick-start; keyless WIF (engine.auth, OIDC, id-token: write) lives only in auth.mdx:207-271.
• ❌ No quick-start mention of ANTHROPIC_BASE_URL / Anthropic-compatible proxy/Azure endpoints (auth.mdx:195-197).
• ❌ Manual engine: claude step not tied to the secret step → non-wizard users may skip ANTHROPIC_API_KEY.
• ❌ No Claude 401/403 troubleshooting in quick-start (auth.mdx:347-349).

Recommended Actions

Priority 1 — unblock the common case

• Add a quick-start callout: "Using Claude Code? CLAUDE_CODE_OAUTH_TOKEN and Claude Max OAuth billing are not supported — create an ANTHROPIC_API_KEY in the Anthropic Console." (fixes the rejig docs #1 friction).
• In the manual path, co-locate the engine: claude and ANTHROPIC_API_KEY steps.

Priority 2 — level the defaults

• Document --engine claude prominently in gh aw init/new/add-wizard examples, not just as a footnote.
• Add a short engine-comparison / "which engine?" table (auth model, supported features, web-search) so Claude users see parity and Copilot-only features (copilot-sdk, max-continuations) up front.

Priority 3 — fill reference gaps

• State Claude's web-search: default explicitly in tools.md alongside Codex's.
• Link quick-start → auth.mdx WIF/keyless and ANTHROPIC_BASE_URL sections.
• Add ≥1 end-to-end Claude sample mirroring a flagship Copilot example for copy-paste parity.

Methodology & limitations

Facts gathered by four sub-agents over README.md, quick-start.mdx, how-they-work.mdx, architecture.mdx, tools.md, cli.md, auth.mdx, engines.md, and .github/workflows/*.md. Note: cache-memory (/tmp/gh-aw/cache-memory/) was inaccessible from this run's sandbox (read+write blocked), so trend history could not be appended this run.

References: §28446391605

Generated by 📝 Claude Code User Documentation Review · 366.4 AIC · ⌖ 38.4 AIC · ⊞ 5.5K · ◷

• expires on Jul 1, 2026, 5:15 AM UTC-08:00

[mcdev7777]

Great review. The point about Claude being technically supported but not clearly surfaced in the quick-start feels especially important. I agree that adding a visible ANTHROPIC_API_KEY / unsupported Claude OAuth callout near the first Claude setup step would prevent a lot of first-run confusion. A small engine comparison table would also make the Copilot vs Claude vs Codex tradeoffs much easier to understand.

[github-actions[bot]]

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

A newer discussion is available at Discussion #42763.