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

[github-actions[bot]]

Executive Summary

I reviewed the gh-aw documentation as a developer who uses Claude Code but does not use GitHub Copilot or the Copilot CLI. Overall verdict: Claude users can successfully adopt gh-aw, but the Quick Start path is meaningfully more friction-laden for non-Copilot users than it needs to be.

Key Finding: The reference documentation (engines.md, auth.mdx) is genuinely engine-agnostic and well-structured — engine: claude is a fully supported, first-class option with its own auth section, BYOK guidance, and a Claude-only max-turns feature. However, the onboarding surface area (README.md, quick-start.mdx, index.mdx, architecture.mdx, examples) is Copilot-first: examples reference engine: copilot roughly 7× more often than engine: claude, the only engine-specific setup callout in the Quick Start is for COPILOT_GITHUB_TOKEN, and the security architecture diagram literally renders "Copilot CLI" as the agent box.

Overall Assessment Score: 7/10 — Adopt-able with friction, not blocked.

---

Persona Context

I reviewed this documentation as a developer who:

• ✅ Uses GitHub for version control
• ✅ Uses Claude Code as primary AI assistant
• ❌ Does NOT use GitHub Copilot
• ❌ Does NOT use Copilot CLI
• ❌ Does NOT have a Copilot subscription

---

Question 1: Onboarding Experience

Can a Claude Code user understand and get started with gh-aw?

Mostly yes — the Prerequisites in quick-start.mdx (line 29) explicitly list four engine options including "Anthropic Claude", and add-wizard is described as letting you "Select an AI Engine - Choose between Copilot, Claude, Codex, or Gemini." A Claude user reading top-to-bottom will see Claude is supported.

However, the Quick Start then pivots into Copilot-only specifics in the Step 2 NOTE box (line 76-79), which spends 4 lines walking through COPILOT_GITHUB_TOKEN setup with no equivalent walkthrough for ANTHROPIC_API_KEY. A Claude user who selects Claude in the wizard gets dropped into the auth.mdx reference without a tailored callout in the Quick Start itself.

Specific Issues Found:

• docs/src/content/docs/setup/quick-start.mdx line 75-80: "Setting up COPILOT_GITHUB_TOKEN?" NOTE box is the only inline engine-setup callout. No parallel ANTHROPIC_API_KEY callout.
• docs/src/content/docs/setup/quick-start.mdx line 61-64: The gh aw add-wizard githubnext/agentics/daily-repo-status command doesn't mention --engine claude exists as an option, even though the CLI supports it (docs/src/content/docs/setup/cli.md line 157 lists --engine/-e for add-wizard).
• The sample workflow (daily-repo-status) is added with no indication of its default engine, so a Claude user can't predict whether engine: claude will be injected.

Recommended Fixes:

• Add a sibling NOTE box for ANTHROPIC_API_KEY setup in quick-start.mdx Step 2, linking to https://console.anthropic.com/.
• Add a tabbed or side-by-side snippet in Step 2 showing gh aw add-wizard ... --engine claude (and codex/gemini) alongside the default invocation.
• Briefly note that add-wizard will prompt for engine selection if --engine is omitted.

Question 2: Inaccessible Features for Non-Copilot Users

What features or steps don't work without Copilot?

Very few things are truly Copilot-only, and the engines reference is honest about this in its feature-comparison table (engines.md line 33-44). The asymmetries that exist are documented, just not flagged on the onboarding path.

Features That Require Copilot:

• max-continuations (autopilot mode) — Copilot only, documented in engines.md.
• engine.agent (custom agent file in .github/agents/) — Copilot only.
• engine.harness (custom Node.js harness wrapper) — Copilot only.
• Copilot BYOK mode (COPILOT_PROVIDER_BASE_URL) — Copilot-only configuration path (though it can route to Claude/OpenAI providers, which is interesting).

Features That Work Without Copilot:

