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

[github-actions[bot]]

Executive Summary

As a developer who uses Claude Code exclusively and actively avoids GitHub Copilot, I reviewed the gh-aw documentation to assess adoption viability. The overall picture is positive: Claude users can get started with gh-aw and the core docs explicitly list Claude as a supported engine. However, several friction points remain — particularly around authentication edge cases, architecture diagrams that imply Copilot-first design, and missing alternatives for Copilot-only features.

Key Finding: Claude Code users can successfully adopt gh-aw, but will hit meaningful friction points that could make them question whether the platform was designed with them in mind.

---

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 Copilot subscription

---

Question 1: Onboarding Experience

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

Short answer: Yes, with minor friction. The Quick Start guide (docs/src/content/docs/setup/quick-start.mdx) lists all three major AI providers up front in the prerequisites:

"AI Account - GitHub Copilot, Anthropic Claude or OpenAI Codex"

The add-wizard step is even better — it explicitly says "Select an AI Engine - Choose between Copilot, Claude, or Codex." This means a Claude user will not hit a wall during the interactive onboarding flow.

However, a few issues erode confidence along the way:

Specific Issues Found:

• Issue 1: The prerequisites list Gemini as a full engine in engines.md but omit it from quick-start.mdx prerequisites and from the add-wizard engine selection description. A Gemini user would be confused.
• Issue 2: The configuration example in architecture.mdx (line 228) uses engine: copilot without showing a multi-engine alternative, implying Copilot is "the" way.
• Issue 3: There is no "Why would I choose Claude over Copilot?" guidance anywhere in the docs. Users who actively prefer Claude must infer use-case differences from the feature comparison table alone.

Recommended Fixes:

• Add Gemini to the Quick Start prerequisites and add-wizard description
• Add a brief "Which engine should I choose?" section to engines.md or quick-start.mdx
• In architecture.mdx configuration examples, show engine: claude as an alternative

---

Question 2: Inaccessible Features for Non-Copilot Users

What features or steps don't work without Copilot?

Features That Require Copilot:

