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

[github-actions[bot]]

Executive Summary

I reviewed the gh-aw documentation as a developer who uses Claude Code and explicitly does not use GitHub Copilot or the Copilot CLI. The good news: adoption is viable — engine: claude is documented, ANTHROPIC_API_KEY setup has a step-by-step section, and most tools (edit, bash, github, web-fetch, playwright, memory, MCP servers, safe-outputs) are engine-agnostic. The friction: every onboarding surface — the README, the Quick Start, the default gh aw init behavior, and the sample workflows — leads with Copilot. A non-Copilot user can succeed, but never feels like the documentation was written with them in mind.

Key Finding: No critical blockers — but Copilot is hardcoded as the default engine, and Claude users must consciously opt in at every step. Compared to the previous review (2026-05-20), the count of Claude examples in docs ticked from 5 to 6; the underlying Copilot-default framing has not changed.

---

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

---

Summary Scorecard

Dimension	Score	Notes
Overall adoption viability	6/10	Possible, but Copilot-first throughout
Clarity for non-Copilot users	6/10	Claude is mentioned, never centered
Claude engine documentation	7/10	Reference page is solid; tutorials lag
Alternative approaches provided	6/10	Quick Start only spells out Copilot + Claude callouts
Engine parity	5/10	Copilot has exclusive features (agent files, harness, max-continuations)

Blocker counts: 🚫 0 critical · ⚠️ 4 major · 💡 6 minor (unchanged from prior run)

---

Question 1: Onboarding Experience

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

Yes, but the path requires reading carefully and skipping over Copilot framing. The README's Overview does an honest one-liner — "Supports GitHub Copilot, Claude (Anthropic), Codex (OpenAI), and Gemini (Google) — pick whichever AI account you already have" — which is the single most welcoming sentence for Claude users in the entire onboarding surface. Everything downstream from that sentence then defaults to Copilot.

The Quick Start (docs/src/content/docs/setup/quick-start.mdx) lists all four AI accounts in the Prerequisites (L29) and surfaces engine choice during the interactive add-wizard (L70). Two dedicated NOTE callouts exist: one for COPILOT_GITHUB_TOKEN (L75–79) and one for ANTHROPIC_API_KEY (L82–85). Codex and Gemini get equal billing in the engine-selection step but no setup callout — they're treated as second-tier even though the Prerequisites lists them peer-to-peer.

The "customize" step at L130–136 finally shows how to set engine: claude in frontmatter — but only as one example among the customization instructions, not as a first-class onboarding step. A Claude user reading top-to-bottom will run add-wizard, hit the AI Engine prompt, and have to choose Claude there with no prior guidance that this is the supported path.

Specific Issues Found:

• docs/src/content/docs/setup/quick-start.mdx:14 — sample workflow link daily-repo-status.md should be a workflow the Quick Start has demonstrated runs on Claude.
• docs/src/content/docs/setup/quick-start.mdx:71 — the step-3 sentence lists COPILOT_GITHUB_TOKEN first and longest (15+ words of inline parenthetical), while Claude/OpenAI/Gemini keys get just a link.
• docs/src/content/docs/setup/quick-start.mdx:132–135 — the example engine: claude snippet is buried in step 4, after the user has already committed and run a Copilot-based workflow.
• README.md:39 — the Overview heading promises engine flexibility but immediately links to a Copilot-default Quick Start without a Claude-specific landing page.

Recommended Fixes:

• Add a parallel "Use Claude" panel/tabset to Quick Start Step 2, so the choice is presented up front instead of mid-wizard.
• Add a NOTE callout for OPENAI_API_KEY and GEMINI_API_KEY parity with the existing Copilot/Claude callouts.
• Add an engine: claude frontmatter snippet in Step 2's preview, not Step 4.

Question 2: Inaccessible Features for Non-Copilot Users

What features or steps don't work without Copilot?

From docs/src/content/docs/reference/engines.md:

Features that are Copilot-only (no Claude equivalent):

• engine.agent — custom agent files in .github/agents/ (engines.md L41, L111–121). The default gh aw init even creates .github/agents/agentic-workflows.agent.md — a Copilot-only artifact — for every user regardless of intended engine.
• engine.harness — custom harness script (engines.md L44, L293–315). Explicit doc note: "Currently only applied during Copilot engine execution. Setting it on other engines has no effect."
• max-continuations — autopilot mode (engines.md L38, L51, L395–401).
• BYOK (Bring Your Own Key) — routed via the Copilot CLI (engines.md L201–268).

Features that are Claude-only:

• max-turns — iteration budget control (engines.md L37, L406–417).

