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

[github-actions[bot]]

Executive Summary

I reviewed the gh-aw documentation as a developer who uses Claude Code as their primary AI assistant and does not use GitHub Copilot or the Copilot CLI. The good news: gh-aw is genuinely multi-engine and a Claude user can adopt it without a Copilot subscription. The bad news: the onboarding path subtly assumes Copilot at several decision points, the example density skews ~5:1 toward Copilot, and one piece of "required" tooling (gh aw init) is actually Copilot-Chat-specific without that being made clear.

Key Finding: Claude Code users can successfully use gh-aw, but adoption requires reading past Copilot-first defaults in the Quick Start, recognizing that some "required" setup steps are only required for Copilot Chat authoring, and tolerating an example library where most workflows show engine: copilot. There are no true critical blockers — but there are 4 major obstacles that create real friction.

---

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, with friction. The Quick Start (docs/src/content/docs/setup/quick-start.mdx) lists all four engines as valid prerequisites on line 29 ("AI Account - GitHub Copilot, Anthropic Claude, OpenAI Codex, or Google Gemini") and add-wizard interactively prompts for the engine. A Claude user can pick "Claude" and proceed.

Where it falls apart: the prose immediately after the engine list is Copilot-shaped:

• Line 71 mentions all four secrets, but lines 76–79 contain a prominent > [!NOTE] block titled "Setting up COPILOT_GITHUB_TOKEN?" with detailed 3-step PAT setup instructions. There is no equivalent prominent note for ANTHROPIC_API_KEY. A Claude user reading top-to-bottom sees Copilot-specific PAT instructions and has to click out to the auth reference to find equivalent Claude steps.
• The recommended sample workflow githubnext/agentics/daily-repo-status does not specify an engine: field in its frontmatter, meaning the default (Copilot) applies if the user doesn't override it via add-wizard.

Specific Issues Found:

• docs/src/content/docs/setup/quick-start.mdx:76-79 — Copilot-specific NOTE block has no Claude equivalent
• docs/src/content/docs/setup/quick-start.mdx — no "What if I'm using Claude?" branch in the prose
• docs/src/content/docs/index.mdx:39 — "By the Numbers" says "4 (GitHub Copilot, Claude, OpenAI Codex, custom)" — omits Gemini (listed elsewhere), and "custom" is not actually a valid engine: value per engines.md

Recommended Fixes:

• Add a sibling > [!NOTE] block titled "Setting up ANTHROPIC_API_KEY?" with the equivalent 2-step Anthropic Console flow
• Update the home-page "By the Numbers" line to match the engines reference (Copilot, Claude, Codex, Gemini, plus experimental Crush/OpenCode)
• Consider showing a daily-repo-status variant that includes engine: claude so Claude users see their engine in the headline example

Question 2: Inaccessible Features for Non-Copilot Users

What features or steps don't work without Copilot?

Features that genuinely require Copilot (and should):

• engine.agent (custom agent files in .github/agents/) — Copilot-only by design
• engine.harness (custom Node.js harness wrapper) — Copilot-only
• max-continuations (autopilot mode) — Copilot-only
• Copilot BYOK mode (COPILOT_PROVIDER_* env vars)
• Authoring workflows via Copilot Chat on github.com / mobile — needs Copilot, obviously

Features that work without Copilot:

• All safe-outputs (create-issue, create-pull-request, add-comment, etc.)
• All built-in tools (edit, bash, github, web-fetch, web-search, playwright, cache-memory, repo-memory, qmd, agentic-workflows, cli-proxy)
• All custom MCP servers (mcp-servers:)
• Threat detection, content sanitization, secret redaction
• Network firewall (AWF)
• All CLI commands except the Copilot-Chat-authoring path
• max-turns is actually Claude-only — a feature Copilot doesn't have

Underdocumented friction point — gh aw init:

docs/src/content/docs/setup/creating-workflows.mdx:104 states:

Running gh aw init is required to enable the authoring experience in the GitHub code agent.

This wording reads as "you must run this" but in practice gh aw init only sets up the Copilot Chat dispatcher agent (.github/agents/agentic-workflows.agent.md) and Copilot-specific MCP integration. A Claude Code user who never uses Copilot Chat on github.com does not need this — they can author with Claude Code locally and use gh aw compile. The doc never says "skip this if you don't use Copilot Chat," so a careful reader assumes they're broken without it.

