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

[github-actions[bot]]

Executive Summary

As a developer using Claude Code as my primary AI assistant — with no GitHub Copilot subscription — I conducted a full review of the gh-aw documentation to determine whether I could successfully onboard and use GitHub Agentic Workflows. The good news: Claude users can absolutely use gh-aw. The prerequisites, engine selection, and authentication are all documented. However, the architecture documentation contains Copilot-specific labels that misrepresent the system as Copilot-only, and a few rough edges add friction for non-Copilot users.

Key Finding: Claude Code users can get started with gh-aw, but the architecture diagrams imply the system is Copilot-only, and the ANTHROPIC_API_KEY setup link points to documentation rather than the API key creation page.

---

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, but with some friction. The Quick Start guide (quick-start.mdx) explicitly lists Claude as one of four supported AI engines in the Prerequisites section. The add-wizard interactive command walks users through engine selection, covering Copilot, Claude, Codex, and Gemini equally. The engines reference (engines.md) includes a well-structured feature comparison table.

Specific Issues Found:

• Issue 1: architecture.mdx lines 181–189 — The Agent Workflow Firewall diagram labels the AI agent process as COPILOT["Copilot CLI"]. A new user reading this diagram would conclude the system requires Copilot:

  subgraph Agent["AI Agent Process"]
      COPILOT["Copilot CLI"]
      WEB["WebFetch Tool"]
      SEARCH["WebSearch Tool"]
  end
  

  The label should read ENGINE["AI Engine (Copilot/Claude/Codex/Gemini)"] or similar.

• Issue 2: architecture.mdx lines 244–259 — The MCP Gateway diagram hardcodes the agent container as "Agent container\nCopilot CLI + MCP client\n172.30.0.20". This reinforces the false impression that the architecture is Copilot-specific.

• Issue 3: architecture.mdx lines 226–237 — The firewall configuration code example uses engine: copilot without a note that this works with any engine. New users copy examples verbatim.

Recommended Fixes:

• In all architecture diagrams, replace Copilot CLI labels with AI Engine or Coding Agent (Copilot / Claude / Codex / Gemini).
• Add a note below the firewall configuration example: # Replace 'copilot' with 'claude', 'codex', or 'gemini' for other engines.

---

Question 2: Inaccessible Features for Non-Copilot Users

What features or steps don't work without Copilot?

Features that require Copilot specifically:

