[claude-code-user-docs-review] Claude Code User Documentation Review - 2026-08-12

[github-actions[bot]]

Executive Summary

gh-aw's docs are functionally complete for Claude Code users — Claude has first-class engine support, its own auth secret (ANTHROPIC_API_KEY), and appears in every engine list — but the docs are written Copilot-first: Copilot gets the fullest walkthroughs, the most worked examples, and is framed as the path requiring "no extra setup." A Claude Code user (no Copilot, no Copilot CLI) can succeed, but hits more friction and fewer worked examples than a Copilot user at nearly every step. Key finding: Copilot outnumbers Claude ~2.3x in .github/workflows/*.md example coverage (141 vs 62 engine: directives), and the add-wizard auth flow documents Copilot's PAT mechanics in full while Claude gets one generic sentence.

Severity Findings

Critical / Major / Minor (click to expand)

Critical Blockers

• Claude Code's native subscription auth (claude login → CLAUDE_CODE_OAUTH_TOKEN) is explicitly rejected with no alternative offered for users who only have a Claude.ai subscription (not separate Anthropic Console API billing). A Claude Code user's natural assumption — "I'm already logged in, this should just work" — is wrong, and the docs don't soften the landing. (README.md:41, docs/src/content/docs/setup/quick-start.mdx:148-150, docs/src/content/docs/setup/cli.md:259)

Major Obstacles

• add-wizard documents Copilot's PAT flow in full detail (auto-opened prefilled token page, scope/resource-owner guidance, revalidation behavior) but Claude/Codex/Gemini/Pi share one generic sentence ("Prompts for missing API keys and secrets"). (docs/src/content/docs/setup/cli.md:169 vs :180)
• gh aw init --engine claude is documented only as skipping "Copilot-specific artifacts" — it never states what (if anything) is generated in their place for Claude. (docs/src/content/docs/setup/cli.md:151)
• Worked examples in .github/workflows/*.md skew heavily Copilot: 141 engine: copilot directives vs 62 claude and 16 codex. Smoke tests alone show 9 Copilot variants (Azure OpenAI key/Entra auth, ARM, MAI backend, SDK mode, sub-agents) vs 3 for Claude and 2 for Codex — a Claude user has no analogous template for equivalent auth/runtime permutations.
• web-search: tool support is called "engine-dependent," but only Codex's behavior (disabled by default, needs explicit declaration) is spelled out. Nothing states whether Claude Code has native web search or needs a third-party MCP server. (docs/src/content/docs/reference/tools.md:62-67)

Minor Confusion

• tools.timeout defaults are given for Claude (60s) and Codex (120s) only — Copilot/Gemini/Pi defaults are silently omitted, making the "applies to all tools" framing feel incomplete. (docs/src/content/docs/reference/tools.md:157)
• Supported-engine lists disagree: architecture.mdx:15 lists Copilot/Claude/Codex/Gemini (no Pi), while how-they-work.mdx:26 and README.md:54 list Pi as a fifth built-in engine — unclear if Pi shares the same security guarantees.
• No literal engine: custom exists anywhere in .github/workflows/*.md; the only "custom" construct found is a nested id: custom in shared/genaiscript.md, making the "Custom" engine class effectively undocumented by example.
• The CLI troubleshooting table (docs/src/content/docs/setup/cli.md:1008-1019) has no Claude-specific entries (e.g., invalid ANTHROPIC_API_KEY, WIF misconfiguration), unlike the depth given to Copilot auth issues elsewhere.

Engine & Tool Matrix

Engine	Setup Detail	Worked Examples	Auth	Score
Copilot	Full (PAT flow, wizard walkthrough, copilot-requests: write) — cli.md:169-180	141 directives, 9 smoke variants	copilot-requests: write or COPILOT_GITHUB_TOKEN — how-they-work.mdx:32	9/10
Claude	Partial — auth steps clear, but wizard/init non-Copilot behavior generic — cli.md:151,180	62 directives, 3 smoke variants	ANTHROPIC_API_KEY or Anthropic WIF; OAuth not supported — README.md:41	6/10
Codex	Partial, best-documented non-Copilot engine (web-search caveat, timeout default, TOML MCP quirk) — tools.md:62-67,157,181	16 directives, 2 smoke variants	CODEX_API_KEY (precedence) or OPENAI_API_KEY — quick-start.mdx:152-157	6/10
Custom	Not a real engine option; only custom MCP servers / MCP Scripts as extension points — tools.md:184, how-they-work.mdx:67	1 directive (nested id: custom)	N/A	3/10 (mislabeled expectation)

Tool classification (tools.md) is otherwise engine-agnostic and consistent (edit, bash, github, playwright, cache-memory, etc. all apply uniformly) — the imbalance is concentrated in auth walkthroughs and worked examples, not the tool reference itself.

Auth Gaps

• No subscription-only path for Claude: docs state OAuth tokens are ignored but don't redirect subscription users to a workable alternative (e.g., clarifying that a paid Anthropic Console API key is a separate purchase from a Claude.ai/Claude Code subscription). (quick-start.mdx:148-150)
• Asymmetric wizard documentation: Copilot's add-wizard auth mechanics get a full paragraph; every other engine shares one sentence. (cli.md:169 vs :180)
• gh aw init engine parity gap: unclear what artifacts (if any) get created for Claude/Codex/Gemini/Pi vs Copilot's skill + custom agent files. (cli.md:151)
• Web-search ambiguity: "engine-dependent" is asserted but only resolved for Codex. (tools.md:62-67)

Recommended Actions

Priority 1 (blocks adoption)

1. Add a short note clarifying that Anthropic Console API billing is separate from a Claude.ai/Claude Code subscription, and that OAuth tokens can't bridge that gap — right where the rejection is stated (quick-start.mdx:148-150).

Priority 2 (major friction)
2. Expand add-wizard docs with equivalent step-by-step detail for Claude/Codex/Gemini/Pi, matching the Copilot PAT walkthrough (cli.md:180).
3. Document what gh aw init --engine claude actually generates (cli.md:151).
4. Resolve web-search support explicitly per engine, not just Codex (tools.md:62-67).
5. Add 2–3 Claude-focused smoke-test examples covering auth/runtime variants analogous to the Copilot set.

Priority 3 (polish)
6. Reconcile the Pi-inclusion discrepancy between architecture.mdx:15 and how-they-work.mdx:26.
7. Fill in tools.timeout defaults for Copilot/Gemini/Pi (tools.md:157).
8. Add Claude-specific rows to the CLI troubleshooting table (cli.md:1008-1019).

---

Findings appended to review-history.jsonl in cache-memory for trend tracking (first run — no prior baseline to compare).

References:

• §31597056301

Generated by 📝 Claude Code User Documentation Review · agent · 167.2 AIC · ⌖ 38.8 AIC · ⊞ 5.3K · ◷

• expires on Aug 13, 2026, 4:44 AM UTC-08:00