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

[github-actions[bot]]

Executive Summary

As a developer who uses Claude Code as my primary AI assistant and does not use GitHub Copilot, I reviewed the gh-aw documentation to assess whether I could understand, set up, and adopt this tooling. The verdict: yes, with moderate effort. The documentation is broadly inclusive with solid Claude-specific content, but Copilot remains the implicit default throughout, with some significant features (web interface authoring, custom agent files, autopilot mode) being Copilot-exclusive with no documented Claude equivalent.

Key Finding: Claude Code users can successfully use gh-aw. Authentication documentation is clear, 46 example workflows use engine: claude, and the add-wizard onboarding flow handles engine selection. However, several friction points and Copilot-centric framings create unnecessary confusion.

---

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 — the Quick Start guide (docs/src/content/docs/setup/quick-start.mdx) explicitly lists all AI options in the prerequisites:

AI Account — GitHub Copilot, Anthropic Claude, OpenAI Codex, or Google Gemini

The add-wizard interactive setup prompts for engine selection and the correct secret. This is the best part of the onboarding experience for non-Copilot users.

Specific Issues Found:

• Issue 1: creating-workflows.mdx, the GitHub Web Interface section opens with "If you have access to GitHub Copilot, you can create and edit Agentic Workflows directly from the Web Interface." A Claude Code user immediately learns this authoring path is closed to them. There is no callout saying "Claude users, start here instead."
• Issue 2: creating-workflows.mdx Step 3 reads: "If not using Copilot, also adjust the engine: field" — this subtly frames Copilot as the baseline everyone starts from.
• Issue 3: gh aw init creates a dispatcher agent at .github/agents/agentic-workflows.agent.md that enables /agent agentic-workflows in Copilot Chat on github.com. Claude users who run gh aw init get a file they cannot use and no explanation of what it does for their workflow.

Recommended Fixes:

• Add a "Not using Copilot? Start here →" callout at the top of the Creating Workflows web interface section
• Rename Step 3 in creating-workflows.mdx to "Configure your AI engine" and make it engine-neutral
• Add a note in the gh aw init description clarifying which parts are Copilot-specific vs. universal

---

Question 2: Inaccessible Features for Non-Copilot Users

What features or steps don't work without Copilot?

Features That Require Copilot:

• Web interface workflow authoring (github.com Copilot Chat + /agent agentic-workflows) — the primary "create workflows without leaving GitHub" experience
• engine.agent (custom agent files) — engine.agent: technical-doc-writer to reference .github/agents/ files is Copilot-only; engine.harness is also Copilot-only
• max-continuations (autopilot mode) — allows multiple sequential agent runs; no Claude equivalent exists
• Crush and OpenCode engines — currently require COPILOT_GITHUB_TOKEN, creating confusing dependency on Copilot infrastructure even for nominally non-Copilot engines

Features That Work Without Copilot (Engine-Agnostic):

• All 8 built-in tools: edit, github, bash, web-fetch, playwright, cache-memory, repo-memory, agentic-workflows
• Safe outputs (create issue, add comment, create PR, etc.)
• MCP server integration (custom mcp-servers:)
• The entire compilation pipeline (gh aw compile)
• gh aw add-wizard, gh aw run, gh aw logs, gh aw audit
• gh aw secrets bootstrap --engine claude
• gh aw new --engine claude
• max-turns (Claude-exclusive) for iteration control

Missing Documentation:

• No "here's what Claude users get instead of autopilot" guide — max-turns is mentioned in the feature table but not with context around how to achieve similar long-running session goals
• No explanation of what gh aw init does for Claude users specifically vs. Copilot users

---

Question 3: Documentation Gaps and Assumptions

Where does the documentation assume Copilot usage?

Copilot-Centric Language Found In:

• File: docs/src/content/docs/reference/engines.md — "Copilot is the default choice for most users because it supports the broadest gh-aw feature set" — accurate but discouraging for Claude users without explaining Claude's strengths
• File: docs/src/content/docs/introduction/architecture.mdx — the AWF network configuration example uses engine: copilot exclusively; no Claude/Codex equivalent shown
• File: docs/src/content/docs/setup/creating-workflows.mdx — gh aw init description ties the feature to "Copilot coding agent" and "Copilot Chat on github.com" without flagging this as optional for non-Copilot users