Missing Documentation:

• No "Claude-first onboarding path" — e.g., "If you're using Claude Code, do A, B, C; skip step D"
• The init section doesn't disclose that --no-mcp is the path for users who don't want Copilot-specific MCP setup
• No callout that gh aw init is not required for purely-local authoring with non-Copilot agents

Question 3: Documentation Gaps and Assumptions

Where does the documentation assume Copilot usage?

Copilot-Centric Language Found In:

File	Issue
docs/src/content/docs/setup/quick-start.mdx:76-79	Detailed Copilot PAT setup in NOTE block; no Claude equivalent
docs/src/content/docs/setup/creating-workflows.mdx:104	gh aw init declared "required" without disclosing it's Copilot-Chat-authoring infrastructure
docs/src/content/docs/setup/creating-workflows.mdx:118-127	Init benefits listed are all Copilot Chat features (/agent agentic-workflows is Copilot Chat syntax)
docs/src/content/docs/introduction/architecture.mdx:181-184	AWF firewall diagram subgraph labels the agent process as "Copilot CLI" only, omitting Claude/Codex/Gemini
docs/src/content/docs/reference/engines.md:27	Opinionated steer: "Copilot is the default choice for most users because it supports the broadest gh-aw feature set" — true but framed in Copilot's favor
docs/src/content/docs/index.mdx:39	"By the Numbers" lists 4 engines including a fictional "custom" entry and omitting Gemini
Examples corpus	95 copilot engine declarations vs 15 claude in the docs tree — workflows users copy/paste will skew Copilot

Missing Alternative Instructions:

