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

[github-actions[bot]]

Executive Summary

As a developer who uses Claude Code and deliberately avoids GitHub Copilot, I reviewed the gh-aw documentation to determine whether I could successfully understand and adopt this tool. The good news: Claude Code users can fully adopt gh-aw without major blockers. The documentation covers all four AI engines, authentication is clearly documented, and 57 of 204 live workflows (28%) already use engine: claude. The friction points are primarily around Copilot-centric framing in a few places, one common Claude-user gotcha that needs more prominence, and some engine-specific diagrams that could mislead.

Key Finding: Claude Code users can successfully use gh-aw. The main risk is a subtle authentication gotcha (CLAUDE_CODE_OAUTH_TOKEN is not supported but is the default credential that Claude Code itself uses), which could cause initial 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 Copilot subscription

---

Question 1: Onboarding Experience

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

Yes, with minor friction. The Quick Start guide (docs/src/content/docs/setup/quick-start.mdx) is notably inclusive: the Prerequisites section explicitly lists "GitHub Copilot, Anthropic Claude, OpenAI Codex, or Google Gemini" as alternative AI accounts. Step 2 of the wizard explicitly says "Select an AI Engine - Choose between Copilot, Claude, Codex, or Gemini." This is well done.

However, there are some friction points:

Specific Issues Found:

• Issue 1 — docs/src/content/docs/introduction/overview.mdx: The introductory example workflow has no engine: field, which silently defaults to Copilot. A Claude user might copy this pattern and be confused when their workflow fails for lack of a COPILOT_GITHUB_TOKEN.

  # Current: no engine field = Copilot default
  on:
    issues:
      types: [opened]
  permissions: read-all

  Suggested fix: Add a comment # engine: defaults to copilot — set engine: claude to use Claude or show the field.

• Issue 2 — docs/src/content/docs/reference/engines.md (line 27): The "Which engine should I choose?" section opens with: "Copilot is the default choice for most users... If you are unsure, start with Copilot and switch later." For a developer without Copilot, this is misleading advice. There is no "start with Claude instead if you don't have Copilot" path.

Recommended Fixes:

• Add conditional framing to the engine recommendation: "If you have a Copilot subscription, start with Copilot (broadest feature set). If you are using Claude Code or have an Anthropic API key, start with Claude."
• Add a comment to the overview example noting that omitting engine: defaults to Copilot.

---

Question 2: Inaccessible Features for Non-Copilot Users

What features or steps don't work without Copilot?

Features That Require Copilot (Copilot-only):

• engine.agent — Custom Copilot agent files in .github/agents/ (documented in engines.md)
• engine.driver — Custom driver script replacement (documented in engines.md)
• max-continuations — Autopilot multi-run mode (documented in engines.md)
• Crush experimental engine — requires COPILOT_GITHUB_TOKEN (listed in engines table)
• OpenCode experimental engine — requires COPILOT_GITHUB_TOKEN (listed in engines table)
• Assign-to-Copilot safe output — separate assign-to-copilot.mdx doc page

Features That Work Without Copilot (Engine-Agnostic):

• All standard tools: edit:, bash:, github:, playwright:, web-fetch:, cache-memory:, repo-memory:, agentic-workflows:
• Safe outputs: add-comment, create-issue, create-pull-request, add-labels, etc.
• max-turns (Claude-specific turn limiting)
• MCP server integration (mcp-servers:)
• Network firewall, secret redaction, threat detection
• All CLI commands (gh aw compile, gh aw run, gh aw logs, etc.)
• api-target for custom endpoints
• All timeout configuration

Missing Documentation:

• No "Claude-first quickstart" path. The Quick Start guide uses add-wizard which interactively prompts for engine choice — this is fine. But there is no dedicated guide for "I have Claude Code and want to set up my first workflow."
• No explicit documentation of which .github/agents/ features are Copilot-only vs. what alternatives exist for Claude. The custom-agent-for-aw.mdx doc may address this but isn't in the core review path.

---

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 AWF network diagram labels the agent process as "Copilot CLI" and the agent container as "Copilot CLI + MCP client". A Claude user reading the firewall architecture docs would see Copilot CLI labeled explicitly where any AI engine would actually run. This is technically accurate for the example but misleading for non-Copilot users trying to understand how their engine integrates.