Missing Alternative Instructions:

• No "How to author workflows using Claude Code locally" quick guide
• No explanation of CLAUDE_CODE_OAUTH_TOKEN being unsupported appearing in the Quick Start; it's buried in auth.mdx (though well-documented there once found)
• No guide on using Claude Code itself (the tool) to author gh-aw workflows — the creating-workflows guide mentions "VSCode/Claude/Codex/Copilot" but doesn't tailor instructions to Claude Code CLI users

---

Severity-Categorized Findings

🚫 Critical Blockers (Score: 0/10)

There are no critical blockers. A Claude Code user with ANTHROPIC_API_KEY can successfully run workflows today.

⚠️ Major Obstacles (Score: 6/10)

Obstacle 1: OAuth authentication confusion — CLAUDE_CODE_OAUTH_TOKEN silently fails

Impact: Claude Code users are accustomed to CLAUDE_CODE_OAUTH_TOKEN for local Claude Code authentication. Setting this as a repository secret will silently fail with no obvious error at setup time.

Current State: auth.mdx explicitly says: "CLAUDE_CODE_OAUTH_TOKEN is not supported... configure ANTHROPIC_API_KEY instead." This is good documentation — but only visible after the user has already searched for Claude authentication. It is not surfaced in the Quick Start.

Why It's Problematic: A Claude Code user setting up gh-aw for the first time will naturally reach for CLAUDE_CODE_OAUTH_TOKEN — it's what they use every day. The Quick Start mentions ANTHROPIC_API_KEY in a list, but doesn't call out that OAuth/subscription auth is not supported.

Suggested Fix: Add a note in the Quick Start add-wizard step saying: "Claude users: gh-aw requires ANTHROPIC_API_KEY from the Anthropic Console. CLAUDE_CODE_OAUTH_TOKEN (used by the Claude Code desktop app) is not supported."

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

Obstacle 2: gh aw init creates Copilot-specific files with no warning for Claude users

Impact: Claude users who follow the "Initialize the Repository" step get a Copilot dispatcher agent file that provides no value to them and may cause confusion.

Current State: creating-workflows.mdx says gh aw init is "required to enable the authoring experience in the GitHub code agent." The description then lists Copilot-specific benefits: "registers the agentic-workflows custom agent in GitHub Copilot", enables /agent agentic-workflows in Copilot Chat.

Why It's Problematic: A Claude Code user reading "required to enable the authoring experience" will run gh aw init, then try to understand why their Claude Code workflow didn't change. The command does still configure .gitattributes and VS Code settings (useful for all users), but the main advertised benefit is Copilot-specific.

Suggested Fix: Add a "For Claude/Codex/Gemini users:" note clarifying which gh aw init steps are engine-agnostic (.gitattributes, VS Code settings) vs. Copilot-specific (dispatcher agent).

Affected Files: docs/src/content/docs/setup/creating-workflows.mdx

Obstacle 3: No equivalent guidance for Copilot-exclusive features

Impact: Claude users reading the feature comparison table see gaps without guidance on workarounds.

Current State: The engines.md feature comparison table correctly marks max-continuations as Copilot-only and max-turns as Claude-only. The "Which engine should I choose?" section says "Choose Claude when you want stronger control over turn limits (max-turns) for long reasoning sessions" — this is helpful but brief.

Why It's Problematic: max-continuations enables "autopilot mode with multiple consecutive runs" — a powerful feature. A Claude user wants to know: how do I achieve long-running autonomous tasks without autopilot? The answer (use max-turns + timeout-minutes tuning) exists but isn't explained in the context of "here's how you replace autopilot with Claude."

Suggested Fix: Add a "Long-running tasks with Claude" section in the engines reference showing how max-turns + timeout-minutes configuration compares to Copilot's max-continuations approach.

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

Obstacle 4: Web interface authoring is Copilot-exclusive with no clear Claude path

Impact: Claude Code users cannot use the "Create a workflow on github.com" approach, but this isn't clearly explained upfront.

Current State: creating-workflows.mdx starts with a GitHub web interface section gated on Copilot access, then has a combined "VSCode/Claude/Codex/Copilot" section with generic CLI instructions.

Why It's Problematic: For a Claude Code user, the workflow for creating new workflows is: start Claude Code locally, give it the create.md URL prompt. This works well but isn't called out as the canonical Claude Code path. The guide buries this in a generic multi-platform section.