• No "Quick Start: Claude path" or equivalent dedicated walkthrough
• No FAQ entry "Do I need Copilot to use gh-aw?" (the answer is "no" but you'd never know it from a 30-second skim)
• No prominent doc explaining that the default engine when omitted is Copilot — this is buried in engines.md:23

Severity-Categorized Findings

🚫 Critical Blockers (Score: 0/10)

None found. A Claude Code user can complete the Quick Start by choosing Claude in the add-wizard interactive prompt, adding ANTHROPIC_API_KEY, and running their workflow. The path exists. It's just not the path the prose walks you down.

⚠️ Major Obstacles (Score: 4/10)

Obstacle 1: Quick Start has a Copilot-only NOTE block with no Claude counterpart

Impact: Claude users get less hand-holding for the secret setup that is literally the only required setup step.

Current State: docs/src/content/docs/setup/quick-start.mdx:76-79 shows a multi-step > [!NOTE] block for COPILOT_GITHUB_TOKEN setup. The Claude path is a single hyperlink to auth.mdx#anthropic_api_key.

Why It's Problematic: The visual weight of the Quick Start signals that Copilot is "the" path and other engines are footnotes. For a Claude-first user, they have to navigate away from the Quick Start to discover the Anthropic Console URL.

Suggested Fix: Add a sibling NOTE for ANTHROPIC_API_KEY (and ideally for each engine), or replace the Copilot-specific NOTE with an engine-neutral one that branches.

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

Obstacle 2: `gh aw init` framed as "required" but only enables Copilot Chat authoring

Impact: Claude Code users either run an unnecessary command or worry they're skipping a required step.

Current State: creating-workflows.mdx:104 says gh aw init "is required to enable the authoring experience in the GitHub code agent." The benefits listed (lines 117–121) are all Copilot Chat features: a .github/agents/agentic-workflows.agent.md dispatcher and MCP server integration for Copilot.

Why It's Problematic: "Required" is doing a lot of work in that sentence. It's required if you want to author via Copilot Chat on github.com — but that's the only thing it's required for. Claude Code users editing markdown locally don't need any of it.

Suggested Fix: Reword: "gh aw init is required if you want to author workflows via Copilot Chat on github.com or the GitHub mobile app. If you author with another coding agent (Claude Code, Cursor, local editor), this step is optional." Then surface the optional bits that ARE useful for everyone (.gitattributes, VS Code settings).

Affected Files: docs/src/content/docs/setup/creating-workflows.mdx, docs/src/content/docs/setup/cli.md (the init command description)

Obstacle 3: Default engine is Copilot and that fact is buried

Impact: A user who omits engine: from a hand-written workflow gets Copilot. Claude users get a confusing failure (COPILOT_GITHUB_TOKEN missing) instead of an obvious "you forgot to set the engine."

Current State: The default is mentioned exactly once on the engines page (engines.md:23) in passing. The home page and Quick Start never call it out.

Why It's Problematic: The 95:15 example ratio in the docs tree means most copy-paste sources won't have engine: claude — they'll have engine: copilot or no engine at all. A Claude user copying any sample workflow needs to remember to change it.

Suggested Fix: Add a prominent callout in the Quick Start: "If you're using Claude/Codex/Gemini, add engine: claude (or codex / gemini) to your workflow's frontmatter. Without it, gh-aw defaults to Copilot and will require a Copilot token."

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

Obstacle 4: Recommended sample workflow has no explicit engine declaration

Impact: The headline tutorial workflow (daily-repo-status) doesn't include engine: claude, so a Claude user who copies it (instead of using add-wizard) hits the default-Copilot trap.

Current State: gh aw add-wizard githubnext/agentics/daily-repo-status works because the wizard prompts for engine. But anyone reading the workflow source as a template won't see Claude represented.

Why It's Problematic: Examples are how developers learn. With 95 Copilot examples and 15 Claude examples across the docs, Claude users get a "second-class citizen" impression even though the underlying tooling is engine-neutral.

Suggested Fix: Either (a) publish parallel Claude-engine variants of the headline workflows, or (b) add a docs convention where engine-agnostic examples explicitly say # Choose your engine: copilot | claude | codex | gemini near the frontmatter. The single instance of engine: copilot # or claude, codex, custom (found in one file) is a great pattern to extend.

Affected Files: All engine: copilot examples in docs/src/content/docs/

💡 Minor Confusion Points (Score: 6/10)

• Home page "By the Numbers" inconsistency — docs/src/content/docs/index.mdx:39 says "4 (GitHub Copilot, Claude, OpenAI Codex, custom)" — but engines.md lists 6 (Copilot, Claude, Codex, Gemini, Crush, OpenCode) and there is no "custom" engine value. Gemini is silently dropped from the headline count.
• AWF firewall diagram is Copilot-shaped — architecture.mdx:181-184 shows COPILOT["Copilot CLI"] inside the "AI Agent Process" subgraph with no Claude/Codex/Gemini equivalents. Other diagrams (e.g., architecture.mdx:280) correctly show all three. The AWF section is the visual exception.
• "Custom" engine is mentioned but undefined — Both the home page tagline and the prompt instructions for this review reference an "engine: custom" value. The engines.md table doesn't include one. Either it exists and is undocumented, or the marketing copy is wrong.
• BYOK ambiguity — Copilot BYOK mode (engines.md:199-265) lets you route Copilot CLI to an Anthropic endpoint. This is documented well but adds confusion: a Claude user could plausibly think "I need Copilot CLI + my Anthropic key" when they should actually just use engine: claude. A short callout — "If you want to use Claude, set engine: claude. BYOK mode is for users who want Copilot CLI but a non-Copilot model." — would help.
• CLAUDE_CODE_OAUTH_TOKEN explicitly NOT supported — auth.mdx:121-123 good documentation, but a Claude Pro/Max subscriber might be surprised that their existing subscription doesn't power gh-aw. This is correctly flagged but could be more discoverable (the Quick Start doesn't mention it).
• gh aw secrets bootstrap --engine claude — Documented at cli.md:223 but never referenced from the Quick Start as a Claude-friendly setup helper.

---

Engine Comparison Analysis

Available Engines

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

• engine: copilot — ⭐⭐⭐⭐⭐ Documentation is comprehensive (default, most examples, BYOK guide, custom agents, custom harness)
• engine: claude — ⭐⭐⭐⭐ Documentation is good (dedicated auth section, feature comparison table, max-turns support called out, bare mode documented)
• engine: codex — ⭐⭐⭐ Documentation is adequate (auth section, web-search quirk documented)
• engine: gemini — ⭐⭐⭐ Documentation is adequate but minimal examples
• engine: crush / opencode — ⭐⭐ Marked experimental; minimal docs

Documentation Quality by Engine