• File: docs/src/content/docs/introduction/architecture.mdx (lines 225-237) — The network configuration example hardcodes engine: copilot. While a single example is fine, a Claude user might wonder "does this firewall work differently for Claude?"

• File: docs/src/content/docs/reference/engines.md (line 27) — "If you are unsure, start with Copilot" recommendation without a conditional for non-Copilot users.

Missing Alternative Instructions:

• No Claude-specific "getting started" section beyond what's in Quick Start.
• No guide for what to do if you want max-continuations behavior with Claude (you can't — but what's the Claude equivalent pattern?).
• No explicit callout that web-search: with Claude requires MCP server setup (mentioned in a note but not in a highlighted "Claude users: do this" format).

---

Severity-Categorized Findings

🚫 Critical Blockers (Score: 0)

No critical blockers found. A Claude Code user can successfully install gh-aw, add a workflow, configure ANTHROPIC_API_KEY, and run it.

⚠️ Major Obstacles (Score: 2)

Obstacle 1: CLAUDE_CODE_OAUTH_TOKEN Not Supported — Needs More Prominence

Impact: First-time Claude users may authenticate incorrectly, causing confusing failures.

Current State: The auth.mdx file contains this note buried under the ANTHROPIC_API_KEY section:

"CLAUDE_CODE_OAUTH_TOKEN is not supported by GitHub Agentic Workflows. The only supported authentication method for the Claude engine is ANTHROPIC_API_KEY."

Why It's Problematic: Claude Code (the CLI tool this persona uses daily) authenticates via OAuth by default. Claude Code users are accustomed to running claude without an API key, relying on OAuth. When they try to replicate this for gh-aw, they may set CLAUDE_CODE_OAUTH_TOKEN or wonder why claude commands work locally but not in gh-aw. The note IS present, but it's easy to miss.

Suggested Fix: Add this as a callout in the Quick Start prerequisites or as a "⚠️ Claude Code users: note" callout box in the auth documentation. Something like:

⚠️ Claude Code Users: If you normally use Claude Code with OAuth (no API key), note that gh-aw requires ANTHROPIC_API_KEY from console.anthropic.com. OAuth authentication via CLAUDE_CODE_OAUTH_TOKEN is not supported.

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

Obstacle 2: "Start With Copilot" Recommendation Without Copilot Conditional

Impact: Sends non-Copilot users on a dead-end path or causes confusion about default setup.

Current State: docs/src/content/docs/reference/engines.md line 27:

"Copilot is the default choice for most users because it supports the broadest gh-aw feature set, including custom agents and autopilot-style continuations. Choose Claude when you want stronger control over turn limits... If you are unsure, start with Copilot and switch later by changing only engine: and the corresponding secret."

Why It's Problematic: The "if you are unsure" path assumes Copilot availability. For developers who explicitly chose Claude Code over Copilot, this guidance is unusable. There's no corresponding "if you already use Claude Code and don't have Copilot, start with Claude."

Suggested Fix: Add a parallel path:

"If you are unsure and have a Copilot subscription, start with Copilot. If you use Claude Code or have an Anthropic API key, start with Claude — the max-turns parameter gives you precise control over agent iteration."

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

💡 Minor Confusion Points (Score: 5)

• Point 1: Architecture diagram shows "Copilot CLI" in the AWF firewall network node diagram — should show "AI Engine (Copilot / Claude / Codex)" — File: docs/src/content/docs/introduction/architecture.mdx lines 181, 252
• Point 2: Overview example workflow has no engine: field, silently defaults to Copilot — File: docs/src/content/docs/introduction/overview.mdx
• Point 3: Network config example in architecture uses engine: copilot — this is an example, but there are no parallel Claude examples of the same config — File: docs/src/content/docs/introduction/architecture.mdx lines 225-237
• Point 4: tools.md notes web-search "requires third-party MCP servers" for some engines, but doesn't give a Claude-specific path to set it up — File: docs/src/content/docs/reference/tools.md line 65
• Point 5: engines.md feature table lists engine.agent as Copilot-only without explaining what the Claude Code equivalent pattern is for custom agent behavior — File: docs/src/content/docs/reference/engines.md