Suggested Fix: Add engine-specific tabs (or a "Using Claude Code" callout) to the creating-workflows guide showing the exact Claude Code workflow.

Affected Files: docs/src/content/docs/setup/creating-workflows.mdx

💡 Minor Confusion Points (Score: 8/10)

• Architecture firewall config example uses engine: copilot without showing alternatives — File: docs/src/content/docs/introduction/architecture.mdx
• "Copilot is the default choice for most users" phrasing without counterbalancing Claude strengths — File: docs/src/content/docs/reference/engines.md
• README.md has almost no content beyond a brief intro and 900+ lines of community contributors — a Claude Code user gets no orientation from the README
• No "I use Claude Code, how do I get started?" entry point in the documentation navigation

---

Engine Comparison Analysis

Documentation Quality by Engine

Engine	Setup Docs	Examples	Auth Docs	Overall Score
Copilot	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐
Claude	⭐⭐⭐⭐	⭐⭐⭐⭐	⭐⭐⭐⭐⭐	⭐⭐⭐⭐
Codex	⭐⭐⭐	⭐⭐	⭐⭐⭐⭐	⭐⭐⭐
Gemini	⭐⭐⭐	⭐ (0 example workflows)	⭐⭐⭐⭐	⭐⭐

Rating Scale: ⭐⭐⭐⭐⭐ Excellent → ⭐ Poor/Missing

Notable: Gemini has 0 example workflows in the repo, and Codex has only 11 compared to Claude's 46. Claude is the second-best documented engine by a significant margin.

---

Tool Availability Analysis

Engine-Agnostic Tools (work with all engines):

• edit, github, bash, web-fetch, playwright, cache-memory, repo-memory, agentic-workflows, qmd
• All custom mcp-servers: configurations

Engine-Specific Behavior:

• web-search: — Codex has native support; Copilot, Claude, Gemini require a third-party MCP server
• tools.timeout defaults differ — Claude: 60s, Codex: 120s, others: engine-managed
• max-turns — Claude only
• max-continuations — Copilot only

Copilot-Only Features (no Claude/Codex equivalent):

• engine.agent (custom agent files in .github/agents/)
• engine.harness (custom harness script)
• /agent agentic-workflows web interface authoring
• max-continuations autopilot mode

---

Authentication Requirements

Current Documentation Status

Engine	Required Secret	Auth Docs Quality
Copilot	COPILOT_GITHUB_TOKEN	✅ Excellent — step-by-step with direct link
Claude	ANTHROPIC_API_KEY	✅ Excellent — clear, with troubleshooting
Codex	OPENAI_API_KEY	✅ Good — Azure endpoint documented too
Gemini	GEMINI_API_KEY	✅ Good

Missing for Claude Users:

• Quick Start doesn't explicitly call out that CLAUDE_CODE_OAUTH_TOKEN is NOT supported
• No link from Quick Start to the "Claude-specific auth warnings" section of auth.mdx

---

Example Workflow Analysis

Workflow Count by Engine

Engine: copilot         — 90 workflows
Engine: copilot (none)  — 24 workflows (defaults to Copilot)  
Engine: claude          — 46 workflows
Engine: codex           — 11 workflows
Engine: gemini          — 0 workflows
Total                   — 204 workflows

Claude Examples Assessment: The 46 Claude workflows include the workflow running this very review (claude-code-user-docs-review.md), plus api-consumption-report, audit-workflows, aw-failure-investigator, blog-auditor, and many others. Coverage is solid — these are real, substantive workflows demonstrating Claude's capabilities.

---

Recommended Actions

Priority 1: Critical Documentation Fixes

1. Add CLAUDE_CODE_OAUTH_TOKEN warning to Quick Start — Explicitly note in Step 2 of quick-start.mdx that OAuth/subscription auth is not supported; ANTHROPIC_API_KEY is required. File: docs/src/content/docs/setup/quick-start.mdx

2. Clarify gh aw init for non-Copilot users — Add a note distinguishing Copilot-specific init features (dispatcher agent, /agent agentic-workflows) from universal features (.gitattributes, VS Code settings). File: docs/src/content/docs/setup/creating-workflows.mdx