Engine	Setup Docs	Examples	Auth Docs	Overall
Copilot	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐ (95)	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐
Claude	⭐⭐⭐	⭐⭐ (15)	⭐⭐⭐⭐	⭐⭐⭐
Codex	⭐⭐⭐	⭐ (4)	⭐⭐⭐⭐	⭐⭐⭐
Gemini	⭐⭐	⭐ (1)	⭐⭐⭐	⭐⭐

---

Tool Availability Analysis

Engine-Agnostic Tools (work with Claude):

• edit, bash, github, web-fetch, playwright, cache-memory, repo-memory, qmd, agentic-workflows, cli-proxy
• All mcp-servers: configurations
• All safe-outputs: types

Engine-Specific Tool Behavior:

• web-search: native in Codex (opt-in), via third-party MCP for all others (including Claude). Documented at tools.md:65-67.
• tools.timeout: different defaults per engine (Claude: 60s, Codex: 120s, Copilot/Gemini: engine-managed). Documented at engines.md:379-385.

Engine-Specific Features:

• max-turns — Claude only ✅ (a Claude advantage, not a deficit)
• max-continuations — Copilot only
• engine.agent — Copilot only
• engine.harness — Copilot only

Verdict: Tools are well-documented as engine-agnostic. The few engine-specific behaviors are tabulated clearly. No tool is hidden from Claude users.

---

Authentication Requirements

Current Documentation Quality

Engine	Setup steps	Custom endpoint	Troubleshooting	Score
Copilot	✅ Detailed (4 steps + screenshot)	✅ GITHUB_COPILOT_BASE_URL	✅ License troubleshooting	⭐⭐⭐⭐⭐
Claude	✅ Adequate (2 steps + console link)	✅ ANTHROPIC_BASE_URL	✅ 401/403 and CLAUDE_CODE_OAUTH_TOKEN note	⭐⭐⭐⭐
Codex	✅ Adequate	✅ Azure example	✅ 401/403	⭐⭐⭐⭐
Gemini	✅ Minimal	❌ Not documented	✅ 401	⭐⭐⭐

Missing for Claude Users

