[claude-code-user-docs-review] 🔍 Claude Code User Documentation Review - 2026-07-01

[github-actions[bot]]

Executive Summary

gh-aw is fully usable by Claude Code users with zero Copilot access — Claude is a first-class engine, its ANTHROPIC_API_KEY setup is spelled out in the quick start, and all 14 documented tools are engine-agnostic (README.md:40, quick-start.mdx:71,84-88). No critical blockers (0 for the 15th consecutive run, score 7.5/10). The single most persona-relevant gap is unchanged: CLAUDE_CODE_OAUTH_TOKEN is silently ignored and this caveat lives only in the auth reference / FAQ, never in the quick start — exactly where a Claude Pro/Max/Teams subscriber would look.

Severity Findings

Critical / Major / Minor (click to expand)

🚫 Critical Blockers — none. A Claude Code user can install, authenticate, and run without any Copilot product.

⚠️ Major Obstacles (3, all persistent):

1. OAuth token silently ignored. CLAUDE_CODE_OAUTH_TOKEN (used by Claude Pro/Max/Teams subscriptions) is not supported — "it will be ignored — configure ANTHROPIC_API_KEY instead" (auth.mdx:199-201, also auth.mdx:349, faq.md:368). This caveat is absent from quick-start.mdx, so a Claude-subscription user sets the token they already have and hits an opaque 401. This is the top hit on the exact reviewer persona.
2. gh aw init / add-wizard default to Copilot artifacts. Non-Copilot engines require --engine claude to skip Copilot-specific scaffolding (cli.md:135, cli.md:164), but this flag is not surfaced in the quick-start add flow — only in the CLI reference.
3. Omitting engine: silently defaults to Copilot (~35 example files rely on this; billing.md:20-22). The quick-start inline secret callouts detail Copilot + Anthropic thoroughly; Codex/Gemini are thinner or link-only (quick-start.mdx:71,84-88).

💡 Minor Confusion:

• Copilot-first nudge in prerequisites — "If you already have GitHub Copilot, start there" (quick-start.mdx:29); no "why Claude vs Copilot" guidance.
• WIF keyless auth for Claude exists (auth.mdx:207-271) but is not surfaced in the quick start.
• custom engine has 1 example (shared/genaiscript.md, a reusable include), no standalone workflow, no dedicated auth section.

Engine & Tool Matrix

Engine	Setup docs	Examples (.github/workflows)	Auth in quick-start	Score
Copilot (default)	Full callout + org-billing path	129 (93 object / 36 inline)	✅ COPILOT_GITHUB_TOKEN + org billing	9/10
Claude	Full callout	60 (9 object / 51 inline — leads)	✅ ANTHROPIC_API_KEY (WIF not surfaced)	8/10
Codex	No dedicated callout	14	⚠️ OPENAI_API_KEY, link only	6/10
Custom	None	1 (shared include)	🚫 undocumented	3/10

Tools: 15 documented, 14 engine-agnostic, 0 Copilot-only, 0 Claude-only. Only web-search: is engine-dependent (Codex disabled-by-default; some engines need an MCP server — tools.md:62-67). tools.timeout cites per-engine defaults (Claude 60s / Codex 120s, tools.md:157) but applies to all. No tool is inaccessible to Claude users.

Parity: Claude reaches near-parity with Copilot across analysis, reporting, and safe-output families (e.g. smoke-claude.md, api-consumption-report.md, ci-doctor.md), and leads Copilot in the inline engine: claude form (51 vs 36). Copilot uniquely covers default-only concerns: org-billing auth modes, AOAI/ARM/SDK smoke matrix, and workflow-call plumbing.

Auth Gaps

Per-engine auth extraction

• Claude: ANTHROPIC_API_KEY — fully documented (quick-start.mdx:71,84-88). ✅ Only gap: OAuth-token caveat + WIF alternative not surfaced here.
• Copilot: COPILOT_GITHUB_TOKEN (fine-grained PAT, Copilot Requests: Read) or org billing via permissions.copilot-requests: write — the PAT-free convenience path is Copilot-only (quick-start.mdx:78-81, cli.md:164).
• Codex: OPENAI_API_KEY mentioned but no step-by-step callout box like Copilot/Claude have (quick-start.mdx:71).
• Custom: no required secret, no setup steps, no scope notes documented anywhere in quick-start or cli.md.

Recommended Actions

Priority 1 — close the OAuth trap (fixes the #1 persistent finding): Add a short NOTE in quick-start.mdx Step 2 Claude section: "CLAUDE_CODE_OAUTH_TOKEN (Claude Pro/Max/Teams) is not supported — use ANTHROPIC_API_KEY." Costs 2 lines; eliminates the opaque 401 for the exact persona.

Priority 2 — de-Copilot the default path: In quick-start's add/init step, show gh aw init --engine claude alongside the default and state plainly that omitting engine: selects Copilot. Add Codex/Gemini secret callouts to match Copilot/Anthropic depth.

Priority 3 — polish: Add a one-paragraph "choosing an engine" section (why Claude vs Copilot), surface Claude WIF keyless auth (auth.mdx:207-271) in the quick start, and add a minimal custom engine auth note.

Trend: Stable across all 15 runs — score 7.5, 0 critical, same 3 major gaps. The OAuth-token gap is the highest-leverage unaddressed fix.

References: §28520373607

Generated by 📝 Claude Code User Documentation Review · 310.4 AIC · ⌖ 35 AIC · ⊞ 5.5K · ◷

• expires on Jul 2, 2026, 5:28 AM UTC-08:00

[github-actions[bot]]

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

A newer discussion is available at Discussion #42972.