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

[github-actions[bot]]

Executive Summary

gh-aw treats Claude Code as a first-class, fully documented engine — quick-start.mdx and cli.md give Claude users complete API-key setup steps on par with Copilot, and no doc gates any core feature behind Copilot specifically. The friction isn't inaccessibility, it's parity gaps: Claude Code's own OAuth session (claude login) is explicitly rejected everywhere auth is discussed, forcing a separate billed ANTHROPIC_API_KEY; and gh aw init bootstraps extra tooling (custom agent, MCP integration) only for the Copilot engine, with no explanation of what Claude users get instead.

Key finding: onboarding is Copilot-free but not Copilot-parity — a Claude Code user can complete quick-start end-to-end, but hits unexplained gaps in init tooling, web-search config, and deep auth (WIF) documentation.

Severity Findings

Critical Blockers / Major Obstacles / Minor Confusion

Critical Blockers

• Existing Claude Code login cannot be reused at all: CLAUDE_CODE_OAUTH_TOKEN (including a token from claude login) is explicitly rejected, three times over — README.md:47, quick-start.mdx:148-150, cli.md:259. A Claude Code user must provision a separate, billed ANTHROPIC_API_KEY before any workflow runs; there is no fallback path documented.

Major Obstacles

• gh aw init creates a custom agent (.github/agents/agentic-workflows.md) and enables MCP integration only for --engine copilot; for Claude/Codex/Gemini/Pi the docs just say "skip these Copilot-specific artifacts" with zero explanation of what a non-Copilot user should do instead — cli.md:151,155-158.
• Deep auth setup (especially Anthropic WIF) is named but never explained in any of the core docs — all defer to /gh-aw/reference/auth/ and /gh-aw/reference/engines/, which sit outside the reviewed doc set — how-they-work.mdx:38, quick-start.mdx:122,174, cli.md:273,949.
• tools.md:65 says "some engines require third-party MCP servers for web search" but only Codex's behavior is spelled out (tools.md:67); Claude/Gemini web-search requirements are left unspecified.
• Codex has only 8 example workflows vs. Claude's 37 and Copilot's ~72 effective (33 explicit + 39 files with no engine: line, which default to Copilot). Custom-engine has zero examples using the flat engine: custom form — the one example found (shared/genaiscript.md) uses a nested engine:\n id: custom shape invisible to simple doc search.

Minor Confusion

• architecture.mdx:15 omits Pi from the engine list while README.md:60 and how-they-work.mdx:26 include it — inconsistent engine inventory across docs.
• README.md:47's one-line Claude auth instruction is far terser than quick-start.mdx:144-150's full walkthrough — a user following only the README lacks the concrete gh secret set command.
• Pi's authentication is conditional on the model: provider prefix rather than a single fixed secret, making its requirement ambiguous at a glance — quick-start.mdx:166-169.

Engine & Tool Matrix

Engine	Setup Docs	Example Workflows	Auth	Score
Copilot	Full wizard walkthrough; exclusive init artifacts (custom agent + MCP integration) — cli.md:151	33 explicit + ~39 defaulted ≈ 72 effective	copilot-requests: write perm or COPILOT_GITHUB_TOKEN PAT — README.md:46	★★★★★ default, richest tooling
Claude	Full quick-start walkthrough (quick-start.mdx:144-150); README version terse (README.md:47); init skips custom-agent/MCP with no replacement documented	37	ANTHROPIC_API_KEY or Anthropic WIF; CLAUDE_CODE_OAUTH_TOKEN explicitly not supported — cli.md:259	★★★☆☆ solid engine support, OAuth-reuse blocker + init parity gap
Codex	Full quick-start walkthrough (quick-start.mdx:152-157); web-search disabled by default unless declared — tools.md:67	8	CODEX_API_KEY (precedence) or OPENAI_API_KEY	★★☆☆☆ documented but thin example coverage
Custom (MCP servers)	tools.md:184-224 documents mcp-servers: block; no standard-form engine: custom example	0 in flat form; 1 nested-form example outside main glob	Per-server secrets, e.g. SLACK_BOT_TOKEN — tools.md:190-194	★★☆☆☆ functional but nearly invisible in examples

Auth Gaps

• Deep per-engine auth (esp. Anthropic/Google WIF) is named but never explained inline — always deferred to /gh-aw/reference/auth/ or /gh-aw/reference/engines/, outside the core doc set — how-they-work.mdx:38, quick-start.mdx:122,174, cli.md:273,949.
• CLAUDE_CODE_OAUTH_TOKEN rejection is repeated across README.md:47, quick-start.mdx:148-150, cli.md:259 but never explains why (billing/security rationale), leaving Claude Code subscribers unsure why their existing login doesn't work.
• Claude's web-search MCP requirement is unspecified — only Codex gets an explicit carve-out (tools.md:65 vs :67).
• README.md:47's bootstrap-block auth instructions are noticeably thinner than quick-start.mdx's equivalent, so depth of guidance depends on which doc a user lands on first.

Recommended Actions

Priority 1

• Add a rationale callout next to every CLAUDE_CODE_OAUTH_TOKEN-unsupported note explaining that a separate billed ANTHROPIC_API_KEY is required even for existing Claude subscribers, to head off "why can't I reuse my login" confusion.

Priority 2

• Document what gh aw init produces for non-Copilot engines in place of the custom agent/MCP integration (cli.md:151) instead of just "skip."
• Extend tools.md:65-67's web-search guidance to explicitly cover Claude and Gemini, not just Codex.
• Grow Codex and custom-engine example coverage (currently 8 and ~0 respectively) so non-Copilot/Claude users have reference workflows to copy.

Priority 3

• Reconcile the engine inventory across architecture.mdx:15 (missing Pi) and README.md:60/how-they-work.mdx:26.
• Align README.md:47's terse Claude-auth blurb with quick-start.mdx:144-150, or link directly to it.

Generated by 📝 Claude Code User Documentation Review · agent · 128.3 AIC · ⌖ 5.21 AIC · ⊞ 5.8K · ◷

• expires on Aug 19, 2026, 4:40 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 #54003.

[sandeeppachauri]

🚀 Built a set of open-source accelerators for teams building on the Claude Agent SDK.

After shipping a few Claude-powered agents, I kept solving the same problems from scratch — credential handling, tracing, prompt config, orchestration. So I turned them into reusable, composable building blocks:

🔐 Auth resolution across console API keys, claude login OAuth, and OS-mounted sessions — one call, zero env-var wrangling
📊 Drop-in JSON-line tracing for tool calls & agent activity via hooks — no other dependencies
📝 Prompt-as-config pattern — scope/format/constraints live in YAML, enforced in code, editable without a redeploy
🧩 A master orchestrator with a single execute(payload) entry point, model routing with fallback, and a scaffold CLI to spin up new projects that inherit the whole stack instantly

Everything's independently installable, Python 3.10+, MIT-licensed.

🔗 github.com/sandeeppachauri/Accelerators
🔗 github.com/sandeeppachauri/claude-orchestration-accelerator

this is my attempt at reusable plumbing for the agentic AI era. Feedback and contributions welcome.

#ClaudeAgentSDK #AI #OpenSource #EnterpriseIntegration #SoftwareEngineering