• No mention in auth.mdx of how to verify the Anthropic key works before running a workflow (Copilot has the troubleshooting note pointing to a local diagnostic — Claude doesn't)
• No mention of Anthropic's rate limits / billing implications, which is a real concern for users new to the API
• The link (platform.claude.com/redacted) (auth.mdx:109) is fine but inconsistent — the troubleshooting section (auth.mdx:199) sends users to https://console.anthropic.com/`. Both URLs should be cross-referenced.

Secret Names

• Copilot: COPILOT_GITHUB_TOKEN (documented)
• Claude: ANTHROPIC_API_KEY (documented; CLAUDE_CODE_OAUTH_TOKEN explicitly not supported)
• Codex: OPENAI_API_KEY or CODEX_API_KEY (both documented)
• Gemini: GEMINI_API_KEY (documented)

---

Example Workflow Analysis

Workflow Count by Engine (across docs/src/content/docs/)

engine: copilot  - 71 raw + 24 as `id: copilot` = ~95 occurrences
engine: claude   -  7 raw + 8  as `id: claude`  = ~15 occurrences
engine: codex    -  1 raw + 3  as `id: codex`   = ~4 occurrences
engine: gemini   -  1 occurrence

Quality of Examples

Copilot Examples: Plentiful, varied, cover all patterns (issue triage, CI doctor, daily reports, custom agents).

Claude Examples: Adequate but thin. Concentrated in a few files (reference/imports.md, guides/deterministic-agentic-patterns.md, guides/serena.md, patterns/side-repo-ops.mdx). A Claude user copy-pasting from a randomly chosen doc page is much more likely to land on a Copilot example.

Codex / Gemini Examples: Sparse — Codex has a handful, Gemini essentially one.

---

Recommended Actions

Priority 1: Critical Documentation Fixes

1. Add a Claude-equivalent NOTE block to the Quick Start — mirror the Copilot setup note for ANTHROPIC_API_KEY — File: docs/src/content/docs/setup/quick-start.mdx
2. Reword the gh aw init "required" claim to disclose it's Copilot-Chat-authoring infrastructure — File: docs/src/content/docs/setup/creating-workflows.mdx
3. Surface the default-engine fact in Quick Start — explicitly tell users that omitting engine: defaults to Copilot — File: docs/src/content/docs/setup/quick-start.mdx

Priority 2: Major Improvements

1. Fix the home page "By the Numbers" engine count — match engines.md (drop fictional "custom", include Gemini) — File: docs/src/content/docs/index.mdx
2. Add the agent label for Claude/Codex/Gemini to the AWF firewall diagram — File: docs/src/content/docs/introduction/architecture.mdx:181-184
3. Publish a Claude-engine variant of daily-repo-status or similar headline workflow — even just an engine: claude parallel block in the existing example would help
4. Add an FAQ entry: "Do I need GitHub Copilot to use gh-aw?" — answer "no" prominently — File: docs/src/content/docs/reference/faq.md

Priority 3: Nice-to-Have Enhancements

1. Add a "When to use Claude vs Copilot" decision guide highlighting max-turns as a Claude-only feature
2. Reduce the 95:15 example imbalance by labelling existing Copilot examples as engine-agnostic where they truly are
3. Add a docs callout near BYOK mode clarifying it's for "Copilot CLI + non-Copilot model" not "non-Copilot users in general"
4. Cross-reference the two different Anthropic URLs (platform.claude.com and console.anthropic.com) in auth.mdx

---

Positive Findings

What Works Well

• ✅ add-wizard interactively prompts for engine — Claude users get a guided path
• ✅ auth.mdx has a dedicated, well-structured ANTHROPIC_API_KEY section with setup steps and custom endpoint guidance
• ✅ Engine feature comparison table at engines.md:33-44 is clear and shows Claude has unique advantages (max-turns)
• ✅ gh aw new --engine claude and gh aw secrets bootstrap --engine claude are first-class CLI options
• ✅ engine.bare is documented per-engine, including for Claude
• ✅ CLAUDE_CODE_OAUTH_TOKEN non-support is explicitly called out — this prevents Pro/Max subscribers from wasting time
• ✅ Tools docs are essentially engine-agnostic — no Copilot lock-in for tools
• ✅ Architecture diagrams in most places (not AWF) correctly show "Copilot, Claude, Codex" trio
• ✅ Claude Tool Enforcement Security Model (engines.md:437-470) is documented in detail — a Claude-specific concern explicitly addressed

---

Conclusion

Can Claude Code Users Successfully Adopt gh-aw?

Answer: Yes, with manageable friction.

Reasoning: The product is genuinely multi-engine — the runtime, tools, safe outputs, security model, and CLI all support Claude as a first-class engine. Authentication is well-documented. The friction is purely at the documentation surface level: the Quick Start's narrative voice is Copilot-shaped, the example density is heavily Copilot, and one piece of "required" tooling (gh aw init) is actually optional for non-Copilot users without that being said. A motivated Claude Code user will get through this in 15–20 minutes. A casual reader scanning the home page might bounce, assuming Copilot is required.

The biggest single win for Claude users would be a 3-paragraph addition to the Quick Start: a Claude-flavored secret setup note, an explicit statement that omitting engine: defaults to Copilot, and a one-line "skip gh aw init if you don't author via Copilot Chat."

Overall Assessment Score: 7/10

Breakdown:

• Clarity for non-Copilot users: 6/10
• Claude engine documentation: 7/10
• Alternative approaches provided: 7/10
• Engine parity (feature support): 8/10 — most things work, max-turns is a Claude win
• Engine parity (documentation): 5/10 — 5:1 example imbalance

Next Steps

1. Quick win — patch the three Priority 1 items in the Quick Start and creating-workflows.mdx. These are small text changes with high ROI.
2. Medium-term — rebalance the example library so the engine ratio better reflects the multi-engine product.
3. Long-term — consider a "Quick Start: Claude path" sibling page, similar to how some multi-stack tools have parallel onboarding for each supported stack.

---

Appendix: Files Reviewed

Complete List of Documentation Files Analyzed

• README.md
• docs/src/content/docs/index.mdx
• 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/reference/tools.md
• docs/src/content/docs/reference/engines.md
• docs/src/content/docs/reference/auth.mdx
• docs/src/content/docs/examples/multi-repo.md (sampled)
• Cross-cutting grep of engine: declarations across the full docs tree

---

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

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

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

[github-actions[bot]]

This discussion was automatically closed because it expired on 2026-05-14T13:16:25.497Z.

Closed by Workflow