---

Engine Comparison Analysis

Available Engines

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

• engine: copilot — Default, broadest feature set, well-documented
• engine: claude — Well-documented, strong max-turns support, 57 example workflows
• engine: codex — Documented with full auth instructions, 12 example workflows
• engine: gemini — Documented, 1 example workflow
• engine: crush / engine: opencode — Experimental, both require COPILOT_GITHUB_TOKEN

Documentation Quality by Engine

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

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

---

Tool Availability Analysis

Engine-Agnostic Tools (work with all engines including Claude):

• edit:, bash:, github: (GitHub API operations)
• playwright: (browser automation)
• web-fetch: (fetch web content)
• cache-memory:, repo-memory: (persistence)
• agentic-workflows: (workflow introspection)
• All MCP server integrations (mcp-servers:)

Engine-Specific Tools:

• web-search: — Codex has native support; Claude/Copilot/Gemini require third-party MCP server
• engine.agent — Copilot-only (custom .github/agents/ files)
• engine.driver — Copilot-only (custom driver scripts)
• max-continuations — Copilot-only (autopilot multi-run)
• max-turns — Claude-only (iteration limit)

Unclear/Undocumented:

• The specific MCP server needed for web-search: with Claude is referenced but not named inline — users must follow the link to Using Web Search

---

Authentication Requirements

Current Documentation

Quick Start guide covers authentication for:

• ✅ Copilot — detailed instructions with pre-filled PAT creation link
• ✅ Claude — ANTHROPIC_API_KEY documented in auth.mdx with setup steps
• ✅ Codex — OPENAI_API_KEY / CODEX_API_KEY documented
• ✅ Gemini — GEMINI_API_KEY documented

Missing for Claude Users

The key gap is prominence of the OAuth limitation. The CLAUDE_CODE_OAUTH_TOKEN note is present but not highlighted as a prerequisite warning for Claude Code users who rely on OAuth daily.