• engine.agent — Custom agent files (.github/agents/*.agent.md) — documented as Copilot-only in the engine feature table, but copilot-custom-agents.md is an entire reference page with no "this is Copilot-only" callout at the top.
• engine.driver — Custom driver script replacement — Copilot-only, documented in engines.md with a callout.
• max-continuations — Autopilot mode with multiple consecutive runs — Copilot-only, documented in the feature table.
• assign-to-agent safe output — Currently only supports copilot as the agent name. A Claude Code user might reasonably expect to be able to assign Claude to issues. The supported agents note (Supported agents: copilot) is buried and easy to miss.
• crush and opencode experimental engines — Both require COPILOT_GITHUB_TOKEN, which is counterintuitive for users who don't have Copilot.

Features that work without Copilot:

• All core agentic execution (engine: claude with ANTHROPIC_API_KEY)
• All safe outputs (create issue, add comment, create PR, etc.)
• All tools (bash, edit, web-fetch, playwright, cache-memory, etc.)
• MCP server integrations
• All CLI commands (gh aw compile, gh aw run, gh aw logs, etc.)
• max-turns (Claude-only, but well-documented)

Missing Documentation:

• No "Getting Started with Claude" guide or dedicated quickstart path for Claude users.
• The assign-to-agent safe output page (assign-to-copilot.mdx) does not prominently state it's Copilot-only. The page title is "Assign to Copilot" which helps, but the referenced workflow feature is assign-to-agent — which sounds engine-agnostic.

---

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 — Three diagrams use "Copilot CLI" as the agent label, not "AI Engine". This is the most prominent example of Copilot-centric architecture documentation.
• File: docs/src/content/docs/reference/engines.md (line ~27) — "Which engine should I choose?" section: "Copilot is the default choice for most users because it supports the broadest gh-aw feature set, including custom agents and autopilot-style continuations." A Claude user who actively chose not to use Copilot might feel they're using a second-class option. The section doesn't articulate when Claude is the right choice beyond "stronger control over turn limits."
• File: docs/src/content/docs/reference/auth.mdx (line 109) — The ANTHROPIC_API_KEY setup instruction points to (platform.claude.com/redacted) — a documentation page — rather than the API key creation page at https://console.anthropic.com/`. The troubleshooting section on line 199 correctly references console.anthropic.com, creating an inconsistency.

Missing Alternative Instructions:

• No guide for "Using gh-aw with Claude Code" that mirrors the overall getting-started experience.
• No mention in the README of how to use alternative engines beyond the Copilot default.

---

Severity-Categorized Findings

🚫 Critical Blockers (Score: 0/10 — none found)

No true critical blockers exist. A Claude user can get started by following the Quick Start guide, selecting Claude in add-wizard, and supplying ANTHROPIC_API_KEY.

⚠️ Major Obstacles (Score: 6/10)

Obstacle 1: Architecture diagrams label AI agent as "Copilot CLI" throughout

Impact: Creates false impression that gh-aw requires Copilot at the architecture level.

Current State: Three mermaid diagrams in architecture.mdx use "Copilot CLI" as a label for what is actually an engine-agnostic AI agent container. Lines 181–223 (AWF diagram), 244–268 (MCP Gateway diagram), and the Agent Execution diagram at line 279.

Why It's Problematic: A developer evaluating gh-aw reads the architecture page to understand how the system works. Seeing "Copilot CLI" in the architecture diagrams leads them to conclude Copilot is required — even if the quickstart says otherwise.

Suggested Fix: Replace COPILOT["Copilot CLI"] with ENGINE["AI Engine"] and add a caption note: "Engine shown as Copilot; Claude Code, Codex, and Gemini are also supported."

Affected Files: docs/src/content/docs/introduction/architecture.mdx

Obstacle 2: ANTHROPIC_API_KEY setup URL points to documentation, not API key creation

Impact: Claude users following setup instructions will land on a "getting started" documentation page, not the API key creation interface, causing confusion.

Current State: auth.mdx line 109:

1. Create an API key at (platform.claude.com/redacted)

This is a docs overview page. The actual API key creation is at https://console.anthropic.com/.

Why It's Problematic: The Copilot token setup on line 82 provides a pre-filled URL with the exact token creation page. By contrast, Claude users are sent to documentation. The troubleshooting section on line 199 correctly references console.anthropic.com — an inconsistency within the same page.

Suggested Fix: Change to:

1. Create an API key at https://console.anthropic.com/ (Settings → API Keys)

Affected Files: docs/src/content/docs/reference/auth.mdx, line 109

Obstacle 3: "Which engine should I choose?" section doesn't make a positive case for Claude

Impact: Claude users feel they're using an inferior option.

Current State: engines.md states: "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 (max-turns) for long reasoning sessions."

Why It's Problematic: Recommending Copilot to "most users" without acknowledging that many developers don't have or want Copilot is unhelpful. The Claude use case ("want stronger control over turn limits") is weak — it implies Claude is only worth choosing for edge cases.

Suggested Fix: Add a line like: "Choose Claude if you already have an Anthropic API key, prefer direct API billing without a Copilot subscription, or want fine-grained turn control for complex reasoning tasks. Claude has 47+ example workflows in this repository."

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

💡 Minor Confusion Points (Score: 7/10)

• Issue 1: crush and opencode experimental engines require COPILOT_GITHUB_TOKEN per the engines table, but this is non-obvious — users might assume they need their own AI provider key. File: docs/src/content/docs/reference/engines.md
• Issue 2: assign-to-copilot.mdx page title says "Assign to Copilot" but the workflow field is assign-to-agent — mixing terminology. Non-Copilot users might think they can configure this for Claude. File: docs/src/content/docs/reference/assign-to-copilot.mdx
• Issue 3: copilot-custom-agents.md reference page has no top-of-page callout stating "This feature is Copilot-only." Claude users who click through to this page after seeing engine.agent in the feature matrix will need to read carefully to understand this. File: docs/src/content/docs/reference/copilot-custom-agents.md
• Issue 4: Feature parity gap (max-continuations Copilot-only vs. no equivalent for Claude) is documented in the table but no explanation of what this means practically — Claude users cannot do multi-run autopilot loops. File: docs/src/content/docs/reference/engines.md
• Issue 5: The Quick Start video (install-and-add-workflow-in-cli.mp4) likely shows Copilot CLI setup, but there's no caption noting this. Users who watch the video then select Claude will be confused if the prompts differ. File: docs/src/content/docs/setup/quick-start.mdx

---

Engine Comparison Analysis

Available Engines

Based on my review:

Engine	Setup Docs	Examples	Auth Docs	Overall Score
Copilot	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐ (89 workflows)	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐
Claude	⭐⭐⭐⭐	⭐⭐⭐⭐ (47 workflows)	⭐⭐⭐ (wrong URL)	⭐⭐⭐⭐
Codex	⭐⭐⭐	⭐⭐ (10 workflows)	⭐⭐⭐⭐	⭐⭐⭐
Gemini	⭐⭐⭐	⭐ (0 workflows)	⭐⭐⭐⭐	⭐⭐

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

Notes:

• Claude has 47 real-world workflow examples in .github/workflows/, which is excellent for learning by example.
• Copilot's 89 examples include Copilot-specific features (custom agents, autopilot) that aren't available for other engines.
• Gemini has zero workflow examples in this repository, making it hard to validate practical use.
• Codex examples are limited but sufficient for basic use cases.

---

Tool Availability Analysis

Based on tools.md review:

Engine-Agnostic Tools (work with any engine):

• edit: — File editing
• bash: — Shell command execution
• web-fetch: — Web content fetching
• playwright: — Browser automation
• cache-memory: — Persistent memory
• repo-memory: — Repository memory
• github: — GitHub API operations
• agentic-workflows: — Workflow introspection
• qmd: — Documentation search (experimental)

Engine-Specific Behaviors:

• web-search: — Codex natively supports this; other engines (including Claude) need a third-party MCP server. The note says "engine-dependent" but doesn't list which engines need MCP setup — requires reading the web search guide.
• tools.timeout defaults differ: Claude defaults to 60s, Codex to 120s, others engine-managed.

Unclear/Undocumented:

• Whether all MCP server types (command, container, HTTP) work equally across all engines is not explicitly stated.

---

Authentication Requirements

Current Documentation Coverage

Engine	Secret	Setup URL Quality	Status
Copilot	COPILOT_GITHUB_TOKEN	⭐⭐⭐⭐⭐ (pre-filled link)	✅ Complete
Claude	ANTHROPIC_API_KEY	⭐⭐ (docs URL not key URL)	⚠️ URL issue
Codex	OPENAI_API_KEY	⭐⭐⭐⭐ (correct platform URL)	✅ Complete
Gemini	GEMINI_API_KEY	⭐⭐⭐⭐ (correct AI Studio URL)	✅ Complete

Missing / Unclear for Claude Users

• The CLAUDE_CODE_OAUTH_TOKEN exclusion is correctly documented — good proactive note.
• The path to console.anthropic.com for API key creation needs fixing (wrong URL in setup steps).
• No note about API key pricing tiers or usage-based billing for Claude (Copilot has a note about license requirements).

---

Example Workflow Analysis

Workflow Count by Engine

Engine: copilot - 89 workflows found
Engine: claude  - 47 workflows found
Engine: codex   - 10 workflows found
Engine: gemini  -  0 workflows found

Quality of Examples

Copilot Examples: Comprehensive, covering a full range from simple status reports to complex multi-step automations. Include Copilot-specific features.

Claude Examples: Excellent breadth — 47 workflows covering auditing, reporting, testing, and research. Many use advanced features like max-turns, playwright, and agentic-workflows tool. These serve as strong role models for Claude users.

Codex Examples: Limited (10 workflows), but demonstrate basic use cases adequately.

Gemini Examples: None found. This is a significant gap for Gemini users, but outside Claude user scope.

---

Recommended Actions

Priority 1: Critical Documentation Fixes

1. Fix ANTHROPIC_API_KEY setup URL — Change (platform.claude.com/redacted) to https://console.anthropic.com/` (Settings → API Keys). File: docs/src/content/docs/reference/auth.mdx, line 109.
2. Replace "Copilot CLI" labels in architecture diagrams — Three mermaid diagrams in architecture.mdx (lines 182, 247, 279) should use engine-agnostic labels like "AI Engine" or "Coding Agent". File: docs/src/content/docs/introduction/architecture.mdx.

Priority 2: Major Improvements

1. Add positive Claude use case to "Which engine should I choose?" — Frame Claude as the right choice for users with Anthropic accounts, those who prefer direct API billing, or those wanting fine-grained turn control. File: docs/src/content/docs/reference/engines.md.
2. Add Copilot-only callout to copilot-custom-agents.md — Add an [!NOTE] admonition at the top: "Custom agent files are a Copilot-specific feature. Claude, Codex, and Gemini users can achieve similar results by including instructions directly in workflow markdown." File: docs/src/content/docs/reference/copilot-custom-agents.md.
3. Replace engine: copilot in architecture configuration examples with engine: <your-engine> or show a multi-engine example. File: docs/src/content/docs/introduction/architecture.mdx, line 228.

Priority 3: Nice-to-Have Enhancements

1. Add a "Using Claude with gh-aw" guide — A short dedicated page or section showing a minimal Claude workflow end-to-end would build confidence for Claude users.
2. Note video content — Add a caption to the Quick Start video indicating which engine is demonstrated, so users selecting a different engine know what to expect.
3. Add at least 2–3 Gemini examples — Currently zero, which makes Gemini hard to evaluate practically.

---

Positive Findings

What Works Well

• ✅ Prerequisites clearly list all engines — quick-start.mdx mentions Copilot, Claude, Codex, and Gemini as valid AI account types.
• ✅ add-wizard handles multi-engine setup — Interactive flow covers all engines equally.
• ✅ 47 Claude workflow examples — Far more than needed to understand practical use; excellent real-world templates.
• ✅ CLAUDE_CODE_OAUTH_TOKEN exclusion note — Proactively warns Claude users about the unsupported auth method. Prevents a common pitfall.
• ✅ Engine feature comparison table — Clear side-by-side view of what's supported per engine.
• ✅ max-turns Claude-specific feature — Well documented with examples.
• ✅ --engine claude CLI flag — Available on add, compile, validate, new, and other commands.
• ✅ Auth troubleshooting — All four engine auth errors are documented.

---

Conclusion

Can Claude Code Users Successfully Adopt gh-aw?

Answer: Yes, with minor friction.

Reasoning: The core onboarding path (Quick Start → add-wizard → ANTHROPIC_API_KEY) is well documented and engine-agnostic. The 47 Claude workflow examples in this repository demonstrate that Claude is a first-class engine in practice. The main friction points are cosmetic (Copilot-labeled architecture diagrams) and a broken setup URL for ANTHROPIC_API_KEY. Neither prevents adoption, but the architecture diagrams in particular could mislead evaluating developers into thinking Copilot is required.

A Claude user who reads the Quick Start and engines reference will succeed. A Claude user who reads the architecture page first might give up prematurely.

Overall Assessment Score: 7/10

Breakdown:

• Clarity for non-Copilot users: 7/10 (good prerequisites, weak architecture diagrams)
• Claude engine documentation: 7/10 (comprehensive engines.md, wrong auth URL)
• Alternative approaches provided: 8/10 (feature table, --engine flags, auth docs)
• Engine parity (in docs): 7/10 (honest about feature gaps, Copilot-first framing)

Next Steps

1. Fix the ANTHROPIC_API_KEY URL (5-minute fix, high impact).
2. Update architecture diagram labels to be engine-agnostic (moderate effort, high visibility impact).
3. Strengthen the Claude use-case framing in the engine selection 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
• docs/src/content/docs/reference/faq.md
• docs/src/content/docs/reference/github-tools.md
• docs/src/content/docs/reference/assign-to-copilot.mdx
• docs/src/content/docs/reference/copilot-custom-agents.md
• Sample workflows: 47 Claude, 89 Copilot, 10 Codex (engine counts from .github/workflows/*.md)

---

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

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

• expires on Apr 24, 2026, 1:20 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 #28270.