• All safe-outputs (create-issue, create-pull-request, add-comment, ...) — engine-agnostic.
• All tools: edit:, bash:, web-fetch:, web-search: (via MCP for Claude), playwright:, cache-memory:, repo-memory:, agentic-workflows:, qmd:, mcp-servers:.
• All security layers (firewall, threat detection, content sanitization, secret redaction).
• engine.api-target, engine.bare, engine.env, engine.args, custom engine.command — all engines.
• max-turns is actually Claude-only (a Claude advantage, per engines.md line 36 and FAQ).
• gh aw init, gh aw add, gh aw add-wizard, gh aw new, gh aw compile, gh aw run, gh aw trial, gh aw secrets bootstrap — all support --engine claude.

Missing/Confusing Documentation:

• gh aw init (cli.md line 132-145) says it "creates the dispatcher agent file (.github/agents/agentic-workflows.agent.md)". Per engines.md, .github/agents/ files are a Copilot-specific custom-agent mechanism (engine.agent, marked ❌ for all non-Copilot engines). Documentation doesn't tell Claude users whether this generated file matters to them, whether --no-mcp is preferable for non-Copilot setups, or whether the file is silently ignored.
• The crush and opencode (experimental) engines surprisingly use COPILOT_GITHUB_TOKEN as their required secret (engines.md line 20-21, auth.mdx). This naming is confusing — a non-Copilot user reading the table sees "Copilot" in the secret name for an unrelated engine.
• tools.web-search requires a third-party MCP server for Claude (tools.md line 65, engines.md line 39 "via MCP") with a pointer to guides/web-search/, but the engines table cell just says "via MCP" without flagging this as friction worth understanding before commit.

Question 3: Documentation Gaps and Assumptions

Where does the documentation assume Copilot usage?

The structural assumption is that Copilot is the default and most readers will land there. This shows up in concrete ways:

Copilot-Centric Language Found In:

• README.md — extremely thin (sends readers to docs); doesn't mention engine alternatives or that Claude is a first-class engine option.
• docs/src/content/docs/index.mdx line 39: "Supported AI engines | 4 (GitHub Copilot, Claude, OpenAI Codex, custom)" — drops Gemini from the count despite engines.md listing it. Minor but inconsistent.
• docs/src/content/docs/index.mdx line 144: example caption says "runs an AI agent (Copilot, Claude, Codex, ...)" — fine ordering, but the Example: Daily Issues Report snippet (lines 117-141) has no engine: field at all, so readers infer the default (Copilot).
• docs/src/content/docs/introduction/architecture.mdx line 188: the AWF mermaid diagram has a node literally labeled COPILOT["Copilot CLI"], even though the security architecture is engine-agnostic. Claude users reading the security model see a Copilot-specific picture.
• docs/src/content/docs/introduction/architecture.mdx line 228: the Configuration Example uses engine: copilot rather than something engine-neutral or Claude.
• docs/src/content/docs/introduction/how-they-work.mdx line 26: "Workflows support GitHub Copilot (default), Claude by Anthropic, Codex, and Gemini by Google" — single line, no inline engine: claude snippet anywhere in the document.
• docs/src/content/docs/reference/engines.md has dedicated subsections titled "Copilot Custom Configuration" (line 109) and "Copilot Bring Your Own Key (BYOK) Mode" (line 199), totalling ~70 lines of Copilot-specific guidance. There is no parallel "Claude Custom Configuration" subsection — Claude-specific guidance is scattered across tables.
• docs/src/content/docs/setup/cli.md line 222 example: gh aw secrets bootstrap --engine copilot (could just as well have used claude to demonstrate non-default usage).
• Engine reference counts in docs: I grepped ^engine:\s*X and id:\s*X across docs/src/content/docs/: Copilot ~100 occurrences, Claude ~15, Codex 1, Gemini 1. Copilot examples outnumber Claude by ~7×.

Missing Alternative Instructions:

• No "Why would I choose Claude over Copilot?" guidance beyond a single sentence in engines.md line 27 ("Choose Claude when you want stronger control over turn limits (max-turns) for long reasoning sessions"). This understates the realistic reasons (existing Anthropic billing, preference for Claude family, organizational policy, etc.).
• No standalone tutorial like "Quick Start with Claude" or "Quick Start with Codex" — only a Copilot-flavored Quick Start.
• No callout to Claude users explaining that the .github/agents/agentic-workflows.agent.md file created by gh aw init is Copilot-specific and how it interacts (or doesn't) with Claude workflows.

---

Severity-Categorized Findings

🚫 Critical Blockers (Score: 0/10 — none found)

Nothing prevents a Claude user from successfully adopting gh-aw. engine: claude is fully supported, ANTHROPIC_API_KEY is well-documented, and the wizard path explicitly offers Claude. This is a real success and worth noting.

⚠️ Major Obstacles (Score: 5/10)

Obstacle 1: Quick Start auth callout is Copilot-only

Impact: A Claude user finishing the wizard's engine selection is dropped into auth.mdx without an inline callout matching the depth of the COPILOT_GITHUB_TOKEN walkthrough.

Current State: quick-start.mdx lines 75-80 dedicate a NOTE block to PAT creation steps for Copilot. No parallel block for ANTHROPIC_API_KEY, OPENAI_API_KEY, or GEMINI_API_KEY.

Why It's Problematic: Visual asymmetry signals "Copilot is the default-and-supported path; everything else is a side option." The actual auth reference is fine, but the Quick Start's signal is wrong.

Suggested Fix: Convert the NOTE block to a tabbed component (or four parallel collapsible boxes) covering all four engines with their respective key-creation links and gh aw secrets set commands.

Affected Files: docs/src/content/docs/setup/quick-start.mdx

Obstacle 2: Quick Start `add-wizard` command doesn't surface `--engine claude`

Impact: Claude users reading Step 2 don't learn they can skip the interactive prompt by passing --engine claude. The flag exists (CLI reference, line 157) but is invisible at the moment of adoption.

Current State: quick-start.mdx line 62-64 shows only the bare command.

Suggested Fix: Add a follow-up tip showing the non-interactive variant for each engine:

gh aw add-wizard githubnext/agentics/daily-repo-status --engine claude

Affected Files: docs/src/content/docs/setup/quick-start.mdx

Obstacle 3: Architecture diagram hard-codes "Copilot CLI"

Impact: The flagship security-architecture diagram (the AWF section) renders the agent process as COPILOT["Copilot CLI"]. Claude users reading the security model see a Copilot-specific picture and may wonder whether the firewall protections actually apply to Claude.

Current State: docs/src/content/docs/introduction/architecture.mdx line 188 in the AWF mermaid diagram. Other diagrams in the same file (e.g. the MCP Server Sandboxing diagram at line 282) correctly say "AI Engine<br/>(Copilot, Claude, Codex)" — so the pattern exists, just not consistently applied.

Suggested Fix: Rename the node to AGENT["AI Agent CLI<br/>(Copilot/Claude/Codex/Gemini)"] or similar. The same fix should be applied to the MCP Gateway diagram at line 252 which labels the container "Agent container\nCopilot CLI + MCP client".

Affected Files: docs/src/content/docs/introduction/architecture.mdx

Obstacle 4: Engines.md has no Claude-specific subsection mirroring Copilot's

Impact: The reference page has substantial dedicated sections — "Copilot Custom Configuration" (~10 lines), "Copilot Bring Your Own Key (BYOK) Mode" (~60 lines) — but Claude has only table entries and a security model section. A Claude user looking for "the Claude part of this page" cannot find a single anchored subsection to read.

Current State: docs/src/content/docs/reference/engines.md lines 109-119 (Copilot Custom Configuration), 199-266 (Copilot BYOK). The "Claude Tool Enforcement Security Model" section at line 437 is the closest Claude-specific area but it's about security caveats, not capabilities.

Suggested Fix: Add a "Claude Configuration" subsection covering: typical engine: claude shape with model and version, common Anthropic models worth using, recommended max-turns values for common workloads, Anthropic-specific env vars (ANTHROPIC_BASE_URL, etc.).

Affected Files: docs/src/content/docs/reference/engines.md

Obstacle 5: `gh aw init` creates a Copilot-flavored agent file with no Claude guidance

Impact: A Claude user running gh aw init gets .github/agents/agentic-workflows.agent.md created in their repo. Per engines.md, engine.agent (which references .github/agents/) is Copilot-only (❌ for all other engines). The CLI docs don't tell Claude users whether this file is harmless, useful, or to be deleted.

Current State: docs/src/content/docs/setup/cli.md line 134-145 (init description).

Suggested Fix: Add one sentence: "The agentic-workflows.agent.md file is read only by the Copilot engine. If your repository uses Claude, Codex, or Gemini, the file is created for forward-compatibility but has no runtime effect." Or alternatively, condition file creation on the engine flag.

Affected Files: docs/src/content/docs/setup/cli.md, possibly internal init logic

💡 Minor Confusion Points (Score: 7/10)

• Issue 1: README.md doesn't mention engines at all — sends readers to docs. Could add one line: "Works with Copilot, Claude, Codex, and Gemini." — File: README.md
• Issue 2: index.mdx line 39 says "4 (GitHub Copilot, Claude, OpenAI Codex, custom)" but engines.md lists 5 active engines + 2 experimental. Inconsistent count. — File: docs/src/content/docs/index.mdx
• Issue 3: Crush and OpenCode (non-Copilot engines) require COPILOT_GITHUB_TOKEN as their auth secret — counterintuitive naming, briefly explained in engines.md but not in auth.mdx. — File: docs/src/content/docs/reference/auth.mdx
• Issue 4: engines.md line 27 "Which engine should I choose?" is a single paragraph; not strong enough as a decision-support tool. Could be a small table with axes like "existing billing", "long reasoning", "autopilot continuations". — File: docs/src/content/docs/reference/engines.md
• Issue 5: tools.web-search requires third-party MCP for Claude (per engines.md line 39). The notation "via MCP" doesn't warn Claude users that this is extra setup. — File: docs/src/content/docs/reference/tools.md
• Issue 6: The Daily Repo Status sample workflow chosen for the Quick Start is hosted in githubnext/agentics and its default engine is invisible to readers of the Quick Start. — File: docs/src/content/docs/setup/quick-start.mdx
• Issue 7: "Claude Tool Enforcement Security Model" (engines.md line 437) — important warning about bypassPermissions mode silently ignoring --allowed-tools — is buried near the end of a long page. Worth promoting via a cross-link from the Security Architecture page. — File: docs/src/content/docs/reference/engines.md, docs/src/content/docs/introduction/architecture.mdx

---

Engine Comparison Analysis

Available Engines

Based on engines.md, gh-aw supports:

• engine: copilot — Default. Comprehensive docs, dedicated subsections, custom-agent + BYOK capabilities documented.
• engine: claude — Fully supported. Has max-turns advantage. Auth and security-mode docs are clear. Missing dedicated configuration subsection.
• engine: codex — Supported. Documented in tables and BYOK section. Almost no inline examples.
• engine: gemini — Supported. Documented in tables. Almost no inline examples.
• engine: crush (experimental) — Documented; reuses COPILOT_GITHUB_TOKEN.
• engine: opencode (experimental) — Documented; reuses COPILOT_GITHUB_TOKEN.
• custom — Index page mentions "custom AI processors" but this isn't actually an engine ID; minor inconsistency.

Documentation Quality by Engine

Engine	Setup Docs	Examples	Auth Docs	Overall
Copilot	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐
Claude	⭐⭐⭐⭐	⭐⭐	⭐⭐⭐⭐⭐	⭐⭐⭐⭐
Codex	⭐⭐⭐	⭐	⭐⭐⭐⭐	⭐⭐⭐
Gemini	⭐⭐⭐	⭐	⭐⭐⭐⭐	⭐⭐⭐

---

Tool Availability Analysis

Engine-Agnostic Tools (per tools.md and engines.md feature table):

• edit:, bash:, web-fetch:, playwright:, cache-memory:, repo-memory:, agentic-workflows:, qmd:, cli-proxy:, mcp-servers:, github:
• Safe outputs (create-issue, create-pull-request, etc.)

Engine-Specific Wrinkles:

• tools.web-search — Codex has it natively (opt-in); Claude/Copilot/Gemini/Crush/OpenCode need a third-party MCP.
• engine.agent — Copilot only.
• engine.harness — Copilot only.
• max-continuations — Copilot only.
• max-turns — Claude only.
• Tools allowlist — supported on Copilot/Claude/Codex/Gemini; not on Crush/OpenCode (per engines.md line 44).

Verdict: Tool surface is overwhelmingly engine-agnostic. The asymmetries are documented, just not always called out in the right places.

---

Authentication Requirements

Current Documentation

Quick Start guide visibly covers authentication for:

• ✅ Copilot (detailed NOTE box with PAT creation steps)
• 🟡 Claude (referenced via link to auth.mdx, no inline walkthrough in Quick Start)
• 🟡 Codex (same — link only)
• 🟡 Gemini (same — link only)

Reference auth page (auth.mdx) covers all four with parity: dedicated ### ANTHROPIC_API_KEY, ### OPENAI_API_KEY, ### GEMINI_API_KEY sections, each with setup steps, custom-endpoint guidance, and troubleshooting blocks.

Secret Names

• Copilot: COPILOT_GITHUB_TOKEN ✅
• Claude: ANTHROPIC_API_KEY ✅
• Codex: OPENAI_API_KEY (with CODEX_API_KEY as alternative) ✅
• Gemini: GEMINI_API_KEY ✅
• Crush / OpenCode: COPILOT_GITHUB_TOKEN ⚠️ (counterintuitive naming)

Strong points for Claude users:

• CLAUDE_CODE_OAUTH_TOKEN not-supported gotcha is documented in both auth.mdx and the FAQ — this is a great preemptive call-out.
• Custom endpoint via ANTHROPIC_BASE_URL is documented for self-hosted/Azure/proxy scenarios.
• 401/403 troubleshooting steps are documented per engine.

---

Example Workflow Analysis

Workflow Count by Engine (raw ^engine:\s*X + id:\s*X references)

Engine: copilot ~ 100 occurrences across 43 doc files
Engine: claude  ~  15 occurrences across  9 doc files
Engine: codex   ~   1 occurrence
Engine: gemini  ~   1 occurrence

Quality of Examples

Copilot examples: Plentiful, varied, embedded in pattern docs, architecture diagrams, BYOK section.

Claude examples: Concentrated in: network.md, deterministic-agentic-patterns.md, research-plan-assign-ops.md, frontmatter-hash-specification.md, faq.md, cli.md. The engines.md reference page has 3 id: claude examples but uses them mainly to demonstrate bare mode, token-weights, and max-turns — i.e., as showcases of Claude features, not as general-purpose workflow examples.

Codex/Gemini: Effectively absent from examples outside the engines reference and BYOK section.

---

Recommended Actions

Priority 1: Critical Documentation Fixes

1. Add parallel auth callouts for all four engines in Quick Start Step 2 — File: docs/src/content/docs/setup/quick-start.mdx
2. De-Copilot the architecture diagrams (AWF and MCP Gateway diagrams) so the security-architecture page reads as engine-agnostic — File: docs/src/content/docs/introduction/architecture.mdx
3. Show --engine claude (and codex/gemini) variants of the add-wizard command in Quick Start — File: docs/src/content/docs/setup/quick-start.mdx

Priority 2: Major Improvements

1. Add a "Claude Configuration" subsection in engines.md mirroring the structure of the existing "Copilot Custom Configuration" and "Copilot BYOK" sections — File: docs/src/content/docs/reference/engines.md
2. Clarify the role of .github/agents/agentic-workflows.agent.md created by gh aw init for non-Copilot users — File: docs/src/content/docs/setup/cli.md
3. Promote the "Claude Tool Enforcement Security Model" warning about bypassPermissions to the Security Architecture page (cross-link) — Files: docs/src/content/docs/reference/engines.md, docs/src/content/docs/introduction/architecture.mdx
4. Rebalance examples by converting a handful of engine: copilot snippets in patterns and guides to engine: claude (or to engine-agnostic snippets that omit the engine: field entirely).

Priority 3: Nice-to-Have Enhancements

1. Add a one-line engine summary to README.md: "Works with Copilot, Claude, Codex, and Gemini."
2. Add a decision-support table to engines.md (axes: existing billing, long reasoning, autopilot, custom agents, web search built-in).
3. Fix the inconsistent engine count in index.mdx line 39 ("4 ... custom" vs. the actual 5–7 supported engines).
4. Clarify in auth.mdx why Crush/OpenCode reuse COPILOT_GITHUB_TOKEN.
5. Add a "Quick Start with Claude" sibling page for users who land already knowing they want Claude.

---

Positive Findings

• ✅ engines.md engine-feature comparison table is genuinely useful and honestly documents per-engine asymmetries.
• ✅ auth.mdx gives each engine a dedicated section with setup link, CLI command, custom-endpoint guidance, and troubleshooting.
• ✅ CLAUDE_CODE_OAUTH_TOKEN not-supported pitfall is preempted in both auth.mdx and FAQ — excellent.
• ✅ Claude-only max-turns is positioned as an advantage, not an exception.
• ✅ The MCP Server Sandboxing diagram correctly labels the agent as "AI Engine<br/>(Copilot, Claude, Codex)". Pattern exists — just needs propagation.
• ✅ gh aw secrets bootstrap --engine claude is a smooth onboarding affordance and is documented.
• ✅ gh aw new --engine claude injects engine: claude into the generated template (cli.md line 187-194). This is great.
• ✅ engine.bare is engine-agnostic with per-engine effect documented in a clear table (engines.md line 327-333).
• ✅ Custom endpoint guidance covers Anthropic (ANTHROPIC_BASE_URL), OpenAI, Copilot, and Gemini equally.

---

Conclusion

Can Claude Code Users Successfully Adopt gh-aw?

Answer: Yes, with friction.

Reasoning: The reference documentation is solid: engine: claude is a first-class option with full auth, security-model, and capability documentation. A determined Claude user reading top-to-bottom can complete adoption. The friction is in the onboarding surface area — the Quick Start, README, architecture diagrams, and examples all read like Copilot-first material with Claude as a footnote. Most of the fixes are mechanical (callouts, diagram labels, example rebalancing) rather than structural — the underlying support is already there.

Overall Assessment Score: 7/10

Breakdown:

• Clarity for non-Copilot users: 7/10
• Claude engine documentation: 8/10
• Alternative approaches provided: 7/10
• Engine parity: 8/10

Next Steps

1. Highest-leverage single fix: add the parallel ANTHROPIC_API_KEY (and Codex/Gemini) auth callouts to Quick Start Step 2.
2. Second-highest: relabel the "Copilot CLI" boxes in architecture.mdx to be engine-neutral.
3. Lowest-effort: add an engine line to README.md.

---

Appendix: Files Reviewed

• README.md
• docs/src/content/docs/index.mdx
• docs/src/content/docs/setup/quick-start.mdx
• docs/src/content/docs/setup/cli.md
• docs/src/content/docs/introduction/how-they-work.mdx
• docs/src/content/docs/introduction/architecture.mdx
• docs/src/content/docs/reference/tools.md
• docs/src/content/docs/reference/engines.md
• docs/src/content/docs/reference/auth.mdx
• docs/src/content/docs/reference/faq.md (partial — engine and Claude sections)
• docs/src/content/docs/examples/manual.md (sample examples doc)

Grep-based counts across all docs/src/content/docs/ for ^engine:\s*X and id:\s*X patterns.

---

References:

• §25736205666

Generated by Claude Code User Documentation Review · ● 11.3M · ◷

• expires on May 13, 2026, 1:10 PM UTC

[github-actions[bot]]

This discussion has been marked as outdated by Claude Code User Documentation Review.

A newer discussion is available at Discussion #31940.