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

[github-actions[bot]]

Executive Summary

Reviewed as a Claude Code user (no Copilot). gh-aw's core path works without Copilot — --engine claude is documented and Claude has a first-class quick-start auth callout. Key finding, unchanged across 35 consecutive daily runs: Claude Code users get no zero-secret/org-billing auth shortcut equivalent to Copilot's copilot-requests: write, and the CLI/runtime silently defaults to Copilot the moment engine: is omitted or removed. Score: 7.5/10, 0 critical blockers.

Severity Findings

Critical Blockers: None. A Claude-only user can complete quick-start end-to-end.

Major Obstacles

1. No OAuth/PAT-free path for Claude. CLAUDE_CODE_OAUTH_TOKEN is explicitly unsupported and silently ignored — "Provider-based OAuth authentication (such as billing through a Claude Teams or Claude Max subscription) is not supported" (auth.mdx:205-207). Only a separately-billed ANTHROPIC_API_KEY (or WIF) works, vs. Copilot's zero-secret copilot-requests: write (auth.mdx:94-118, quick-start.mdx:132-139).
2. Silent Copilot default. If engine: is removed from frontmatter, "the runtime defaults to Copilot" (quick-start.mdx:116; confirmed how-they-work.mdx:26, "GitHub Copilot (default)"). A Claude user hand-editing frontmatter can silently lose their engine choice.
3. Auth depth is Copilot > Claude. Claude's ANTHROPIC_API_KEY section has no quota/rate-limit guidance and no troubleshooting beyond generic 401/403 (auth.mdx:187-209, auth.mdx:413-415); the WIF keyless alternative (auth.mdx:213-244) references external Anthropic Console setup with no step-by-step federation walkthrough and no token rotation/revocation guidance.
4. No cost/tradeoff framing. Quick-start presents Copilot's centralized-billing option and Claude's personal-key option side by side but never explains why one might cost more or less, or which fits an org (quick-start.mdx:132-139).

Minor Confusion

• Copilot-first ordering everywhere ("if you already have GitHub Copilot, start there," auth.mdx:19; Copilot listed first in every engine list, how-they-work.mdx:26) — no why-Claude-vs-Copilot guidance.
• web-search tool's default-off behavior is documented only for Codex (tools.md:67-68); ambiguous whether Claude/Gemini have the same restriction.
• Historically noted (persisting since ~2026-07-29): advanced config — engine.agent, max-continuations, Copilot-SDK/BYOK — is Copilot-exclusive and not flagged as such in the main engine comparison table, so Claude users discover the restriction by trial and error.
• custom engine has effectively zero standalone example coverage (only a shared snippet, shared/genaiscript.md), no dedicated auth section.

Engine & Tool Matrix

Engine	Setup	Examples (this run)	Auth	Score
Copilot (default)	Easiest — zero-secret copilot-requests: write or PAT	135 explicit (dominant; + majority of omitted-engine files default here)	copilot-requests: write / COPILOT_GITHUB_TOKEN PAT	9/10
Claude	Clear but requires separate billing; --engine claude flag documented quick-start.mdx:110	66 (2nd, near-parity in raw count this run)	ANTHROPIC_API_KEY or Anthropic WIF (no OAuth-token reuse)	7/10
Codex	OPENAI_API_KEY/CODEX_API_KEY, Azure/custom endpoint via engine.env	15	OPENAI_API_KEY (auth.mdx:281-319)	6.5/10
Custom	Overlay via engine.command/harness; no dedicated quick-start section	1 (no standalone workflow)	Undocumented, depends on harness	4/10

Tool parity is strong: doc-reader classified 10 of 11 core tools as engine-agnostic (edit, github, bash, web-fetch, playwright, cache-memory, repo-memory, qmd, agentic-workflows, cli-proxy — tools.md:20-151); only web-search has documented engine-specific behavior (disabled by default for Codex, tools.md:60-68). No Copilot-only or Claude-only core tools this run — the asymmetry is in advanced engine.* config, not the tool surface. (Note: this run's engine-example-counter returned an outlier 134 "omitted-engine" count vs. the ~35 historical baseline over 35 prior runs — likely a substring/methodology artifact; treat directionally, not as a step change.)

Auth Gaps

• Claude: ANTHROPIC_API_KEY (quick-start.mdx:142-148, auth.mdx:187-209) or Anthropic WIF (auth.mdx:213-244); CLAUDE_CODE_OAUTH_TOKEN explicitly rejected (auth.mdx:205-207). No quota guidance, no WIF step-by-step, no key-rotation instructions.
• Copilot: copilot-requests: write permission (no secret) preferred, or fine-grained PAT as COPILOT_GITHUB_TOKEN (auth.mdx:94-152) — richest, most validated path.
• Codex: OPENAI_API_KEY or CODEX_API_KEY, Azure/custom endpoint via OPENAI_BASE_URL (auth.mdx:281-319) — no deprecation timeline for the CODEX_API_KEY alias.
• Gemini: GEMINI_API_KEY or Google WIF/Vertex AI (auth.mdx:323-398) — WIF setup is externally-referenced, minimal inline detail.
• Custom: no dedicated auth section at all.

Recommended Actions

Priority 1

• Add a one-line callout in quick-start.mdx near the Claude tab clarifying there is no Claude equivalent to copilot-requests: write — set expectations before the user hits billing surprise.
• Move the "engine: omitted → defaults to Copilot" warning (quick-start.mdx:116) into the Prerequisites section, not buried mid-flow.

Priority 2

• Add explicit Copilot-only tags to engine.agent, max-continuations, and Copilot-SDK/BYOK rows in the engine comparison table so Claude users don't discover restrictions by trial and error.
• Expand auth.mdx:213-244 (Anthropic WIF) with a numbered federation-rule setup walkthrough matching the detail level of the Copilot PAT flow.

Priority 3

• Add a short "why pick Claude vs Copilot" note for teams evaluating options.
• Add at least one standalone custom engine example workflow.

References:

• §30748289808

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

• expires on Aug 3, 2026, 4:55 AM UTC-08:00