[claude-code-user-docs-review] 🔍 Claude Code User Documentation Review - 2026-10-05

[github-actions[bot]]

Executive Summary

A Claude Code user (no Copilot, no Copilot CLI) can get a gh-aw workflow running with ANTHROPIC_API_KEY, but the experience is second-class to Copilot's: gh aw init auto-scaffolds a custom agent file + MCP wiring only for Copilot, example coverage is ~1.9x richer for Copilot, and keyless (WIF) auth is link-only for Claude vs. fully inline for Copilot. Key finding: no critical blockers remain (0 for the current streak), but the gh aw init artifact-parity gap is now the longest-standing unresolved major obstacle across multiple consecutive daily reviews.

Severity Findings

Critical Blockers (0) / Major Obstacles (4) / Minor Confusion (3)

Critical Blockers: None found this run.

Major Obstacles:

1. gh aw init artifact-parity gap — Copilot gets an auto-generated custom agent file (.github/agents/agentic-workflows.md) and MCP wiring (.github/mcp.json, copilot-setup-steps.yml); Claude/Codex users are told only to "author an agent file in your own agent's format" with no template. — docs/src/content/docs/setup/cli.md:139-140
2. Example/smoke-test parity gap — Claude has 58 example workflows vs. Copilot's 112 (~1.93x) and Codex's 77 (~1.33x); smoke-test auth variants are 2 (smoke-claude*.md) vs. 9 (smoke-copilot-*.md), a 4.5x depth gap for learning-by-example. — engine-example-counter scan of .github/workflows/*.md
3. Anthropic WIF is link-only/one-sentence — Copilot's two auth paths (org billing, PAT) are fully inline with numbered steps; Claude's keyless WIF option gets one sentence and a link-out for full detail. — docs/src/content/docs/setup/quick-start.mdx:149 vs. :133-141
4. No path for Claude.ai subscription-only users — CLAUDE_CODE_OAUTH_TOKEN (from claude login) is explicitly documented as unsupported and silently ignored, failing with a CLI error that never mentions the token; only ANTHROPIC_API_KEY or enterprise WIF work. — docs/src/content/docs/setup/quick-start.mdx:151, docs/src/content/docs/setup/cli.md:240

Minor Confusion:

1. tools.timeout default (60s) documented only for Claude/Codex; Copilot/Gemini/Pi defaults unstated. — docs/src/content/docs/reference/tools.md:237
2. web-fetch standalone per-engine behavior ambiguous outside Codex's combined web-search/web-fetch model. — docs/src/content/docs/reference/tools.md:126-128
3. Pi's extra required config (tools.github.mode: gh-proxy, tools.cli-proxy: true) stated as a unique requirement with no rationale given. — docs/src/content/docs/setup/quick-start.mdx:175

Engine & Tool Matrix

Engine	Setup (inline vs. link)	Examples	Auth	Score
Copilot	Fully inline (org billing + PAT steps)	112 workflows, 9 smoke variants	COPILOT_GITHUB_TOKEN or org billing, inline	9/10
Claude	API key inline; WIF link-only; final "complete setup" is a bare link	58 workflows, 2 smoke variants	ANTHROPIC_API_KEY inline; OAuth subscription token unsupported	6/10
Codex	API key inline; CODEX_API_KEY override noted	77 workflows	OPENAI_API_KEY/CODEX_API_KEY inline	7/10
Custom/Other (Pi, Gemini, aider, goose, etc.)	Mixed; Pi needs extra proxy flags unexplained	32 (Pi) down to 2-4 each for long-tail engines	Varies by model: provider prefix	5/10

Tool classification (from reference/tools.md): most tools (edit, github, bash, playwright, cache-memory, etc.) are engine-agnostic. Two tools are engine-differentiated: web-search (opt-in for Codex/Claude/Copilot, absent for Gemini/Pi) and tools.timeout (documented only for Claude/Codex). This gives a 14 all-engine / 2 engine-differentiated / 2 ambiguous breakdown — the ambiguous entries (web-fetch standalone behavior, Pi's proxy flags) are the main source of Minor Confusion above.

Auth Gaps

• Claude: ANTHROPIC_API_KEY is the clear, fully-inline path. Anthropic WIF (keyless) is mentioned in one sentence with a link for actual setup steps (quick-start.mdx:149). CLAUDE_CODE_OAUTH_TOKEN from claude login is explicitly unsupported and fails silently with a misleading CLI error (quick-start.mdx:151, cli.md:240) — this remains the most consequential documented (not silent) gap for a Claude Code user trying to reuse their existing subscription login.
• Copilot: Two fully inline auth paths — organization billing (adds copilot-requests: write) or a fine-grained PAT stored as COPILOT_GITHUB_TOKEN — both with numbered steps in the same section.
• Codex: OPENAI_API_KEY inline; CODEX_API_KEY override noted inline.
• Gemini: GEMINI_API_KEY inline; Google WIF given the same brief-inline/link-for-detail treatment as Anthropic WIF.
• Pi: Auth is selected indirectly via a model: provider prefix (copilot/, anthropic/, openai/), riding on whichever underlying engine's credentials are configured — not a distinct auth story of its own.

Recommended Actions

Priority 1 (blocks confident adoption):

• Add an inline Claude/Codex agent-file template (or gh aw init --engine claude scaffolding) so non-Copilot users get the same turnkey agent + MCP wiring Copilot gets. (cli.md:139-140)
• Surface the CLAUDE_CODE_OAUTH_TOKEN limitation as a proactive warning in the quick-start auth step itself, not only in a later gotchas note, so Claude.ai subscribers don't hit a misleading CLI error. (quick-start.mdx:151)

Priority 2 (friction, workaround exists):

• Expand Anthropic/Google WIF from one sentence to the same inline numbered-step treatment Copilot's PAT path gets. (quick-start.mdx:149, :169)
• Add a handful of Claude-specific smoke/auth-variant example workflows to close the 2-vs-9 smoke-test gap.

Priority 3 (polish):

• State tools.timeout and web-fetch default behavior explicitly for every engine, not just Claude/Codex. (tools.md:126-128,237)
• Add a one-line rationale for Pi's gh-proxy/cli-proxy requirement. (quick-start.mdx:175)

Generated by 📝 Claude Code User Documentation Review · claude · agent · 329.9 AIC · ⌖ 4.07 AIC · ⊞ 5.2K · ◷

• expires on Oct 6, 2026, 4:56 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 #66142.