Features that are engine-agnostic (work the same for Claude users): edit, bash, github (toolsets), web-fetch, playwright, cache-memory, repo-memory, qmd, agentic-workflows, cli-proxy, mcp-servers, safe-outputs, threat-detection.

Features with engine-specific quirks:

• web-search — native opt-in for Codex; other engines need third-party MCP servers (tools.md L62–67).
• Tools allowlist enforcement — supported on copilot/claude/codex/gemini/pi; not on crush/opencode (engines.md L45).

Missing Documentation:

• gh aw init (cli.md L134) does not flag that the dispatcher agent file it creates is Copilot-only and ignored by Claude. A Claude user who runs gh aw init gets a file they will never use, with no warning.
• engine.harness and engine.agent mention they're Copilot-only inside their own sections, but the engines.md feature matrix would benefit from a "What this means for you" paragraph for non-Copilot users.

Question 3: Documentation Gaps and Assumptions

Where does the documentation assume Copilot usage?

Copilot-Centric Language Found In:

• docs/src/content/docs/introduction/how-they-work.mdx:26 — "Workflows support GitHub Copilot (default), Claude by Anthropic, Codex, and Gemini by Google." — the bold (default) qualifier on Copilot, with no corresponding "how do I switch" hint inline.
• docs/src/content/docs/introduction/architecture.mdx:228 — the firewall configuration example uses engine: copilot for the only complete example.
• docs/src/content/docs/introduction/architecture.mdx:280 — "AI Engine (Copilot, Claude, Codex)" in a sandboxing diagram omits Gemini even though it's listed in support elsewhere.
• docs/src/content/docs/setup/cli.md:134 — gh aw init description says it "creates the dispatcher agent file (.github/agents/agentic-workflows.agent.md)" without noting this file is only used by the Copilot engine.
• docs/src/content/docs/reference/auth.mdx — Claude section references both (platform.claude.com/redacted) (L109) and https://console.anthropic.com/` (L199). Both work, but the inconsistency makes a Claude user second-guess which is canonical.

Repo-Wide Example Counts:

Global .md files (1,496 total):
  engine: copilot   349 files
  engine: claude    109 files
  engine: codex      33 files
  engine: gemini      1 file
  engine: custom      0 files
  (no engine field) 1,006 files → silently default to copilot

Docs only (140 files under docs/src/content/docs/):
  engine: copilot    58
  engine: claude      6
  engine: codex       1
  engine: gemini      1

Docs has roughly a 10:1 Copilot-to-Claude example ratio. The 109 Claude workflows that exist in the repo are mostly in pkg/cli/workflows/test-claude-*.md — test fixtures, not user-facing docs.

Missing Alternative Instructions:

• No "how to use Claude" landing/tutorial page at the same level as the Quick Start. Claude-engine specifics are scattered across engines.md, auth.mdx, and CLI flag descriptions.
• No comparison table ("Why Claude vs Copilot vs Codex vs Gemini?") that helps a new user pick.
• No troubleshooting section keyed on engine choice (e.g., "My Claude workflow is hitting max-turns").

Severity-Categorized Findings

🚫 Critical Blockers

None. A Claude Code user can complete the Quick Start, set up ANTHROPIC_API_KEY, and run a workflow without any genuinely blocking gap.

⚠️ Major Obstacles (4)

Obstacle 1: Copilot is the default engine, baked into init

Impact: Every user — including Claude users — gets a Copilot-shaped repo after gh aw init.

Current State: cli.md:134 documents that gh aw init "Creates the dispatcher agent file (.github/agents/agentic-workflows.agent.md)." This file is consumed by the Copilot engine.agent mechanism (engines.md L41, L53). For Claude/Codex/Gemini users, the file is dead weight.

Why It's Problematic: A Claude Code user has no way to know from the docs that this generated file is Copilot-only.

Suggested Fix: Add an --engine flag to gh aw init (or document that running gh aw init --no-mcp is the non-Copilot path). Add a sentence to cli.md:134: "The dispatcher agent file is consumed by the Copilot engine; other engines ignore it."

Affected Files: docs/src/content/docs/setup/cli.md, docs/src/content/docs/reference/copilot-custom-agents.md

Obstacle 2: Quick Start callouts only cover Copilot and Claude

Impact: Codex and Gemini users land on the Quick Start, choose their engine in the wizard, and then get no dedicated NOTE block telling them which secret to set and where to get the key.

Current State: quick-start.mdx:75–79 and :82–85 give detailed setup boxes for COPILOT_GITHUB_TOKEN and ANTHROPIC_API_KEY respectively. OPENAI_API_KEY and GEMINI_API_KEY appear only as links in the step-3 paragraph (:71).