• engine.agent — Custom agent files (.github/agents/*.agent.md) are a Copilot-only feature. The copilot-custom-agents.md reference page exists; there is no Claude equivalent documented.
• max-continuations — Autopilot mode (multiple consecutive agent runs) is Copilot-only. The engines.md table notes this with ❌ for all other engines.
• assign-to-copilot — The assign-to-copilot.mdx safe-output is Copilot-specific by design and acceptable as such, but it adds to the "Copilot feels like first class" impression.
• CLAUDE_CODE_OAUTH_TOKEN auth method — Claude Code's standard OAuth flow (used by Claude Teams/Max subscribers) is explicitly not supported. Only ANTHROPIC_API_KEY works. This is documented in auth.mdx but represents a real blocker for Claude users who don't have separate API access.

Features That Work Without Copilot:

• All core tools: edit, bash, github, web-fetch, playwright, cache-memory, repo-memory, agentic-workflows
• Safe outputs: create-issue, add-comment, create-pull-request, all standard outputs
• All CLI commands: gh aw init, add-wizard, compile, run, logs, audit — all engine-agnostic
• MCP server integration (engine-agnostic)
• All security features: AWF firewall, threat detection, secret redaction

Missing Documentation:

• No documented Claude alternative to Copilot's engine.agent custom agent file system
• No documented workaround for users with Claude Teams/Max who want OAuth authentication
• No explicit note explaining that gh aw init creates a dispatcher agent file (.github/agents/agentic-workflows.agent.md) that is Copilot CLI-specific in the agent-configuration sense

---

Question 3: Documentation Gaps and Assumptions

Where does the documentation assume Copilot usage?

Copilot-Centric Language Found In:

• File: docs/src/content/docs/introduction/architecture.mdx — Lines 181, 209, 252: The Agent Workflow Firewall (AWF) Mermaid diagrams label the agent process as "Copilot CLI" and "Copilot CLI + MCP client". A Claude or Codex user reading the security architecture page sees architecture diagrams implying their engine does not fit. This contradicts the later MCP sandboxing diagram (line 279) which correctly shows "AI Engine\n(Copilot, Claude, Codex)".
• File: docs/src/content/docs/reference/engines.md — The api-target configuration examples (GHEC and GHES sections) both use engine: copilot without showing Claude or Codex alternatives.
• File: docs/src/content/docs/reference/auth.mdx — The CLI example for adding secrets uses COPILOT_GITHUB_TOKEN as the featured secret name (even though alternatives are documented below it).

Missing Alternative Instructions:

• No "Getting started with Claude engine" dedicated guide or section
• No explanation of how CLAUDE_CODE_MAX_TURNS relates to the max-turns frontmatter field (it is mentioned in engines.md under Timeout Configuration, but only in passing)
• No guidance on cost management specifically for Claude users (Claude API pricing differs from Copilot's subscription model)

---

Severity-Categorized Findings

🚫 Critical Blockers (Score: 1/10 — Only one real blocker, affecting a subset of Claude users)

Blocker 1: CLAUDE_CODE_OAUTH_TOKEN Not Supported — Claude Teams/Max Users Cannot Authenticate

Impact: Claude Max and Claude Teams subscribers who authenticate via OAuth (the standard Claude Code flow) cannot use their existing credentials.

Current State: auth.mdx contains this note:

"CLAUDE_CODE_OAUTH_TOKEN is not supported by GitHub Agentic Workflows. The only supported authentication method for the Claude engine is ANTHROPIC_API_KEY. Provider-based OAuth authentication (such as billing through a Claude Teams or Claude Max subscription) is not supported."

Why It's a Blocker: A developer using Claude Code daily likely authenticates via claude auth login (OAuth), which creates a CLAUDE_CODE_OAUTH_TOKEN. They may not have a separate ANTHROPIC_API_KEY from the API console if they've only ever used Claude through a Teams/Max plan. The documentation correctly identifies this, but does not explain how to obtain a separate API key if you're coming from a Teams context, nor does it explain whether API access is included with Teams.

Fix Required: Add a note explaining: "If you use Claude Teams or Claude Max, you still need a separate ANTHROPIC_API_KEY from the Anthropic Console (console.anthropic.com). API access is separate from your Claude subscription plan."

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

⚠️ Major Obstacles (Score: 5/10 — Real friction but workable)

Obstacle 1: Architecture Diagrams Show "Copilot CLI" as the Agent Process

Impact: Significant confusion when reading the Security Architecture page

Current State: In architecture.mdx, the AWF firewall diagram (the most prominent security visualization) labels the "AI Agent Process" subgraph with specifically COPILOT["Copilot CLI"]. The MCP gateway diagram goes further, labeling the agent container as "Copilot CLI + MCP client". Both diagrams show Copilot as the only agent, contradicting the text which says all engines use the same security architecture.

Why It's Problematic: A Claude Code user evaluating whether gh-aw is secure for their use case reads the security page and sees their engine is absent from the diagrams. This creates false uncertainty: "Does the firewall work with Claude too?" The later MCP sandboxing diagram correctly shows AI Engine (Copilot, Claude, Codex) — the inconsistency compounds the confusion.

Suggested Fix: Update the AWF firewall diagram node from COPILOT["Copilot CLI"] to ENGINE["AI Engine\n(Copilot/Claude/Codex)"] and update the MCP gateway diagram similarly.

Affected Files: docs/src/content/docs/introduction/architecture.mdx (lines 181, 209, 252)

Obstacle 2: Copilot-Only Features Have No Claude Alternatives Documented

Impact: Feature discovery gap — Claude users don't know what they're missing or how to work around it

Current State: The feature comparison table in engines.md correctly marks engine.agent and max-continuations as Copilot-only (❌ for Claude). However, there is no guidance on:

• What a Claude user should do instead of engine.agent (custom agent behavior)
• What alternative to max-continuations exists for Claude users who want long-running multi-step automation

Why It's Problematic: Without alternatives documented, Claude users hitting these limitations may abandon gh-aw instead of finding a workaround (e.g., using max-turns + scheduling multiple workflow runs).

Suggested Fix: Add a "Copilot-only features and Claude alternatives" section or callout in engines.md explaining that max-turns serves a similar bounding purpose to max-continuations, and that custom behavior for Claude can be specified directly in the workflow markdown body.

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

Obstacle 3: No "Why Claude?" Guidance in Onboarding

Impact: Users who prefer Claude are not given any reason to confirm their choice, while Copilot is highlighted as "default"

Current State: The engines reference table shows copilot with "(default)" in the description. There is no explanation of when Claude might be preferred over Copilot or vice versa.

Why It's Problematic: For users coming from the Claude Code ecosystem who are evaluating gh-aw, the "default" framing combined with the absence of Claude-specific advantages makes the platform feel Copilot-first. This is a trust/confidence issue rather than a technical blocker.

Suggested Fix: Add a brief "Choosing an Engine" section to the Quick Start or engines page that explains: Copilot requires a GitHub Copilot subscription; Claude uses Anthropic's API (pay-as-you-go); Codex uses OpenAI's API. Mention any practical tradeoffs (e.g., Claude supports max-turns for iteration control).

Affected Files: docs/src/content/docs/setup/quick-start.mdx or docs/src/content/docs/reference/engines.md

💡 Minor Confusion Points (Score: 4/10)

• Gemini Omitted from Quick Start Prerequisites: quick-start.mdx lists Copilot/Claude/Codex but not Gemini; engines.md lists Gemini as fully supported with its own secret.
• Auth Page CLi Example is Copilot-First: The auth.mdx CLI example under "Adding secrets using the CLI" shows COPILOT_GITHUB_TOKEN before mentioning any other engine's secret.
• api-target Examples Are All Copilot: The GHEC and GHES enterprise endpoint examples in engines.md use engine: copilot without showing Claude equivalents, even though api-target works with all engines.
• gh aw init Description Doesn't Mention Engine Choice: The init command creates a .github/agents/agentic-workflows.agent.md file, which is a Copilot agent configuration file. The CLI docs don't explain how this interacts with non-Copilot engines.
• Web Search Note Buried: The note that web search requires a third-party MCP server for Claude (while Codex has native support) is a footnote in the tools table rather than a visible callout.

---

Engine Comparison Analysis

Available Engines

Based on documentation review, gh-aw supports these engines:

• engine: copilot — Exceptionally well-documented; has dedicated custom agents guide and troubleshooting sections
• engine: claude — Well-documented at a functional level; auth instructions are clear and correct
• engine: codex — Moderately documented; web search opt-in note could be more prominent
• engine: gemini — Minimally documented; present in engines reference but absent from quick start

Documentation Quality by Engine

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

Rating Scale: ⭐⭐⭐⭐⭐ (Excellent) to ⭐ (Poor/Missing)

---

Tool Availability Analysis

Tools Review

Engine-Agnostic Tools (work with all engines):

• edit, bash, github, web-fetch, playwright, cache-memory, repo-memory
• qmd (documentation search), agentic-workflows (introspection), mcp-servers (custom MCP)

Engine-Specific Tools:

• web-search — Native in Codex; requires third-party MCP for all others (Copilot, Claude, Gemini)
• engine.agent — Copilot custom agent files only
• max-continuations — Copilot autopilot mode only
• max-turns — Claude only (iteration cap)

Unclear/Undocumented:

• How gh aw init's generated .github/agents/agentic-workflows.agent.md interacts with non-Copilot engines
• Whether tools.web-search declaration on Claude triggers any behavior without an MCP server configured

---

Authentication Requirements

Current Documentation

Quick Start guide covers authentication for:

• ✅ Copilot (detailed instructions with pre-filled PAT creation link)
• ✅ Claude (found — ANTHROPIC_API_KEY, clear setup instructions in auth.mdx)
• ✅ Codex (found — OPENAI_API_KEY with Azure OpenAI variant documented)
• ✅ Gemini (found — GEMINI_API_KEY in auth.mdx)

Missing for Claude Users

• No instructions for obtaining an API key if you only have a Claude Teams/Max plan
• No guidance on whether API usage costs are separate from Teams/Max subscription costs
• OAuth token (CLAUDE_CODE_OAUTH_TOKEN) rejection is documented but no migration path is offered

Secret Names

• Copilot: COPILOT_GITHUB_TOKEN (documented with pre-filled PAT creation link — excellent UX)
• Claude: ANTHROPIC_API_KEY (documented with link to docs)
• Codex: OPENAI_API_KEY or CODEX_API_KEY (both documented)
• Gemini: GEMINI_API_KEY (documented)

---

Example Workflow Analysis

Workflow Count by Engine (in .github/workflows/*.md)

Engine: copilot — 87 workflows found
Engine: claude  — 46 workflows found
Engine: codex   — 10 workflows found
Engine: gemini  —  0 workflows found

Quality of Examples

Copilot Examples (87): Extensive. Covers monitoring, triaging, code review, documentation — the full spectrum of use cases.

Claude Examples (46): Solid. Covers substantive use cases including API consumption reports, approach validation, blog auditing, audit workflows, and more. A Claude user can find real examples to learn from. The number (46) is meaningful and demonstrates genuine Claude usage.

Codex Examples (10): Limited. Functional but narrow set of examples.

Gemini Examples (0): No example workflows. A Gemini user has no reference implementations to study.

---

Recommended Actions

Priority 1: Critical Documentation Fixes

1. Clarify API key requirement for Claude Teams/Max users — Add a note in auth.mdx explaining that ANTHROPIC_API_KEY requires a separate Anthropic API account (console.anthropic.com), distinct from a Claude Teams or Max subscription. - File: docs/src/content/docs/reference/auth.mdx
2. Fix AWF architecture diagrams — Change COPILOT["Copilot CLI"] to a generic ENGINE["AI Engine"] in the firewall and MCP gateway Mermaid diagrams to reflect that all engines use the same security architecture. - File: docs/src/content/docs/introduction/architecture.mdx (lines 181, 209, 252)

Priority 2: Major Improvements

1. Add "Choosing an Engine" guidance — A short section in quick-start.mdx or engines.md explaining when to pick Claude vs Copilot vs Codex (subscription model, feature parity, cost model). - File: docs/src/content/docs/reference/engines.md
2. Document Claude alternatives to Copilot-only features — Add a callout in engines.md explaining that max-turns provides iteration bounding for Claude, and that workflow markdown body replaces engine.agent for custom behavior. - File: docs/src/content/docs/reference/engines.md
3. Add Gemini to Quick Start prerequisites — The prerequisites list should match the engines table. - File: docs/src/content/docs/setup/quick-start.mdx

Priority 3: Nice-to-Have Enhancements

1. Add Claude-specific api-target examples — Show ANTHROPIC_BASE_URL usage in the enterprise endpoint section of engines.md alongside the existing Copilot examples.
2. Create a "Claude Engine Guide" — A dedicated page (similar to copilot-custom-agents.md) covering Claude-specific features: max-turns, ANTHROPIC_BASE_URL, token cost tracking, and model selection.
3. Add a Gemini example workflow — At least one reference implementation for Gemini users.

---

Positive Findings

What Works Well

• ✅ Quick Start wizard is truly engine-agnostic — add-wizard prompts for engine selection and handles all secret types interactively. A Claude user can complete onboarding without any extra steps.
• ✅ Authentication documentation is comprehensive — Every engine has a dedicated section in auth.mdx with clear, actionable setup steps.
• ✅ CLAUDE_CODE_OAUTH_TOKEN anti-pattern is explicitly called out — The docs proactively address what Claude Code users might try and explain why it won't work.
• ✅ 46 Claude engine workflows — The repo itself uses Claude extensively, providing real-world examples that Claude users can study.
• ✅ Engine feature comparison table — engines.md has a clear matrix showing what works and doesn't work per engine.
• ✅ gh aw secrets bootstrap --engine claude — The secrets CLI knows about Claude specifically, making setup frictionless.
• ✅ gh aw new --engine claude — The workflow scaffolding tool correctly generates Claude-flavored frontmatter templates.
• ✅ max-turns is a Claude-specific feature — The fact that Claude Code users get a useful, Claude-only capability (max-turns) is a genuine selling point that should be highlighted more prominently.

---

Conclusion

Can Claude Code Users Successfully Adopt gh-aw?

Answer: Yes, With Minor Effort

The documentation has clearly been updated to treat Claude as a first-class engine. The Quick Start guide, authentication docs, and CLI tooling all handle Claude correctly. A Claude Code user willing to read the full docs and obtain an ANTHROPIC_API_KEY from the Anthropic Console can get a workflow running within the stated 10-minute estimate.

The friction points are real but not prohibitive: the architecture diagrams create false uncertainty, the lack of a "why Claude?" narrative makes the platform feel Copilot-first, and Claude Teams/Max users face an underdocumented prerequisite (needing a separate API key). None of these are technical blockers — they're documentation gaps that reduce confidence and increase time-to-first-success.

Overall Assessment Score: 7/10

Breakdown:

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

Next Steps

1. Fix the AWF architecture diagrams (quick win, high trust impact)
2. Add the Claude Teams/Max API key clarification to auth.mdx
3. Consider adding a brief "Choosing an Engine" section to the Quick Start
4. Long-term: create a dedicated Claude Engine Guide similar to the existing Copilot agents guide

---

Appendix: Files Reviewed

Complete List of 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
• .github/workflows/api-consumption-report.md (sample Claude workflow)
• .github/workflows/claude-code-user-docs-review.md (this workflow itself)

Also reviewed via grep:

• 46 Claude engine workflows (.github/workflows/*.md)
• 87 Copilot engine workflows (.github/workflows/*.md)
• 10 Codex engine workflows (.github/workflows/*.md)

---

References:

• §24724386004

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

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

• expires on Apr 22, 2026, 1:20 PM UTC