3. Add Claude Code entry point to creating-workflows guide — Add a dedicated "Using Claude Code" tab or callout in the creating-workflows guide showing the exact workflow: start Claude Code locally, provide the create.md URL prompt, run gh aw compile. File: docs/src/content/docs/setup/creating-workflows.mdx

Priority 2: Major Improvements

1. Add "Long-running tasks with Claude" section to engines.md — Explain how to use max-turns + timeout-minutes as an alternative to Copilot's max-continuations autopilot mode. File: docs/src/content/docs/reference/engines.md

2. Add Claude example to architecture firewall config — Show engine: claude variant alongside the engine: copilot network configuration example. File: docs/src/content/docs/introduction/architecture.mdx

3. Reframe "Which engine should I choose?" for Claude users — Currently says Copilot is "the default choice for most users." Add a "Choose Claude if..." section with more than just max-turns — mention: familiar Claude Code tooling, Anthropic billing, BYOK deployments.

Priority 3: Nice-to-Have Enhancements

1. Add a "Claude Code User Quick Start" guide — A dedicated path for users coming from Claude Code that skips Copilot-centric content and focuses on API key setup, engine: claude workflows, and max-turns configuration.

2. Add Gemini example workflows — Currently 0 example workflows use Gemini, which suggests this engine is under-tested or under-documented.

3. Add "FAQ for non-Copilot users" — Common questions: "Do I need Copilot to use gh-aw?" (No), "Can I author workflows without Copilot?" (Yes, via CLI), "Is CLAUDE_CODE_OAUTH_TOKEN supported?" (No, use ANTHROPIC_API_KEY).

---

Positive Findings

What Works Well

• ✅ Prerequisites section lists all 4 AI options — Quick Start immediately establishes gh-aw as a multi-engine tool
• ✅ ANTHROPIC_API_KEY auth is clearly documented — Complete instructions with troubleshooting, and explicit warning that OAuth token is unsupported
• ✅ 46 Claude example workflows — Substantial coverage at 22.5% of all workflows; includes sophisticated real-world examples
• ✅ add-wizard handles engine selection interactively — The onboarding wizard asks you to choose your engine, removing ambiguity
• ✅ Feature comparison table is honest — Clearly shows what's Copilot-only vs. Claude-only vs. shared
• ✅ max-turns is documented as a Claude strength — The engines reference mentions this uniquely benefits long Claude sessions
• ✅ gh aw secrets bootstrap --engine claude is supported — Validates the Claude-specific secret name without running Copilot checks
• ✅ Custom ANTHROPIC_BASE_URL is documented — Enterprise/proxy deployments are covered

---

Conclusion

Can Claude Code Users Successfully Adopt gh-aw?

Answer: Yes, With Moderate Effort

Reasoning: A Claude Code user who works through the documentation can successfully deploy gh-aw workflows using engine: claude. The authentication documentation is excellent, the feature comparison table is honest about engine differences, and 46 example workflows using Claude demonstrate real-world applicability. The add-wizard onboarding path handles engine selection gracefully.

The friction comes from the implicit Copilot-as-default framing that appears throughout: the creating-workflows guide leads with a Copilot-exclusive feature, gh aw init creates Copilot-specific files without explanation, and the engine recommendation section steers toward Copilot as the primary choice. A Claude Code user needs to mentally filter these signals while assembling their own Claude-specific setup path.

The most important undocumented risk is CLAUDE_CODE_OAUTH_TOKEN not being supported — a Claude Code user's most natural first attempt at authentication will silently fail.

Overall Assessment Score: 6.5/10

Category	Score
Clarity for non-Copilot users	7/10
Claude engine documentation	6/10
Alternative approaches provided	6/10
Engine parity	5/10

Next Steps

1. Add a CLAUDE_CODE_OAUTH_TOKEN warning to the Quick Start (highest impact, easiest fix)
2. Add a Claude Code entry point to the creating-workflows guide
3. Clarify gh aw init scope for non-Copilot users
4. Add a "long-running tasks with Claude" guide as an alternative to Copilot autopilot

---

Appendix: Files Reviewed

• 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
• docs/src/content/docs/setup/creating-workflows.mdx
• .github/workflows/*.md (204 workflows analyzed for engine distribution)

---

References:

• §25055196396

Generated by Claude Code User Documentation Review · ● 308.1K · ◷

• expires on Apr 29, 2026, 1:26 PM UTC