🔍 Claude Code User Documentation Review - 2026-02-20

[github-actions[bot]]

Executive Summary

After systematically reading all core gh-aw documentation as a developer who uses Claude Code exclusively and has no Copilot subscription, I found that gh-aw is genuinely usable without GitHub Copilot. The Quick Start, engine selection wizard, and authentication docs all explicitly cover Claude. However, several secondary docs show Copilot bias through hardcoded labels, broken cross-references, and unfulfilled documentation promises that would cause a Claude Code user friction.

Key Finding: Claude Code users CAN successfully adopt gh-aw, but they will encounter 4 specific friction points that require investigation to work around. The core onboarding path is solid; the issues are in supporting documentation.

---

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, the core onboarding path works. The Quick Start (docs/src/content/docs/setup/quick-start.mdx) explicitly lists all three AI accounts as prerequisites:

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

The gh aw add-wizard command interactively guides users through engine selection:

"Select an AI Engine - Choose between Copilot, Claude, or Codex."
"Set up the required secret - COPILOT_GITHUB_TOKEN, ANTHROPIC_API_KEY or OPENAI_API_KEY."

This is a solid, engine-neutral entry point. A Claude Code user can complete the Quick Start without Copilot.

Specific Issues Found:

• Issue 1: docs/src/content/docs/setup/cli.md line 120 — gh aw init is described as "Configures .gitattributes, Copilot instructions, prompt files, and logs .gitignore." A Claude Code user seeing "Copilot instructions" may skip gh aw init thinking it's Copilot-specific, missing out on useful repository configuration.

• Issue 2: docs/src/content/docs/setup/creating-workflows.mdx line 70 — "If you haven't done so already, set up your repository secrets for your chosen engine (Copilot, Claude, or Codex). If not using Copilot, also adjust the engine: field in your workflow's frontmatter." This phrasing implies Copilot is the natural default and non-Copilot users take a deviation. While technically accurate, it subtly reinforces Copilot as the expected choice.

Recommended Fixes:

• In cli.md, rename "Copilot instructions" to "AI agent instructions" or "coding agent configuration files" in the gh aw init description, since init configures .agent.md files that work with all agents.
• In creating-workflows.mdx, reframe the engine instructions as: "Set up secrets for your chosen engine and set the engine: field in your workflow's frontmatter (claude, codex, or copilot)."

---

Question 2: Inaccessible Features for Non-Copilot Users

What features or steps don't work without Copilot?

Features That Require Copilot:

1. GitHub Web Interface workflow creation (creating-workflows.mdx line 20) — "If you have access to GitHub Copilot, you can create and edit Agentic Workflows directly from the Web Interface." This is correctly gated with an explicit Copilot requirement; non-Copilot users are directed to the VSCode/CLI section immediately below.

2. Copilot Custom Agent Files (custom-agent-for-aw.mdx) — The /agent agentic-workflows command and .github/agents/agentic-workflows.agent.md workflow are Copilot-specific. The page title says "Copilot Agent Files" but does not clearly warn Claude Code users at the top of the page that this feature requires Copilot.

3. COPILOT_GITHUB_TOKEN-specific features — Assigning Copilot coding agent to issues (GH_AW_AGENT_TOKEN with assign-to-agent safe output) is Copilot-ecosystem-only. This is documented appropriately.

Features That Work Without Copilot:

• All tools (edit:, bash:, github:, playwright:, web-fetch:, cache-memory:, repo-memory:, agentic-workflows:, custom MCP servers) — engine-agnostic
• Safe outputs — engine-agnostic
• gh aw compile, gh aw run, gh aw status, gh aw logs, gh aw add, gh aw trial — engine-agnostic
• Network firewall configuration — engine-agnostic
• Threat detection — engine-agnostic

Missing Documentation:

• custom-agent-for-aw.mdx should have a prominent note at the top: "This feature requires GitHub Copilot access. Claude and Codex users can use the alternative approach described in Creating Workflows."

---

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 AWF firewall Mermaid diagram (lines 177, 205-207, 248) labels the AI agent as COPILOT["Copilot CLI"] and the container as "Agent container\nCopilot CLI + MCP client\n172.30.0.20". Claude and Codex users would see a diagram that appears to show Copilot CLI as the mandatory runtime component inside the firewall, creating confusion about whether their chosen engine operates differently.

