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

[github-actions[bot]]

Executive Summary

gh-aw's documentation supports Claude Code as a first-class engine on paper (README.md:20, how-they-work.mdx:26), but a Claude Code user without Copilot access still hits real friction: gh aw init provisions Copilot-only artifacts by default, example coverage skews 1.76x toward Copilot, and one auth gap (CLAUDE_CODE_OAUTH_TOKEN) has now gone unresolved across 5 consecutive daily reviews. Onboarding is possible but not frictionless for a Copilot-free user.

Key finding: CLAUDE_CODE_OAUTH_TOKEN guidance remains sparse/misleading at cli.md:284 — unresolved since 2026-08-22.

Severity Findings

Critical / Major / Minor breakdown

Critical Blockers

• CLAUDE_CODE_OAUTH_TOKEN handling is under-documented and has produced a misleading auth error in prior runs; still only a passing mention at cli.md:284. Unresolved for 5 straight days (2026-08-22 → 2026-08-26).

Major Obstacles

• gh aw init creates Copilot-specific artifacts (.github/agents/agentic-workflows.md, .github/mcp.json, copilot-setup-steps.yml) by default; a Claude-only user must already know to pass --engine claude to skip them (cli.md:159, cli.md:176, cli.md:183-184).
• Example parity gap: Copilot has 111 workflow examples vs. Claude's 63 (1.76x) and Codex's 49; custom engine has 0 examples (.github/workflows/*.md scan).
• Anthropic WIF setup is name-dropped but not detailed inline — users are deferred to reference docs with no inline steps (how-they-work.mdx:33, quick-start.mdx:139-141).
• Per-engine MCP server support isn't spelled out; "some integrations use MCP" leaves it unclear which engines support which MCP servers (how-they-work.mdx:40-42).

Minor Confusion

• Trade-off between copilot-requests: write permission vs. COPILOT_GITHUB_TOKEN PAT isn't explained — unclear which a non-Copilot-org user should pick (how-they-work.mdx:32, quick-start.mdx:128-135).
• Codex web-search: docs say it's disabled by default and must be declared, but not what changes once enabled (tools.md:67).
• Pi's model: prefix routing (copilot/, anthropic/, openai/) has no documented fallback behavior for a missing/unrecognized prefix (how-they-work.mdx:36, quick-start.mdx:157).

Engine & Tool Matrix

Engine	Setup Clarity	Example Count	Auth Clarity	Score
Copilot (default)	Clear — org billing or PAT (quick-start.mdx:127-135)	111	Two paths documented, tradeoff unclear	4/5
Claude	Partial — ANTHROPIC_API_KEY documented, WIF deferred, OAuth token gap	63	Partial (see Critical)	2.5/5
Codex	Clear — OPENAI_API_KEY/CODEX_API_KEY (quick-start.mdx:142-147)	49	Clear	3.5/5
Custom	Undocumented per-engine tool support (ambiguous_entries)	0	N/A	1/5

Core tools (Edit, GitHub, Bash, Playwright, Cache/Repo Memory, Custom MCP) are documented as engine-agnostic (tools.md:20-205); the one engine-dependent exception is Codex web-search being off by default (tools.md:55-67). Parity observation from example scan: "Copilot has 111 examples vs Claude's 63 (1.76x higher coverage)... Claude Code users have substantially fewer workflow examples compared to Copilot users."

Auth Gaps

• Claude: ANTHROPIC_API_KEY steps exist (quick-start.mdx:138-141), but Anthropic WIF is only referenced, not walked through, and CLAUDE_CODE_OAUTH_TOKEN remains the recurring critical gap (cli.md:284).
• Codex: OPENAI_API_KEY/CODEX_API_KEY precedence stated but not deeply explained (how-they-work.mdx:34).
• Gemini: Google WIF mentioned as an alternative with no inline detail (quick-start.mdx:154).
• Pi: Auth is inferred from a model: string prefix — no documented behavior for malformed/missing prefixes (quick-start.mdx:157).
• No guidance anywhere on secret rotation/management for non-Copilot engines.

Recommended Actions

Priority 1 (fix now)

• Resolve or clearly document CLAUDE_CODE_OAUTH_TOKEN support/error behavior at cli.md:284 — this is now a 5-day-old unresolved blocker.
• Make gh aw init --engine claude (and other non-Copilot engines) equally prominent in quick-start.mdx, not just discoverable via cli.md flags.

Priority 2 (next)

• Add inline Anthropic WIF and Google WIF walkthroughs instead of deferring to reference docs.
• Grow Claude/Codex workflow examples toward parity with Copilot's 111, or explicitly label examples as "engine-portable."

Priority 3 (polish)

• Document the copilot-requests permission vs. COPILOT_GITHUB_TOKEN decision criteria.
• Specify Pi's fallback behavior for unrecognized model: prefixes and Codex's behavior once web-search is enabled.

References:

• §32968947993

Generated by 📝 Claude Code User Documentation Review · claude · agent · 104.4 AIC · ⌖ 4.56 AIC · ⊞ 6.3K · ◷

• expires on Aug 27, 2026, 4:39 AM UTC-08:00