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

[github-actions[bot]]

Executive Summary

As a Claude Code user (no Copilot subscription, no Copilot CLI) reviewing gh-aw documentation, I found that adoption is possible but requires effort — the documentation supports Claude as an engine, but the onboarding path, examples, and tone are Copilot-first. Reference docs are good; the on-ramp is misleading.

Key Finding: A Claude-only user who follows the Quick Start verbatim will likely fail their first run, because the sample workflow inherits the Copilot default and the docs do not flag this clearly. Engine-portability of features is well-tabulated in engines.md, but most tool docs are silent on engine compatibility.

---

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?

Yes — eventually. The Quick Start describes a 10-minute path that does mention Claude as an option, including the ANTHROPIC_API_KEY setup step. The add-wizard interactively prompts the user to pick an engine. The page links to console.anthropic.com/settings/keys for key creation.

However, the experience has unaddressed traps:

Specific Issues Found:

• quick-start.mdx lines 62–73 — The sample workflow githubnext/agentics/daily-repo-status has no engine: declared in its frontmatter. It defaults to Copilot. The Quick Start does not call out that the wizard must (or will) patch the engine. If a user runs the workflow without verifying, it will try to call Copilot.
• quick-start.mdx lines 76–80 vs 82–86 — The COPILOT_GITHUB_TOKEN note has 6 numbered steps with permission walkthrough; the ANTHROPIC_API_KEY note has 2 steps. Visually signals Copilot as the primary path.
• creating-workflows.mdx lines 102–127 — gh aw init is described as required to enable the Copilot Chat / mobile authoring experience. Reading this, a Claude user may assume gh-aw fundamentally requires Copilot to author workflows.

Recommended Fixes:

• Patch the Quick Start to verify or set engine: claude in the workflow .md after add-wizard finishes for non-Copilot users.
• Give parallel structure to the COPILOT_GITHUB_TOKEN and ANTHROPIC_API_KEY callouts.
• Mark gh aw init as required only for Copilot Chat authoring; clarify that local CLI + gh aw compile works for any engine.

Question 2: Inaccessible Features for Non-Copilot Users

What features or steps don't work without Copilot?

From the engines reference matrix at engines.md lines 33–44, three features are genuinely Copilot-only:

Features That Require Copilot:

• engine.agent — custom agent file (.github/agents/*.agent.md)
• engine.harness — custom Node.js harness script
• max-continuations — autopilot mode with multiple sequential runs
• safe-outputs.create-agent-session and safe-outputs.assign-to-agent — target the Copilot coding agent (server-side service)
• The gh aw init dispatcher file creation (.github/agents/agentic-workflows.agent.md)
• tools.copilot (where present)

Features That Work Without Copilot:

• All safe-outputs write operations (create-issue, add-comment, create-pull-request, etc.)
• All built-in tools: edit, bash, github, playwright, web-fetch, cache-memory, repo-memory, qmd, agentic-workflows, cli-proxy
• Custom mcp-servers
• All security features (AWF firewall, threat detection, secret redaction)
• engine.api-target, engine.bare, engine.env, BYOK via custom base URLs
• Claude has its own unique advantage: max-turns

Missing Documentation:

• Tool reference (tools.md) does not state engine compatibility for edit, bash, cache-memory, repo-memory, qmd, agentic-workflows, cli-proxy, or playwright. Claude users must infer from absence of restriction.
• safe-outputs.md makes no engine-compatibility statement for the vast majority of variants. A Claude user cannot tell whether e.g. push-to-pull-request-branch behaves identically across engines.
• No "How to use gh-aw with Claude" guide exists; there is a dedicated copilot-custom-agents.md and assign-to-copilot.mdx.

Question 3: Documentation Gaps and Assumptions

Where does the documentation assume Copilot usage?

Copilot-Centric Language Found In:

• File: reference/engines.md line 27 — "Copilot is the default choice for most users because it supports the broadest gh-aw feature set... If you are unsure, start with Copilot and switch later." This is a recommendation, not a neutral framing.
• File: reference/engines.md lines 60–69 — Canonical engine: example uses id: copilot and includes Copilot-only fields (agent:) without inline annotations.
• File: reference/faq.md lines 338, 455, 712 — Billing explanations lead with Copilot; other engines get one-bullet treatment.
• File: setup/creating-workflows.mdx lines 102–127 — gh aw init framed as required for authoring workflows via Copilot Chat / mobile, without clarifying alternatives.
• File: index.mdx line 39 — "Supported AI engines | 4 (GitHub Copilot, Claude, OpenAI Codex, custom)" understates the engine list (Gemini, Crush, OpenCode are missing) and lists Copilot first.
• File: reference/auth.mdx line 109 — Anthropic setup links to (platform.claude.com/redacted) (docs page), while OpenAI link (line 135) goes directly to platform.openai.com/api-keys`.

Engine reference distribution across all docs:

Engine	engine: X mentions	id: X mentions	Total
copilot	82 (35 files)	29 (13 files)	111
claude	9 (7 files)	8 (6 files)	17
codex	1	4	5
gemini	1	0	1
crush	0	0	0
opencode	1	0	1

Copilot examples outnumber Claude examples ~6.5×.

Missing Alternative Instructions:

• No "Configuring Claude" or "Using gh-aw with Claude" focused guide.
• No equivalent of copilot-custom-agents.md showing Claude-specific patterns (e.g., when to use max-turns, how Claude's bypassPermissions mode affects tool allowlists).
• The bypassPermissions security note (engines.md line 437–470) — important for Claude users granting bash: '*' — is buried at the bottom of the engines page rather than surfaced in the Claude setup flow.

Severity-Categorized Findings

🚫 Critical Blockers (Score: 2/10)

Blocker 1: Quick Start sample workflow silently inherits Copilot

Impact: A Claude user follows the Quick Start verbatim and the workflow fails at first run because it tries to call Copilot.

Current State: setup/quick-start.mdx lines 62–73 instruct gh aw add-wizard githubnext/agentics/daily-repo-status. The sample workflow has no engine: and defaults to Copilot. The Quick Start does say "Select an AI Engine — Choose between Copilot, Claude, Codex, or Gemini" (line 70) as a wizard step but does not explicitly say the wizard will patch engine: into the workflow file.

Why It's a Blocker: The first thing the user sees succeed is the wizard. The first thing they will see fail is the workflow run, with a Copilot auth error — even though they configured ANTHROPIC_API_KEY.

Fix Required: Either (a) make add-wizard confirm it patched the .md and tell the user, or (b) add a verification step in the Quick Start: "Open .github/workflows/daily-repo-status.md and confirm engine: claude appears in the frontmatter."

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

Blocker 2: `gh aw init` framed as required, but creates Copilot-only artifact

Impact: Claude users may conclude gh-aw fundamentally requires Copilot to author workflows.

Current State: setup/creating-workflows.mdx lines 102–127: "Running gh aw init is required to enable the authoring experience in the GitHub code agent... using the Copilot coding agent." The command creates .github/agents/agentic-workflows.agent.md and instructs users to invoke /agent agentic-workflows in Copilot Chat.

Why It's a Blocker: The word "required" combined with the only documented authoring fallback being Copilot Chat makes a Claude-only user think they cannot use this product.

Fix Required: Rephrase: "Required only if you want to author workflows from github.com or the GitHub mobile app using Copilot Chat. If you are using Claude Code, Cursor, or another local AI assistant, you can skip this and use gh aw new / gh aw compile directly."

Affected Files: docs/src/content/docs/setup/creating-workflows.mdx, docs/src/content/docs/setup/cli.md (the init command description, lines 134–145, also implies general-purpose setup)

⚠️ Major Obstacles (Score: 4/10)

Obstacle 1: Engines page actively steers users to Copilot

Impact: Claude users feel they are choosing the "lesser" engine.

Current State: reference/engines.md line 27: "Copilot is the default choice for most users... If you are unsure, start with Copilot." The feature-comparison table at lines 33–44 reinforces this — Copilot has the most ticks.

Why It's Problematic: The default framing pushes users away from Claude even when Claude's max-turns advantage is more useful for their workload (e.g., long reasoning sessions).

Suggested Fix: Reframe neutrally: "Pick the engine matching your existing AI subscription. Claude users gain max-turns for iteration control; Copilot users gain max-continuations and custom agent files; Codex gains native web search."

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

Obstacle 2: Auth docs give Copilot disproportionate depth

Impact: Claude users perceive Anthropic as a secondary option.

Current State: reference/auth.mdx lines 76–100 (Copilot, ~25 lines with deep links, permissions, license troubleshooting) vs. lines 103–125 (Claude, ~22 lines, half consumed by CLAUDE_CODE_OAUTH_TOKEN not supported warning). The Anthropic API key link (line 109) points to a docs landing page rather than the key creation page.

Why It's Problematic: Claude users hit OAuth-not-supported friction immediately if they have Claude Max/Teams. The discovery path for API keys is slower.

Suggested Fix: Link directly to https://console.anthropic.com/settings/keys (the Quick Start already does this). Move OAuth caveat to a small footnote. Add Claude-equivalent troubleshooting block parity with Copilot's license note.

Affected Files: docs/src/content/docs/reference/auth.mdx

Obstacle 3: Tool reference silent on engine compatibility

Impact: Claude users cannot tell whether a given tool works under Claude without trial-and-error.

Current State: reference/tools.md documents edit, bash, github, playwright, web-fetch, web-search, cache-memory, repo-memory, qmd, agentic-workflows, cli-proxy, custom mcp-servers — none with explicit engine-compatibility statements. The authoritative matrix at engines.md lines 33–44 only covers a few options (web-fetch, web-search, engine.*, max-turns, max-continuations, tools allowlist).

Why It's Problematic: The engines.md table is incomplete; Claude users must infer from absence of restriction in tools.md that a tool is engine-agnostic. A handful of ambiguities (e.g., does cli-proxy work with Claude when safeoutputs/mcpscripts are referenced?) are unresolved.

Suggested Fix: Add an "Engine compatibility" sentence to each tool subsection in tools.md, or extend the feature matrix in engines.md to cover all tools. Defaults like "all tools are engine-agnostic unless explicitly noted" at the top of tools.md would help.

Affected Files: docs/src/content/docs/reference/tools.md, docs/src/content/docs/reference/engines.md, docs/src/content/docs/reference/safe-outputs.md

Obstacle 4: Copilot-only flags mixed in canonical examples without inline annotation

Impact: Claude users copy examples verbatim and silently lose features.

Current State: reference/engines.md lines 60–69 shows a canonical engine: example with id: copilot ... agent: agent-id ... harness: ... mixed in. A reader who changes id: to claude will silently lose agent and harness (correctly tabulated as Copilot-only at lines 40, 43, but easy to miss).

Why It's Problematic: Copy-paste workflow won't be "correct just by changing engine name" — contradicting the engines page's own claim (line 27) that you can "switch by changing only engine: and the corresponding secret."

Suggested Fix: Add inline # Copilot only comments to each Copilot-only field in canonical examples. Add an example block specifically titled "Claude configuration" with id: claude, max-turns, bare.

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

💡 Minor Confusion Points (Score: 5/10)

• Unexplained "Copilot coding agent" jargon — assign-to-copilot.mdx line 10 and many others use this term without disambiguating it from the Copilot CLI engine. File: docs/src/content/docs/reference/assign-to-copilot.mdx
• "By the Numbers" engine count outdated — index.mdx line 39 lists 4 engines (Copilot, Claude, Codex, custom) but engines.md documents 6 (adds Gemini, Crush, OpenCode). File: docs/src/content/docs/index.mdx
• "Copilot Copilot" duplicate word — guides/packaging-imports.mdx line 154: "See [Importing Copilot Copilot Agent Files]". File: docs/src/content/docs/guides/packaging-imports.mdx
• BYOK acronym used before expanding — frontmatter.md lines 473–492; weekly update blog post line 42. File: docs/src/content/docs/reference/frontmatter.md
• "Autopilot mode" never defined inline — appears in engines.md line 27 and elsewhere; glossary entry would help. File: docs/src/content/docs/reference/glossary.md

---

Engine Comparison Analysis

Available Engines

Based on engines.md lines 14–22, gh-aw supports six engines:

• engine: copilot (default) — comprehensive setup docs, custom agent file support, BYOK mode
• engine: claude — adequate setup docs but second-class onramp; no dedicated guide
• engine: codex — minimal setup docs (auth covered)
• engine: gemini — minimal setup docs (auth covered)
• engine: crush (experimental) — uses COPILOT_GITHUB_TOKEN; barely documented
• engine: opencode (experimental) — uses COPILOT_GITHUB_TOKEN; barely documented

Documentation Quality by Engine

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

---

Tool Availability Analysis

Tools Review

Engine-Agnostic Tools (work with any engine, including Claude):

• tools.edit, tools.bash, tools.github, tools.playwright
• tools.web-fetch (web-search requires extra MCP for non-Codex engines)
• tools.cache-memory, tools.repo-memory, tools.qmd
• tools.agentic-workflows, tools.cli-proxy
• Custom mcp-servers
• All security features (AWF, threat detection, secret redaction)
• engine.api-target, engine.env, BYOK via *_BASE_URL env vars
• engine.bare (except Crush/OpenCode)

Engine-Specific Tools:

• engine.agent, engine.harness, max-continuations, safe-outputs.create-agent-session, safe-outputs.assign-to-agent → Copilot-only
• max-turns → Claude-only
• Native web-search → Codex-only

Unclear/Undocumented:

• Most tool subsections in tools.md lack engine compatibility statements (see Obstacle 3)
• safe-outputs.md has no engine matrix at all
• playwright.md is silent on engine support

---

Authentication Requirements

Current Documentation

The auth.mdx page covers authentication for:

• ✅ Copilot — detailed (PAT creation, permissions, troubleshooting, license issues)
• ✅ Claude — adequate but unbalanced (API key + OAuth-not-supported warning)
• ✅ Codex — adequate (API key + CODEX_API_KEY alternative)
• ✅ Gemini — adequate (API key)

Issues for Claude Users

• API key creation link points to a docs landing page (platform.claude.com/docs/en/get-started, line 109) instead of the key creation page. The Quick Start uses the correct link (console.anthropic.com/settings/keys) — these should be consistent.
• CLAUDE_CODE_OAUTH_TOKEN is explicitly unsupported. This means Claude Max/Teams subscribers must use API billing instead, which is not stated upfront.

Secret Names

• Copilot: COPILOT_GITHUB_TOKEN (fine-grained PAT)
• Claude: ANTHROPIC_API_KEY (Anthropic Console)
• Codex: OPENAI_API_KEY or CODEX_API_KEY
• Gemini: GEMINI_API_KEY
• Crush/OpenCode: COPILOT_GITHUB_TOKEN (experimental)

---

Example Workflow Analysis

Workflow Count by Engine (across all docs)

engine: copilot  - 111 references
engine: claude   -  17 references
engine: codex    -   5 references
engine: gemini   -   1 reference
engine: crush    -   0 references
engine: opencode -   1 reference

Quality of Examples

Copilot Examples: Plentiful and detailed. Cover custom agents, BYOK, custom harness, autopilot, all advanced configuration. First-class throughout the docs.

Claude Examples: Adequate in engines.md (which has 13 id: claude blocks) but rare elsewhere. The quick-start.mdx does feature a Claude example (line 134) — good — but it's a tiny snippet rather than a worked end-to-end. There is no dedicated "Building a workflow with Claude" guide showing max-turns, bare, etc. in context.

---

Recommended Actions

Priority 1: Critical Documentation Fixes

1. Fix Quick Start engine override — Make the wizard's engine patching explicit (or auto-set engine in the workflow). Add verification step. File: docs/src/content/docs/setup/quick-start.mdx
2. Recast gh aw init as optional / Copilot-specific — Update phrasing so Claude users don't believe they need it. Files: docs/src/content/docs/setup/creating-workflows.mdx, docs/src/content/docs/setup/cli.md
3. Fix Anthropic API key link — Link to console.anthropic.com/settings/keys (matches the Quick Start). File: docs/src/content/docs/reference/auth.mdx

Priority 2: Major Improvements

1. Neutralize engine recommendation language — Stop saying "start with Copilot if unsure"; reframe as "pick the engine matching your subscription". File: docs/src/content/docs/reference/engines.md
2. Add inline Copilot-only annotations — Annotate agent:, harness:, max-continuations in canonical examples with # Copilot only comments. File: docs/src/content/docs/reference/engines.md
3. Add engine-compatibility line to every tool — Each subsection in tools.md should state "Works with: all engines" or list exceptions. File: docs/src/content/docs/reference/tools.md
4. Add a Claude-focused worked example — A new guide page showing a complete workflow with engine: claude, max-turns, bare. Suggested file: docs/src/content/docs/guides/using-claude.mdx

Priority 3: Nice-to-Have Enhancements

1. Update index.mdx to list all 6 supported engines.
2. Fix "Copilot Copilot" typo in guides/packaging-imports.mdx.
3. Add glossary entries for "autopilot mode", "Copilot coding agent" (vs. CLI engine), "BYOK".
4. Move Claude's bypassPermissions security note (engines.md lines 437–470) into the Claude setup flow or Quick Start.
5. Add Crush/OpenCode auth notes (currently they're listed but no setup details exist).

---

Positive Findings

What Works Well

• ✅ The Quick Start does list Claude as a supported engine prerequisite (line 29) and includes a Claude callout (lines 82–86) and API key link.
• ✅ The engines reference (engines.md) provides a clear feature compatibility matrix (lines 33–44) for Claude users who find it.
• ✅ engines.md includes a dedicated Claude security section (lines 437–470) covering the bypassPermissions behavior — a real Claude-specific consideration that's well-documented.
• ✅ Authentication setup commands (gh aw secrets set ANTHROPIC_API_KEY) work identically for any engine — good CLI parity.
• ✅ The architecture page (introduction/architecture.mdx) is engine-neutral and applies equally to Claude users.
• ✅ All safe-outputs, all MCP integration, and all security features work with Claude — gh-aw's core value proposition is genuinely engine-agnostic.
• ✅ The Anthropic Console link in the Quick Start (line 84) correctly points to the key creation page.

---

Conclusion

Can Claude Code Users Successfully Adopt gh-aw?

Answer: Yes, with significant effort — and after the first failed run.

Reasoning: A Claude user who reads carefully, finds the engines reference, sets engine: claude in their workflow, and configures ANTHROPIC_API_KEY will get a working agentic workflow. The product itself is engine-portable for ~90% of use cases. But the onboarding path is Copilot-first to a degree that will cause a first-run failure for many Claude users, and the absence of Claude-focused worked examples makes it harder for Claude users to discover their engine's unique strengths (notably max-turns).

Overall Assessment Score: 6/10

Breakdown:

• Clarity for non-Copilot users: 5/10 — Reference docs are clear once found; onboarding is misleading
• Claude engine documentation: 7/10 — Adequate in engines.md and auth.mdx; thin elsewhere
• Alternative approaches provided: 6/10 — Most features work, but rarely demonstrated for non-Copilot
• Engine parity: 6/10 — Real parity is high; documented parity lags behind

Next Steps

1. Treat the Quick Start as the highest-leverage fix: a Claude user's first run should not fail.
2. Make gh aw init opt-in / clearly Copilot-specific.
3. Add a small set of Claude-focused examples in engines.md and (ideally) a guides/using-claude.mdx page that mirrors the existing Copilot-specific docs.
4. Audit all tool docs for engine-compatibility statements.

---

Appendix: Files Reviewed

Complete List of Documentation Files Analyzed

• README.md
• docs/src/content/docs/setup/quick-start.mdx
• docs/src/content/docs/setup/creating-workflows.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/introduction/overview.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/safe-outputs.md (sampled)
• docs/src/content/docs/reference/github-tools.md (sampled)
• docs/src/content/docs/reference/playwright.md (sampled)
• docs/src/content/docs/reference/copilot-custom-agents.md (sampled)
• docs/src/content/docs/reference/assign-to-copilot.mdx (sampled)
• docs/src/content/docs/reference/glossary.md (sampled)
• docs/src/content/docs/reference/faq.md (sampled)
• docs/src/content/docs/index.mdx (sampled)
• docs/src/content/docs/guides/packaging-imports.mdx (sampled)

---

Report Generated: §25919140315
Workflow: claude-code-user-docs-review
Engine Used: claude (eating our own dog food! 🐕)

Generated by 📝 Claude Code User Documentation Review · ● 21.3M · ◷

• expires on May 16, 2026, 1:09 PM UTC