• File: docs/src/content/docs/setup/cli.md line 120 — gh aw init description says "Configures .gitattributes, Copilot instructions, prompt files, and logs .gitignore."

• File: docs/src/content/docs/reference/auth.mdx lines 113, 131 — Contains broken cross-references that are syntactically invalid as Markdown links. The text reads: See also (/gh-aw/reference/engines/#using-claude-by-anthropic-claude-code) for additional configuration needed when using Claude with GitHub MCP. — this is a bare URL in parentheses, not a proper [text](url) link and would render as literal text, not a hyperlink.

• File: docs/src/content/docs/reference/engines.md — The "Using Claude by Anthropic (Claude Code)" section (lines 44-58) contains only 3 steps. The auth.mdx promises "additional configuration needed when using Claude with GitHub MCP" but the engines.md section has no such content. This is a broken documentation promise that could leave Claude users confused when they try to use the GitHub MCP tool.

Missing Alternative Instructions:

• No Claude-specific guidance for the GitHub Web Interface workflow creation path
• No explicit statement that the Copilot custom agent files (/agent command) are Copilot-exclusive
• Missing Claude+GitHub MCP additional configuration (promised in auth.mdx but absent in engines.md)

---

Severity-Categorized Findings

🚫 Critical Blockers (Score: 0)

None found. Claude Code users can complete the full onboarding path without Copilot.

⚠️ Major Obstacles (Score: 4 found)

Obstacle 1: Architecture Diagram Hardcodes "Copilot CLI"

Impact: Significant confusion about whether Claude/Codex users have a different runtime architecture

Current State: The AWF firewall diagram in architecture.mdx shows:

COPILOT["Copilot CLI"]
WEB["WebFetch Tool"]
SEARCH["WebSearch Tool"]
```
and the MCP gateway diagram shows:
```
AGENT["Agent container\nCopilot CLI + MCP client\n172.30.0.20"]
```

**Why It's Problematic:** A Claude Code user reading this diagram would see "Copilot CLI" as a runtime component. They would not know whether Claude Code CLI runs in the same container position or whether there's a different architecture for non-Copilot engines. The rest of the diagram would still apply correctly, but the label creates doubt.

**Suggested Fix:** Change the label from `COPILOT["Copilot CLI"]` to `ENGINE["AI Agent\n(Copilot/Claude/Codex CLI)"]` and update the MCP gateway diagram to show `"Agent container\nAI Engine CLI + MCP client"`.

**Affected Files:** `docs/src/content/docs/introduction/architecture.mdx` lines 177-178, 248

</details>

<details>
<summary><b>Obstacle 2: Broken Cross-Reference Links in auth.mdx</b></summary>

**Impact:** Users cannot navigate to promised additional documentation; broken link may render as garbled text

**Current State:** `auth.mdx` contains:
```
See also (/gh-aw/reference/engines/#using-claude-by-anthropic-claude-code) for additional configuration needed when using Claude with GitHub MCP.
```
This is not valid Markdown link syntax — it's a bare URL in parentheses. A proper link would be: `See also [Claude engine docs](/gh-aw/reference/engines/#using-claude-by-anthropic-claude-code)...`

**Why It's Problematic:** The link won't render as clickable. Users following the auth setup for Claude will see the text "See also (/gh-aw/reference/engines/...)" and either try to copy-paste the URL or ignore it.

**Suggested Fix:** Fix the Markdown syntax: `See also [Claude engine configuration](/gh-aw/reference/engines/#using-claude-by-anthropic-claude-code) for additional configuration needed when using Claude with GitHub MCP.`

**Affected Files:** `docs/src/content/docs/reference/auth.mdx` lines 113, 131

</details>

<details>
<summary><b>Obstacle 3: Unfulfilled Documentation Promise for Claude + GitHub MCP</b></summary>

**Impact:** Claude users trying to use GitHub MCP tools have no guidance; they may experience runtime failures

**Current State:** `auth.mdx` line 113 promises: "See also ... for **additional configuration needed when using Claude with GitHub MCP**." But the referenced section in `engines.md` (lines 44-58) only documents:
1. Set `engine: claude` in frontmatter
2. Set `ANTHROPIC_API_KEY` secret

There is no "additional configuration" section for Claude + GitHub MCP. The equivalent Codex section in `auth.mdx` line 131 has the same broken promise.

**Why It's Problematic:** Claude users who need GitHub MCP integration (which requires `GH_AW_GITHUB_TOKEN`) would be sent on a wild goose chase. The auth.mdx documentation for `GH_AW_GITHUB_TOKEN` mentions "Codex engine operations: Required for GitHub MCP integration" but not Claude specifically.

**Suggested Fix:** Either (a) add an actual "Using Claude with GitHub MCP" subsection to `engines.md` explaining the `GH_AW_GITHUB_TOKEN` requirement, or (b) remove the "additional configuration" promise from `auth.mdx` and add a direct explanation of the `GH_AW_GITHUB_TOKEN` requirement for the remote GitHub tools mode when using Claude.

**Affected Files:** `docs/src/content/docs/reference/auth.mdx` lines 113, 131; `docs/src/content/docs/reference/engines.md` section "Using Claude by Anthropic"

</details>

<details>
<summary><b>Obstacle 4: Copilot Custom Agent Page Has No Non-Copilot Warning</b></summary>

**Impact:** Claude Code users may waste time trying to use `/agent agentic-workflows` commands

**Current State:** `custom-agent-for-aw.mdx` describes using the Copilot custom agent for creating, updating, and debugging workflows. The section header is "Copilot Agent Files support for Agentic Workflows" but the page body immediately starts installing and using it without a clear "Copilot required" prerequisite.

**Why It's Problematic:** The page URL and sidebar are part of the general setup documentation. A Claude Code user could land here from the sidebar and spend time trying to use `/agent agentic-workflows` commands that require Copilot access.

**Suggested Fix:** Add a prominent note at the top of the page: "This feature requires GitHub Copilot access. If you use Claude Code or Codex, see [Creating Workflows](/gh-aw/setup/creating-workflows/#vscodeclaudecodexcopilot) for the equivalent workflow creation approach."

**Affected Files:** `docs/src/content/docs/reference/custom-agent-for-aw.mdx`

</details>

### 💡 Minor Confusion Points (Score: 5 found)

- **Issue 1:** `gh aw init` described as "Configures Copilot instructions" - File: `docs/src/content/docs/setup/cli.md` line 120. Should say "AI agent configuration" to avoid implying Copilot-only.
- **Issue 2:** `how-they-work.mdx` line 26 — "Workflows support **GitHub Copilot** (default), Claude by Anthropic, and Codex." The parenthetical "(default)" is accurate but places Copilot as the primary engine in the conceptual introduction. Could be rephrased as "Workflows support multiple AI engines including GitHub Copilot, Claude by Anthropic, and Codex. The default engine is Copilot."
- **Issue 3:** `creating-workflows.mdx` line 70 — "If not using Copilot, also adjust the `engine:` field" implies Copilot is the expected path. The note could be integrated: "Set the `engine:` field (`copilot`, `claude`, or `codex`) and corresponding secret."
- **Issue 4:** `engines.md` — The `model` field documentation example shows `model: gpt-5  # defaults to claude-sonnet-4`. The comment "defaults to claude-sonnet-4" on an example under the Copilot section is confusing — does Copilot default to a Claude model?
- **Issue 5:** Web search guide (`guides/web-search.md`) only shows a `engine: copilot` example, even though the tools.md notes that web search is "engine-dependent." A Claude-engine example using Tavily MCP would complete this guide.

---

## Engine Comparison Analysis

### Available Engines

Based on my review, gh-aw supports these engines:
- `engine: copilot` — Well-documented with setup videos, custom agent support, and `83` workflow examples
- `engine: claude` — Adequately documented with clear setup steps and `37` workflow examples
- `engine: codex` — Minimally documented with `12` workflow examples
- `engine: custom` — Mentioned in extended config but no dedicated documentation page found

### Documentation Quality by Engine

| Engine | Setup Docs | Examples | Auth Docs | Overall Score |
|--------|-----------|----------|-----------|---------------|
| Copilot | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ |
| Claude | ⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐⭐ |
| Codex | ⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐⭐ |
| Custom | ⭐ | ⭐ | ⭐ | ⭐ |

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

---

## Tool Availability Analysis

### Tools Review

**Engine-Agnostic Tools** (work with any engine):
- `edit:` — File editing
- `bash:` — Shell command execution
- `github:` — GitHub API (local and remote mode)
- `playwright:` — Browser automation
- `web-fetch:` — Web content fetching
- `cache-memory:` — Persistent memory across runs
- `repo-memory:` — Repository-specific memory
- `agentic-workflows:` — Workflow introspection
- Custom MCP servers via `mcp-servers:`

**Engine-Specific Tools:**
- `web-search:` — "engine-dependent" per tools.md; the web search guide only shows Copilot. Not clear if Claude has native web search or always requires Tavily MCP.

**Unclear/Undocumented:**
- The `agent:` field in extended engine config — documented only for Copilot (custom agent files). No equivalent for Claude.
- Copilot-specific `copilot plugin install` vs. what Claude Code's plugin system (if any) looks like.

---

## Authentication Requirements

### Current Documentation

Quick Start guide covers authentication for:
- ✅ Copilot — Detailed instructions with video tutorial
- ✅ Claude — Clear instructions (set `ANTHROPIC_API_KEY`), but with a broken cross-reference promising more
- ✅ Codex — Clear instructions (set `OPENAI_API_KEY`), same broken cross-reference issue
- ❓ Custom — Not documented

### Missing for Claude Users

- Clarity on whether `GH_AW_GITHUB_TOKEN` is required for Claude + GitHub MCP (the auth.mdx implies yes but doesn't say so directly in the Claude section)
- The engines.md "Using Claude" section should note: "To use remote GitHub MCP mode (`github: mode: remote`), you also need to configure `GH_AW_GITHUB_TOKEN`"

### Secret Names

| Engine | Secret | Status |
|--------|--------|--------|
| Copilot | `COPILOT_GITHUB_TOKEN` | ✅ Documented with video |
| Claude | `ANTHROPIC_API_KEY` | ✅ Documented |
| Codex | `OPENAI_API_KEY` | ✅ Documented |
| GitHub MCP (all engines) | `GH_AW_GITHUB_TOKEN` | ⚠️ Documented but connection to Claude unclear |

---

## Example Workflow Analysis

### Workflow Count by Engine

```
Engine: copilot  - 83 workflows found
Engine: claude   - 37 workflows found
Engine: codex    - 12 workflows found
Engine: custom   -  0 workflows found
(21 workflows use no explicit engine field, defaulting to Copilot)

Quality of Examples

Copilot Examples:
Large selection (83) demonstrating the full range of capabilities. Many appear to be production workflows in the gh-aw repository itself.

Claude Examples:
Good selection (37) including smoke-claude.md which demonstrates a sophisticated Claude workflow with Playwright, MCP servers, and multiple imports. The claude-code-user-docs-review.md workflow (this very workflow) is a great Claude example. Sufficient for a new user to understand Claude engine capabilities.

Codex Examples:
Limited selection (12). Could use more variety to demonstrate Codex-specific patterns.

---

Recommended Actions

Priority 1: Critical Documentation Fixes

1. Fix broken Markdown links in auth.mdx — Lines 113 and 131 contain bare URLs in parentheses instead of proper [text](url) Markdown links. File: docs/src/content/docs/reference/auth.mdx

2. Add Claude+GitHub MCP guidance — Either add content to engines.md explaining GH_AW_GITHUB_TOKEN requirements for Claude when using remote GitHub MCP mode, or update auth.mdx to stop promising content that doesn't exist in engines.md. File: docs/src/content/docs/reference/engines.md and/or docs/src/content/docs/reference/auth.mdx

3. Add "Requires Copilot" notice to custom-agent-for-aw.mdx — Claude Code users need to know immediately this page does not apply to them. File: docs/src/content/docs/reference/custom-agent-for-aw.mdx

Priority 2: Major Improvements

1. Update AWF firewall Mermaid diagram labels — Replace COPILOT["Copilot CLI"] with engine-neutral labels in the architecture diagrams. File: docs/src/content/docs/introduction/architecture.mdx

2. Update gh aw init description — Replace "Copilot instructions" with "AI agent configuration" or similar engine-neutral language. File: docs/src/content/docs/setup/cli.md line 120

3. Clarify model defaults in extended engine config — The example model: gpt-5 # defaults to claude-sonnet-4 under the Copilot section is confusing. File: docs/src/content/docs/reference/engines.md

Priority 3: Nice-to-Have Enhancements

1. Add Claude engine example to web search guide — Show a Claude-engine workflow using Tavily MCP alongside the Copilot example. File: docs/src/content/docs/guides/web-search.md

2. Engine-neutral phrasing in creating-workflows.mdx — Reframe "If not using Copilot, also adjust the engine: field" as a positive instruction for all users. File: docs/src/content/docs/setup/creating-workflows.mdx

3. Add a "Choosing an Engine" section — A brief comparison table (Copilot vs Claude vs Codex) in the engines reference would help new users make an informed choice. Currently there's no "why would I choose Claude?" guidance.

---

Positive Findings

What Works Well for Claude Code Users

• ✅ Quick Start prerequisites explicitly list Claude — First thing a new user reads lists all three options equally
• ✅ gh aw add-wizard is fully engine-aware — The interactive setup correctly handles Claude selection and ANTHROPIC_API_KEY setup
• ✅ Authentication reference covers all engines clearly — Despite broken links, the actual content for ANTHROPIC_API_KEY is correct and complete
• ✅ 37 real Claude engine workflows in the repository — Plenty of examples to learn from
• ✅ All core tools are engine-agnostic — GitHub API, Playwright, bash, edit, MCP servers all work with Claude
• ✅ Engines reference page has dedicated Claude section — Clear, correct 3-step setup process
• ✅ The how-they-work.mdx intro page names Claude as a supported engine in the second paragraph
• ✅ creating-workflows.mdx has a "VSCode/Claude/Codex/Copilot" section with engine-neutral instructions

---

Conclusion

Can Claude Code Users Successfully Adopt gh-aw?

Answer: Yes, with minor effort

Reasoning: The core onboarding path — prerequisites, Quick Start, add-wizard, authentication setup, and first workflow — is genuinely engine-neutral and explicitly covers Claude. A Claude Code user following the Quick Start will successfully get gh-aw running. The 37 existing Claude engine workflows provide ample examples to build from.

The friction points exist in secondary documentation: architecture diagrams that suggest Copilot CLI is a required runtime component, broken links that lead nowhere, an unfulfilled promise of additional Claude+MCP configuration, and a Copilot-only custom agents page that lacks a clear "this requires Copilot" warning. These are fixable documentation issues, not architectural limitations.

Overall Assessment Score: 7/10

Breakdown:

• Clarity for non-Copilot users: 7/10 (core path clear; secondary docs have Copilot assumptions)
• Claude engine documentation: 7/10 (setup is documented; advanced topics like Claude+MCP are incomplete)
• Alternative approaches provided: 8/10 (good alternatives given for most features)
• Engine parity in docs: 6/10 (Copilot has significantly more examples and tutorials)

Next Steps

1. Fix the two broken Markdown links in auth.mdx (5-minute fix)
2. Add or link the promised "Claude + GitHub MCP additional configuration" (30-minute fix)
3. Add "Requires Copilot" notice to custom-agent-for-aw.mdx (5-minute fix)
4. Update architecture diagram labels from "Copilot CLI" to engine-neutral (15-minute fix)
5. Track these issues over time — the daily audit workflow will re-evaluate after fixes are applied

---

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/introduction/overview.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/faq.md (partial)
• docs/src/content/docs/reference/custom-agent-for-aw.mdx
• docs/src/content/docs/reference/frontmatter.md (partial)
• docs/src/content/docs/guides/web-search.md
• Sample workflows: smoke-claude.md, claude-code-user-docs-review.md
• Engine distribution across all 153 .github/workflows/*.md files

---

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

AI generated by Claude Code User Documentation Review

• expires on Feb 27, 2026, 10:38 PM UTC