Also notable: CLAUDE_CODE_OAUTH_TOKEN not being supported means that users who have a Claude Teams or Claude Max subscription (which bills through Anthropic's subscription model, not API credits) cannot use gh-aw without also maintaining API credits. This is a potential cost consideration that isn't documented.

Secret Names

• Copilot: COPILOT_GITHUB_TOKEN (fine-grained PAT, well-documented)
• Claude: ANTHROPIC_API_KEY (API key from console, documented)
• Codex: OPENAI_API_KEY or CODEX_API_KEY (documented)
• Gemini: GEMINI_API_KEY (documented)

---

Example Workflow Analysis

Workflow Count by Engine

Engine: copilot  — 108 workflows (53%)
Engine: claude   —  57 workflows (28%)
Engine: codex    —  12 workflows  (6%)
Engine: gemini   —   1 workflow   (<1%)
No engine / other —  26 workflows (13%)

Quality of Examples

Copilot Examples (108):
Full spectrum of use cases from CI analysis to code review. This is the dominant pattern in the repo.

Claude Examples (57):
Solid representation — 28% of all workflows. Covers monitoring, auditing, documentation, and AI pipeline workflows. The current workflow (claude-code-user-docs-review.md) itself uses engine: claude, demonstrating real production usage. The existence of 57 Claude workflows is a strong signal that Claude is a first-class citizen.

Codex Examples (12):
Enough to demonstrate patterns but lighter coverage.

Gemini Examples (1):
Minimal — only one workflow, suggesting Gemini is not well-exercised.

---

Recommended Actions

Priority 1: Critical Documentation Fixes

1. Promote the CLAUDE_CODE_OAUTH_TOKEN limitation — Add a callout box in auth.mdx under the ANTHROPIC_API_KEY section AND add a note in quick-start.mdx prerequisites: "Claude Code OAuth is not supported — you need an API key from console.anthropic.com"

   • File: docs/src/content/docs/reference/auth.mdx, docs/src/content/docs/setup/quick-start.mdx

2. Document Claude Teams/Max subscription limitation — Note that subscription-based billing isn't supported; users need API credits. This could be a surprise cost for existing Claude subscribers.

   • File: docs/src/content/docs/reference/auth.mdx

Priority 2: Major Improvements

1. Fix engine recommendation to include non-Copilot path — Change "If you are unsure, start with Copilot" to include "If you use Claude Code or have an Anthropic API key, start with Claude"

   • File: docs/src/content/docs/reference/engines.md line 27

2. Update AWF architecture diagrams — Replace "Copilot CLI" labels with "AI Engine (Copilot / Claude / Codex)" in the AWF network diagram and MCP gateway diagram

   • File: docs/src/content/docs/introduction/architecture.mdx lines 181, 252

3. Add engine: field to overview example — Either show engine: claude as an example or add a comment noting that omitting engine: defaults to Copilot

   • File: docs/src/content/docs/introduction/overview.mdx

Priority 3: Nice-to-Have Enhancements

1. Add a "Claude-first getting started" section — A short guide specifically for Claude Code users setting up their first workflow, separate from the Copilot path
2. Add inline Claude web-search MCP example — In tools.md, add a collapsed example showing the MCP server configuration needed for web search with Claude
3. Add more Gemini workflow examples — Currently only 1 example, making Gemini feel like an afterthought
4. Document Claude Teams/Max subscription workaround — Note that users can configure ANTHROPIC_BASE_URL to route to a proxy if needed

---

Positive Findings

What Works Well for Claude Code Users:

• ✅ Quick Start is engine-inclusive — explicitly lists all AI accounts including Claude in prerequisites
• ✅ Auth docs are complete — ANTHROPIC_API_KEY has full setup instructions with URL
• ✅ Engine feature comparison table is comprehensive — clearly shows what's supported per engine
• ✅ 57 Claude workflow examples (28%) — proves Claude is production-ready in gh-aw
• ✅ CLI explicitly shows Claude — gh aw new --engine claude is a documented first-class example
• ✅ gh aw secrets bootstrap --engine claude — correctly handles Claude-specific secrets
• ✅ CLAUDE_CODE_OAUTH_TOKEN documented as unsupported — prevents a common mistake (though needs more prominence)
• ✅ max-turns uniquely documented for Claude — actually gives Claude users a feature advantage
• ✅ add-wizard interactive setup — prompts for engine choice, works well for Claude path
• ✅ No Copilot license required for any core functionality

---

Conclusion

Can Claude Code Users Successfully Adopt gh-aw?

Answer: Yes — with minor friction.

The documentation is substantially inclusive of Claude as an AI engine. The Quick Start explicitly surfaces Claude as an option, the auth docs are complete, and 57 live workflows demonstrate production use of engine: claude. The biggest practical risk is the CLAUDE_CODE_OAUTH_TOKEN gotcha — Claude Code users work exclusively through OAuth by default, and learning that only ANTHROPIC_API_KEY works in gh-aw is a non-obvious authentication change that needs more prominence in the onboarding flow.

The second concern is cultural: the framing throughout uses Copilot as the default recommendation, which is understandable given it supports more features, but it can make Claude Code users feel like second-class citizens. This is primarily a messaging issue, not a capability gap.

Overall Assessment Score: 7/10

Breakdown:

• Clarity for non-Copilot users: 7/10
• Claude engine documentation: 8/10
• Alternative approaches provided: 7/10
• Engine parity (core functionality): 8/10
• Engine parity (advanced features): 5/10

Next Steps

1. Address the CLAUDE_CODE_OAUTH_TOKEN prominence issue in auth docs and quick start (Priority 1)
2. Add the Claude-alternative path to the engine recommendation section (Priority 2)
3. Update architecture diagrams to be engine-agnostic (Priority 2)
4. Consider a dedicated "Getting Started with Claude" guide for Claude Code users

---

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
• docs/src/content/docs/introduction/overview.mdx
• .github/workflows/*.md (204 workflows surveyed by engine type)

---

References:

• §24997222671

Workflow: claude-code-user-docs-review
Engine Used: claude (eating our own dog food 🐕)

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

• expires on Apr 28, 2026, 1:21 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 #28944.