Why It's Problematic: The Prerequisites section presents all four engines as peer choices. The Step 3 setup makes only two of them first-class.

Suggested Fix: Add equivalent NOTE callouts for OPENAI_API_KEY and GEMINI_API_KEY. Or fold all four into a tabbed component.

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

Obstacle 3: Engine parity is unclear — Claude has only one exclusive feature, Copilot has four

Impact: A Claude user reading the engines reference will discover, item by item, that Copilot has engine.agent, engine.harness, max-continuations, and BYOK — and Claude has max-turns. There is no single "feature parity" view.

Current State: docs/src/content/docs/reference/engines.md rows L37–L51 contain the comparison table, but it is presented as a feature inventory rather than a guidance page. There is no narrative answer to "What do I give up by choosing Claude over Copilot?"

Suggested Fix: Add a short "Choosing an Engine" subsection that summarizes: "Choose Copilot if you need custom agent files, autopilot continuations, or BYOK routing. Choose Claude if you need fine-grained max-turns control."

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

Obstacle 4: No Claude-first end-to-end tutorial in user-facing docs

Impact: All complete engine: claude workflows live in pkg/cli/workflows/test-claude-*.md (test fixtures). The 6 docs-side appearances of engine: claude are mostly inline snippets or short examples in patterns/research-plan-assign-ops.md, patterns/deterministic-ops.md, setup/cli.md, reference/faq.md, and reference/frontmatter-hash-specification.md.

Why It's Problematic: A Claude user has no published "hello world" Claude workflow showing frontmatter + body together. The repo has 109 such workflows, but they're test fixtures, not documentation.

Suggested Fix: Promote one Claude test workflow into the docs as a featured example, or write a "Build Your First Claude Workflow" tutorial parallel to the Quick Start.

Affected Files: New file under docs/src/content/docs/setup/ or docs/src/content/docs/patterns/

💡 Minor Confusion Points (6)

• Claude key URL inconsistency — auth.mdx:109 directs to platform.claude.com, auth.mdx:199 directs to console.anthropic.com. Pick one.
• OpenAI key fallback chain is confusing — auth.mdx:143–145 documents CODEX_API_KEY → OPENAI_API_KEY priority, then the Azure example (L157) introduces AZURE_OPENAI_API_KEY as a third name with no recap.
• Engine list inconsistency — architecture.mdx:280 says "(Copilot, Claude, Codex)" in a diagram, omitting Gemini; other places list all four.
• README billing notice — the warning at README.md:18 about retired versions takes the same visual weight as the Overview, which can mislead new readers into thinking gh-aw itself is risky.
• engine: custom is in the type table but has 0 examples — searched the entire repo: zero .md files use engine: custom. Either remove from supported list or add an example.
• gh aw secrets bootstrap flag list — cli.md:245 documents --engine (copilot, claude, codex, gemini, crush) but crush is experimental per engines.md. The CLI docs surface experimental engines without flagging them.

---

Engine Comparison Analysis

Available Engines

Based on docs/src/content/docs/reference/engines.md:

Engine	Status	Setup Docs	Examples in Docs	Auth Docs	Overall
copilot (default)	production	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐ (58)	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐
claude	production	⭐⭐⭐⭐	⭐⭐ (6)	⭐⭐⭐⭐	⭐⭐⭐⭐
codex	production	⭐⭐⭐	⭐ (1)	⭐⭐⭐⭐	⭐⭐⭐
gemini	production	⭐⭐	⭐ (1)	⭐⭐⭐	⭐⭐
crush	experimental	⭐⭐	—	⭐⭐	⭐⭐
opencode	experimental	⭐	—	—	⭐
pi	experimental	⭐⭐	—	⭐⭐	⭐⭐

Documentation Quality by Engine

Claude scores well on the engines.md reference page (it has a max-turns section, an env-var equivalent, and bare-mode details) but is starved of tutorial-style examples. Codex and Gemini are documented at minimum-viable depth — they're listed but rarely featured.

---

Tool Availability Analysis

Engine-Agnostic Tools (work identically on Claude):

• edit, bash, github, web-fetch, playwright, cache-memory, repo-memory, qmd, agentic-workflows, cli-proxy, mcp-servers, safe-outputs, threat-detection

Engine-Specific Tools / Features:

• web-search — native on Codex (opt-in via tools.web-search:); other engines require third-party MCP
• engine.agent — Copilot only (engines.md L41)
• engine.harness — Copilot only (engines.md L44, L306)
• max-continuations — Copilot only (engines.md L38)
• max-turns — Claude only (engines.md L37)
• Tools allowlist enforcement — not supported on Crush/OpenCode

