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

[github-actions[bot]]

Executive Summary

As a Claude Code user, I can adopt gh-aw — Claude is a first-class engine with documented ANTHROPIC_API_KEY setup. But every default points at Copilot, so a Claude user must actively fight the defaults at each step. Key finding: removing engine: from frontmatter silently reverts the runtime to Copilot with no warning or verification step (quick-start.mdx:75), and gh aw init generates Copilot-specific artifacts unless you know to pass --engine claude (cli.md:148).

Severity Findings (Critical → Major → Minor)

🔴 Critical Blockers

1. Silent Copilot fallback. If engine: is removed, the runtime defaults to Copilot with no warning — a Claude user can unknowingly run (and be billed) on Copilot. quick-start.mdx:75. Fix: emit a compile-time warning and document a gh aw status/verify step.
2. gh aw init defaults to Copilot artifacts. Claude users must already know to pass --engine claude to skip them. cli.md:148,153. Fix: prompt for engine during init, or surface this in the quick-start happy path.

🟠 Major Obstacles

1. No per-engine auth at first mention. how-they-work.mdx:26 and architecture.mdx:42 name four engines but give zero secret/setup guidance; auth is deferred to a linked reference. Fix: inline the ANTHROPIC_API_KEY step near first mention.
2. web-search MCP dependency unnamed. Docs say it "requires third-party MCP servers for some engines" without naming which or how to configure. tools.md:65. A Claude user cannot tell if web-search works out of the box. Fix: name the engines and link config.
3. Example imbalance. Copilot 124 vs Claude 61 vs Codex 15 vs Custom 0; +33 no-engine files default to Copilot (~157 effective). Claude users have far fewer copyable patterns. Fix: add engine-neutral examples or a Claude variant set.
4. Engine-varying defaults are scattered. Tool timeout (Claude 60s / Codex 120s, tools.md:157) and Codex web-search-off (tools.md:67) appear in prose with no single per-engine defaults table.

🟡 Minor Confusion

1. web-search and tools.timeout are engine-ambiguous in the tools reference. tools.md:65,157.
2. COPILOT_GITHUB_TOKEN is a separate token from GITHUB_TOKEN (quick-start.mdx:81) — presented up front, but noise for Claude users.
3. Retired releases 0.68.4–0.71.3 note (README.md:52) is engine-agnostic and fine.

Engine & Tool Matrix

Engine	Setup	Examples	Auth secret	Score
Copilot	default (no flag)	124 (+33 no-engine ≈157)	copilot-requests: write or COPILOT_GITHUB_TOKEN	⭐⭐⭐
Claude	--engine claude / engine: claude	61	ANTHROPIC_API_KEY	⭐⭐
Codex	--engine codex	15	OPENAI_API_KEY / CODEX_API_KEY	⭐
Custom	undocumented in top-level examples	0 (only shared/genaiscript.md)	—	▫️

Parity observations (from workflow scan): Copilot dominates ~2:1 over Claude; Codex ~8× fewer than Copilot; Custom has zero standalone examples; 33 engine-less files silently inflate Copilot's real footprint. The ecosystem skews heavily to Copilot even though the docs describe all engines as peers.

Tool classification: 12 engine-agnostic, 2 ambiguous (web-search, tools.timeout), 0 Copilot-only. Good news — the tools are genuinely engine-neutral; the friction is in defaults, examples, and auth surfacing, not tool availability.

Auth Gaps

Required secrets by engine are correct where documented — Claude: ANTHROPIC_API_KEY (quick-start.mdx:98); Codex: OPENAI_API_KEY/CODEX_API_KEY (:102); Gemini: GEMINI_API_KEY (:112). Gaps for a Claude user:

• how-they-work.mdx:26 / architecture.mdx:42 name engines but give no auth instructions.
• web-search MCP dependency for "some engines" is unnamed (tools.md:65).
• Concrete secret names live only in a linked Authentication reference, not inline in setup (README.md:39, cli.md:268).
• No documented verification step to catch a Claude user who loses their engine setting and silently falls back to Copilot (quick-start.mdx:75).

Recommended Actions

Priority 1 — Add a compile-time warning + gh aw status/verify step for the silent Copilot fallback; prompt for engine in gh aw init instead of defaulting to Copilot artifacts.

Priority 2 — Inline a per-engine auth + defaults table near the first engine mention in how-they-work.mdx/architecture.mdx; name the engines that need a third-party MCP server for web-search.

Priority 3 — Rebalance examples: add a Claude-engine example set (or engine-neutral variants) so Claude users have copyable patterns comparable to Copilot's 124.

Note: cache-memory (review-history.jsonl) write was blocked by the session sandbox (path outside working dir), so trend history could not be updated this run.

Generated by 📝 Claude Code User Documentation Review · 302.7 AIC · ⌖ 35 AIC · ⊞ 6.2K · ◷

• expires on Jul 17, 2026, 5:06 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 #46245.