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

[github-actions[bot]]

Executive Summary

As a developer who actively uses Claude Code and avoids GitHub Copilot, I reviewed the gh-aw documentation to assess whether it enables a clear, unblocked adoption path. The overall picture is positive: the core prerequisites, quick-start wizard, authentication guide, and engines reference all explicitly cover Claude. However, three areas of major friction remain — primarily around the gh aw init authoring experience, Copilot-centric naming in the architecture diagram, and the GitHub Web Interface authoring path that is gated behind Copilot access.

Key Finding: Claude Code users can successfully adopt gh-aw, but the authoring/creation experience described prominently in docs is largely Copilot-centric. Getting started with the add-wizard + manual CLI path works well; the "rich authoring" experience advertised in creating-workflows.mdx is partially inaccessible.

---

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, with minor friction. The Quick Start (docs/src/content/docs/setup/quick-start.mdx) does a good job listing Claude as a first-class option in its prerequisites:

"AI Account - GitHub Copilot, Anthropic Claude or [OpenAI Codex]((openai.com/redacted)

The add-wizard flow interactively prompts for engine selection and secret configuration. A Claude user can follow this flow end-to-end without Copilot.

Specific Issues Found:

• Issue 1 (docs/src/content/docs/setup/creating-workflows.mdx, "GitHub Web Interface" section): The section opens with "If you have access to GitHub Copilot, you can create and edit Agentic Workflows directly from the Web Interface." A Claude user immediately reads this as "this path is not for me." No alternative web-based authoring path is offered for non-Copilot users.

• Issue 2 (docs/src/content/docs/setup/creating-workflows.mdx, "Initialize the Repository" section): gh aw init is described primarily as enabling /agent agentic-workflows in Copilot Chat on github.com and the GitHub mobile app. The value of gh aw init for non-Copilot users (gitattributes setup, MCP server integration, VS Code settings) is not called out separately.

• Issue 3 (docs/src/content/docs/setup/quick-start.mdx, Step 2): The COPILOT_GITHUB_TOKEN secret is listed first in the description of what add-wizard configures, before ANTHROPIC_API_KEY. Minor ordering issue — new users may anchor on Copilot.

Recommended Fixes:

• In creating-workflows.mdx, add a note under the "GitHub Web Interface" section: "If you're using Claude or Codex, use the terminal-based workflow below — the web authoring experience currently requires GitHub Copilot."
• In the "Initialize the Repository" section of creating-workflows.mdx, split the gh aw init description into (a) what it does for everyone and (b) what requires Copilot.

---

Question 2: Inaccessible Features for Non-Copilot Users

What features or steps don't work without Copilot?

Features That Require Copilot:

• GitHub Web Interface authoring — Creating/editing workflows via github.com or the GitHub mobile app using /agent agentic-workflows requires a Copilot subscription. This is called out in docs, but is the most prominent authoring path described.
• engine.agent custom agent files — The agent: field in extended engine config references .github/agents/*.agent.md files and is Copilot-only (confirmed in the engine feature comparison table in docs/src/content/docs/reference/engines.md).
• max-continuations autopilot mode — Copilot-only feature for multiple consecutive runs.
• assign-to-copilot safe output — Assigns the GitHub Copilot coding agent to issues/PRs. Expected to be Copilot-only; well-documented.
• reviewers: [copilot] — Assigning the Copilot PR reviewer bot is Copilot-only.

Features That Work Without Copilot:

All core gh-aw functionality is engine-agnostic: compilation (gh aw compile), execution (gh aw run), monitoring (gh aw logs, gh aw audit, gh aw status), safe outputs (create-issue, add-comment, create-pull-request), MCP servers, tools (edit, bash, web-fetch, github, playwright, cache-memory), network firewall, threat detection, and integrity filtering.

Missing Documentation:

• There's no explicit callout in the "Initialize the Repository" section about which benefits of gh aw init apply to all users vs. Copilot users. Claude Code users may skip gh aw init entirely thinking it's a Copilot setup step.

---

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 — The Agent Workflow Firewall mermaid diagram (lines 181, 209, 252) uses COPILOT["Copilot CLI"] as the process name and labels the agent container as "Agent container\nCopilot CLI + MCP client\n172.30.0.20". This implies the firewall only wraps Copilot, when it actually wraps any engine.
• File: docs/src/content/docs/introduction/architecture.mdx — The network firewall configuration example uses engine: copilot as the sample config (line 228). No Claude or Codex equivalent example is shown alongside it.
• File: docs/src/content/docs/setup/creating-workflows.mdx — The GitHub Web Interface authoring path is gated: "If you have access to GitHub Copilot, you can create and edit Agentic Workflows directly from the Web Interface."
• File: docs/src/content/docs/setup/creating-workflows.mdx — gh aw init is pitched mainly as enabling the Copilot-based authoring experience.

Missing Alternative Instructions:

• No walkthrough for "create your first workflow using Claude Code" equivalent to the GitHub Web Interface path.
• The ANTHROPIC_API_KEY setup step in auth.mdx links to (platform.claude.com/redacted) instead of directly to https://console.anthropic.com/` — the former is docs, the latter is where users actually create API keys.

---

Severity-Categorized Findings

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

No critical blockers exist. A Claude Code user can complete the full quick-start workflow without Copilot.

⚠️ Major Obstacles (Score: 5/10)

Obstacle 1: GitHub Web Interface authoring is Copilot-only with no alternative shown

Impact: A significant, prominently-advertised feature (workflow creation via github.com) is inaccessible.

Current State: creating-workflows.mdx opens its first major section with: "If you have access to GitHub Copilot, you can create and edit Agentic Workflows directly from the Web Interface." The rest of the section demonstrates Copilot-based creation only.

Why It's Problematic: This is the first workflow creation path shown. Claude users hit a wall immediately and must scroll down to find the terminal-based alternative. There's no explicit statement that says "Claude/Codex users: skip to the terminal section."

Suggested Fix: Add a callout box at the top of the "GitHub Web Interface" section: > [!NOTE] > Web interface authoring requires GitHub Copilot. Claude and Codex users should use the terminal-based creation path below.

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

Obstacle 2: gh aw init described primarily as a Copilot authoring setup step

Impact: Claude users may skip gh aw init thinking it's irrelevant to them, missing useful repository setup (gitattributes, MCP server integration, VS Code settings).

Current State: The "Initialize the Repository" section says: "Running gh aw init is required to enable the authoring experience in the GitHub code agent. This step configures your repository so that you can create and modify agentic workflows directly from github.com or the GitHub mobile app, using the Copilot coding agent."

Why It's Problematic: "Required" + "Copilot coding agent" sends a clear signal to Claude users that this step doesn't apply to them. But gh aw init still provides value: .gitattributes configuration, VS Code settings, and MCP server integration for local Claude Code editing.

Suggested Fix: Split gh aw init description into two parts: (1) "What this does for all users" (gitattributes, MCP integration, VS Code) and (2) "Copilot-specific: enables /agent agentic-workflows in Copilot Chat."

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

Obstacle 3: AWF Architecture diagram labels agent container as "Copilot CLI"

Impact: The core security architecture appears to be Copilot-specific, which may confuse Claude users about whether the documented security model applies to them.

Current State: In architecture.mdx, the Agent Workflow Firewall mermaid diagram includes:

• COPILOT["Copilot CLI"] as the agent process
• AGENT["Agent container\nCopilot CLI + MCP client\n172.30.0.20"] as the container label

The firewall configuration example also uses engine: copilot.

Why It's Problematic: The AWF is engine-agnostic (it wraps Claude Code, Codex, and Gemini too), but the diagram implies it only wraps Copilot. A Claude user reading this page might think the security architecture doesn't apply to their setup.

Suggested Fix: Update the mermaid diagram to use generic labels: AGENT_PROC["AI Agent (Copilot / Claude / Codex)"] and AGENT["Agent container\nAI agent + MCP client"]. Add a second configuration example showing a Claude workflow.

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

💡 Minor Confusion Points (Score: 7/10)

• ANTHROPIC_API_KEY setup URL (auth.mdx): Links to (platform.claude.com/redacted) (a docs page) instead of https://console.anthropic.com/` (the actual API key creation page). Minor UX friction.
• Default engine is Copilot, 26 workflows have no engine: field (engines.md): Users need to know that engine: claude must be explicitly added. The docs say this but it's only in the engines reference, not in the quick start.
• CLAUDE_CODE_OAUTH_TOKEN note (auth.mdx): The helpful note that OAuth token auth is not supported is well-placed, but could be more prominent as a tip/warning callout since many Claude users may try this first.
• web-search tool requires MCP for Claude (tools.md): Only mentioned in a note under Web Tools. A more explicit callout for Claude users ("to use web-search with Claude, you need to configure an MCP server") would help.
• The engine: copilot is the default is mentioned in engines.md but not emphasized in quick start. A first-time Claude user might not know to add engine: claude to their workflow file.

---

Engine Comparison Analysis

Available Engines (as documented in engines.md)

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

Notes:

• Claude documentation is genuinely solid; the gap vs. Copilot is mainly in the authoring experience and example quantity (45 Claude vs. ~116 Copilot/default).
• Codex docs are adequate but have fewer examples (8 workflows) and less callout of the web-search opt-in requirement.
• Gemini is the newest and least documented; authentication and setup are covered but examples are sparse.

---

Tool Availability Analysis

Engine-Agnostic Tools (all engines)

edit, bash, web-fetch, github (toolsets, modes, auth), playwright, cache-memory, repo-memory, qmd, agentic-workflows, MCP custom servers, safe outputs (create-issue, add-comment, create-pull-request, add-labels)

Engine-Specific Tools

• engine.agent (custom agent file) — Copilot only
• max-continuations — Copilot only
• max-turns — Claude only
• web-search (native, no MCP) — Codex only (opt-in)
• web-search via MCP — Required for Copilot, Claude, Gemini

Unclear/Undocumented

• MCP servers are documented as engine-agnostic, but there's no explicit note confirming all engines support all MCP configurations equally. The architecture diagram implies MCP Gateway testing was done primarily with Copilot.

---

Authentication Requirements

Current Documentation

Engine	Secret	Auth Docs Quality
Copilot	COPILOT_GITHUB_TOKEN	✅ Detailed, with fine-grained PAT setup link
Claude	ANTHROPIC_API_KEY	✅ Covered, with CLI setup command
Codex	OPENAI_API_KEY or CODEX_API_KEY	✅ Covered, with Azure alternative
Gemini	GEMINI_API_KEY	✅ Covered

Missing for Claude Users

• Direct link to https://console.anthropic.com/ for API key creation (current link goes to docs page)
• No mention of Claude API pricing tiers or whether a free tier is available (Copilot section notes subscription requirement)
• CLAUDE_CODE_OAUTH_TOKEN is called out as unsupported — good! But buried in prose rather than a warning callout.

---

Example Workflow Analysis

Workflow Count by Engine

Engine: copilot  — 90 workflows
Engine: (none, default copilot) — 26 workflows  
Engine: claude   — 45 workflows
Engine: codex    — 8 workflows
Engine: gemini   — ~0 (none found)
Total:  187 workflows

Quality of Examples

Claude Examples: 45 workflows covering daily reports, CI doctors, blog auditors, approach validators, and more. Good variety. Claude workflows tend to use max-turns and are generally production-quality. Examples: audit-workflows.md, ci-doctor.md, approach-validator.md.

Copilot Examples: 90 workflows, the largest set, including many complex patterns. The sheer volume reinforces Copilot as the "primary" engine in practice, even if docs aim for parity.

Codex Examples: 8 workflows — thin coverage. A user wanting to use Codex has very few reference workflows to draw from.

---

Recommended Actions

Priority 1: Critical Documentation Fixes

1. Fix AWF diagram labels in architecture.mdx — Replace "Copilot CLI" with "AI Agent" in the mermaid diagrams. The diagram is the highest-visibility documentation artifact for the security model. Add a Claude example config alongside the Copilot one. File: docs/src/content/docs/introduction/architecture.mdx

2. Add Copilot-gating notice in creating-workflows.mdx web interface section — Add a [!NOTE] callout that web interface authoring requires Copilot, and direct Claude/Codex users to the terminal path explicitly. File: docs/src/content/docs/setup/creating-workflows.mdx

3. Split gh aw init description — Separate "benefits for all users" from "Copilot-specific benefits." Remove the implication that gh aw init is only relevant for Copilot users. File: docs/src/content/docs/setup/creating-workflows.mdx

Priority 2: Major Improvements

1. Fix ANTHROPIC_API_KEY setup link — Change (platform.claude.com/redacted) to https://console.anthropic.com/` in auth.mdx. The goal is to land users on the API key creation page, not the docs. File: docs/src/content/docs/reference/auth.mdx

2. Add explicit engine: claude tip to quick start — In Step 2 of quick-start.mdx, note that if you select Claude, the wizard will inject engine: claude into your workflow frontmatter, and that new workflows default to Copilot. File: docs/src/content/docs/setup/quick-start.mdx

3. Upgrade CLAUDE_CODE_OAUTH_TOKEN note to a warning callout — In auth.mdx, the note that OAuth tokens aren't supported for Claude is helpful but easily missed. Promote it to a [!WARNING] admonition. File: docs/src/content/docs/reference/auth.mdx

Priority 3: Nice-to-Have Enhancements

1. Add a "web-search with Claude" callout in tools.md — Explicitly note that Claude users need a third-party MCP server for web search, with a link to the Using Web Search guide.
2. Add more Codex and Gemini example workflows — Both engines have minimal example coverage compared to Claude and Copilot.
3. Add a "Why Claude over Copilot?" comparison section to engines.md — Briefly explain the trade-offs (e.g., Claude's max-turns support, different cost structures, no Copilot subscription required).

---

Positive Findings

What Works Well for Claude Code Users

• ✅ Quick start prerequisites list all three AI options — Immediately signals Claude is a first-class citizen.
• ✅ add-wizard interactively selects engine — Claude users are prompted and guided through ANTHROPIC_API_KEY setup.
• ✅ Authentication docs are engine-balanced — auth.mdx gives Claude, Codex, and Gemini equal treatment to Copilot with full setup instructions.
• ✅ engines.md feature comparison table — max-turns (Claude-only), max-continuations (Copilot-only), etc. are clearly tabulated.
• ✅ 45 Claude engine workflow examples — Strong real-world reference coverage.
• ✅ gh aw new --engine claude flag — Directly scaffolds Claude workflows with the right frontmatter.
• ✅ gh aw secrets bootstrap --engine claude — Engine-specific secret setup automation.
• ✅ CLAUDE_CODE_OAUTH_TOKEN unsupported note — Saves Claude users a debugging session.

---

Conclusion

Can Claude Code Users Successfully Adopt gh-aw?

Answer: Yes, with minor effort.

Reasoning: The core workflow (install extension → add-wizard → configure ANTHROPIC_API_KEY → run workflow) works without Copilot and is well-documented. Authentication, engine configuration, tools, and monitoring are all covered for Claude users. The main friction points are (1) the GitHub Web Interface authoring path is Copilot-only and prominently featured, (2) gh aw init appears Copilot-specific, and (3) architecture diagrams use "Copilot CLI" branding for engine-agnostic components.

None of these are blockers — they're friction points that slow down adoption and may cause confusion but don't prevent success. The three Priority 1 fixes above would close the gap significantly.

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 in examples: 7/10

Next Steps

1. Address the three Priority 1 documentation fixes (AWF diagram, web interface gating notice, gh aw init split).
2. Track this score over time with subsequent daily reviews to measure improvement.
3. Consider adding a "Getting Started with Claude" dedicated guide to match the implicit "Getting Started with Copilot" path that the current docs support.

---

Appendix: Files Reviewed

Complete List of Documentation Files Analyzed

• README.md
• 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/reference/frontmatter.md (partial)
• .github/workflows/*.md (187 workflows sampled for engine distribution)

---

References:

• §24244683290

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

• expires on Apr 11, 2026, 1:19 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 #25812.