Unclear:

• engine.bare is documented for Copilot/Claude/Codex/Gemini, but its behavior on Crush/OpenCode/Pi is not stated.

---

Authentication Requirements

Quick Start guide covers authentication for:

• ✅ Copilot — detailed callout box at quick-start.mdx:75–79
• ✅ Claude — detailed callout box at quick-start.mdx:82–85
• ⚠️ Codex — link-only mention at quick-start.mdx:71
• ⚠️ Gemini — link-only mention at quick-start.mdx:71

Full auth reference (auth.mdx) covers all four engines with step-by-step setup + gh aw secrets set helpers. The reference page is solid; the Quick Start surface is uneven.

Secret Names (confirmed in auth.mdx):

• Copilot: COPILOT_GITHUB_TOKEN (fine-grained PAT with Copilot Requests: Read)
• Claude: ANTHROPIC_API_KEY
• Codex: OPENAI_API_KEY (with CODEX_API_KEY fallback; Azure uses AZURE_OPENAI_API_KEY)
• Gemini: GEMINI_API_KEY

Gaps for Claude users specifically: None critical. The ANTHROPIC_API_KEY setup is well documented and the gh aw secrets bootstrap helper auto-detects engines in use. Minor: the dual URLs (platform.claude.com vs console.anthropic.com) cause brief confusion.

---

Recommended Actions

Priority 1: Major Improvements

1. Add a Claude-first tutorial page parallel to the Quick Start — docs/src/content/docs/setup/quick-start-claude.mdx or a tabbed Quick Start.
2. Document the gh aw init Copilot dependency at docs/src/content/docs/setup/cli.md:134 — one sentence noting the dispatcher agent file is Copilot-specific.
3. Add Codex and Gemini callout boxes to quick-start.mdx so all four engines have parity in step 3.
4. Add a "Choosing an Engine" narrative section to engines.md summarizing the parity table in plain English.

Priority 2: Nice-to-Have Enhancements

1. Resolve the platform.claude.com vs console.anthropic.com URL inconsistency in auth.mdx.
2. Fix the engine list inconsistency in architecture.mdx:280 (add Gemini).
3. Remove or document engine: custom (zero examples in the repo).
4. Flag experimental engines (crush, opencode, pi) in CLI help text alongside cli.md:245.
5. Promote one pkg/cli/workflows/test-claude-*.md fixture into the docs as a featured complete example.

---

Positive Findings

• ✅ The README's overview line ("pick whichever AI account you already have") is genuinely welcoming.
• ✅ Most tools are engine-agnostic — Claude users aren't gated out of playwright, github, safe-outputs, cache-memory, MCP servers, etc.
• ✅ engines.md is thorough on Claude specifics (max-turns, env-var equivalents, bare-mode).
• ✅ auth.mdx has step-by-step setup for all four main engines, not just Copilot.
• ✅ gh aw secrets bootstrap auto-detects engines in use, so a Claude user doesn't have to know secret names in advance.
• ✅ The --engine claude flag is supported on gh aw new, gh aw add, gh aw add-wizard, gh aw compile, and gh aw trial.
• ✅ Compared to the previous review run, the docs-side Claude example count ticked from 5 to 6 — small but positive trend.

---

Conclusion

Can Claude Code Users Successfully Adopt gh-aw?

Answer: Yes, with moderate effort. No critical blockers exist. A Claude Code user can install the CLI, set ANTHROPIC_API_KEY, add a workflow with --engine claude, and run it successfully — the runtime supports it and the reference docs explain it.

The gap is editorial, not technical: every onboarding surface is written as if the reader is a Copilot user, and Claude is documented as the second-class alternative. Claude users will get there; they will just feel slightly unwelcome along the way.

Next Steps

The single highest-leverage change is a Claude-first Quick Start page (or a tabbed Quick Start that treats all four engines equally). Everything else in this report is a paper cut on that core gap.

---

Appendix: Files Reviewed

Documentation files analyzed

• README.md
• docs/src/content/docs/setup/quick-start.mdx
• 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/setup/cli.md
• docs/src/content/docs/reference/engines.md
• docs/src/content/docs/reference/auth.mdx
• Sample workflows under pkg/cli/workflows/ (counts only)
• Docs examples under docs/src/content/docs/ (counts only)

References:

• Current run: §26229012080
• Prior review: §26165163800

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

• expires on May 22, 2026, 1:37 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 #34003.