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

[github-actions[bot]]

Executive Summary

As a developer who uses Claude Code and actively avoids GitHub Copilot, I reviewed the gh-aw documentation to determine whether non-Copilot users can successfully adopt this tool. The documentation has improved significantly and largely does not block a Claude Code user from getting started — but key friction points remain, primarily around Copilot-centric defaults, diagrams that embed Copilot CLI as the only pictured agent, and a few places where the authoring workflow for workflows still assumes Copilot Chat.

Key Finding: Claude Code users can successfully use gh-aw, but the onboarding experience creates unnecessary friction through Copilot-first defaults, a misleading architecture diagram, and an undocumented model typo. No absolute blockers exist; most gaps are "major obstacles" or "paper cuts."

---

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 moderate friction.

The Quick Start (quick-start.mdx) lists three AI account options at the top of the Prerequisites: Copilot, Anthropic Claude, and OpenAI Codex. That is a positive signal — a Claude Code user is not invisible here.

However, in Step 2, the add-wizard command says:

"Select an AI Engine - Choose between Copilot, Claude, or Codex."

This is clear and reassuring. The wizard handles all three paths interactively.

The "How It Works" page (how-they-work.mdx) mentions Copilot as the "default" in two separate places, once in the AI Engines section and once implicitly through the Mermaid diagram that labels the agent process as "Copilot CLI". A new user reading this page might reasonably infer that Claude is second-class.

Specific Issues Found:

• Issue 1 — Architecture diagram embeds "Copilot CLI" as the canonical agent label (docs/src/content/docs/introduction/architecture.mdx, lines 177 and 248). The AWF firewall flow diagram labels the agent subprocess as COPILOT["Copilot CLI"] and the agent container as AGENT["Agent container\nCopilot CLI + MCP client\n172.30.0.20"]. A Claude or Codex user sees their engine omitted from the architecture diagram, reinforcing a perception that Copilot is the "real" engine and others are bolt-ons.

• Issue 2 — gh aw init documentation describes Copilot-specific output (docs/src/content/docs/setup/cli.md, line 120). The description states init "Configures .gitattributes, Copilot instructions, prompt files, and logs .gitignore." A Claude Code user reading "Copilot instructions" may not know whether this step will work for them or whether it creates Copilot-specific files they don't need.

• Issue 3 — FAQ "workflow authoring" section recommends Copilot Chat (docs/src/content/docs/reference/faq.md, line 327). It reads: "AI-assisted authoring using /agent agentic-workflows create in GitHub Copilot Chat provides interactive guidance..." — no equivalent Claude Code authoring flow is mentioned.

Recommended Fixes:

• Rename the Copilot CLI node in the AWF diagram to a generic "AI Agent" label or show all three engines.
• Clarify gh aw init description to note it creates generic "AI agent instructions" files, or at minimum note these work for all engines.
• Add a note in the FAQ "authoring" section that Claude Code users can create workflows manually or via gh aw new, since they lack Copilot Chat.

---

Question 2: Inaccessible Features for Non-Copilot Users

What features or steps don't work without Copilot?

Features That Require Copilot:

• assign-to-agent safe output (assigns the GitHub platform's asynchronous Copilot coding agent to issues/PRs) — requires GH_AW_AGENT_TOKEN and is explicitly for the Copilot platform's coding agent. This is clearly documented as a Copilot-specific feature.
• /agent agentic-workflows create workflow authoring in Copilot Chat — only available to Copilot subscribers.
• engine: copilot with agent: field for custom Copilot agents — Copilot-specific feature, well documented.

Features That Work Without Copilot:

• All core workflow mechanics: compile, run, schedule, triggers, safe outputs, safe inputs, MCP servers, tools.
• engine: claude — fully supported with ANTHROPIC_API_KEY.
• All GitHub tools (issues, PRs, repos, discussions, etc.) — engine-agnostic.
• Playwright, bash, edit, web-fetch, cache-memory, repo-memory — all engine-agnostic.
• The entire CLI (gh aw compile, gh aw run, gh aw logs, gh aw audit, etc.) — works for all engines.
• Security architecture (AWF firewall, MCP sandboxing, threat detection, safe outputs) — engine-agnostic.

Missing Documentation:

• There is no explicit section or callout box saying "here is what you cannot do without a Copilot subscription." A summary table or note listing Copilot-exclusive features would help Claude users quickly determine what they're missing.
• The assign-to-agent safe output documentation doesn't have a prominent note that this is Copilot-exclusive; a user might spend time setting it up only to discover it doesn't apply to Claude 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 diagram (Mermaid) labels the agent process as COPILOT["Copilot CLI"] instead of a generic label. Two occurrences: lines 177 and 248.
• File: docs/src/content/docs/reference/engines.md — Line 88: The extended engine config shows model: gpt-5 with the comment # defaults to claude-sonnet-4. This comment is wrong in context (this block has id: copilot, so the default is not claude-sonnet-4) and will confuse both Claude and Copilot users. It reads as if the Copilot engine defaults to a Claude model.
• File: docs/src/content/docs/setup/cli.md — Line 120: gh aw init describes configuring "Copilot instructions", which is ambiguous for non-Copilot users.
• File: docs/src/content/docs/reference/faq.md — Lines 157 and 209: The FAQ's "How is my code processed?" and "Why do I need a token?" sections describe the flow primarily in terms of Copilot CLI with Claude/Codex mentioned only parenthetically. The "token" question answer is entirely Copilot-focused, making a Claude user think the reasoning doesn't apply to them.
• File: docs/src/content/docs/introduction/architecture.mdx — The MCP Gateway diagram labels the agent container as "Copilot CLI + MCP client", making the architecture look Copilot-specific.

Missing Alternative Instructions:

• No "Getting Started with Claude" guide that mirrors the Quick Start but focuses on Claude-specific setup decisions (e.g., which Claude model to pick, how API key billing works, rate limits to be aware of).
• No documentation on Claude-specific model: values (e.g., claude-opus-4-5, claude-sonnet-4, claude-haiku-4-5). The engine docs only show model: gpt-5 with a confusing comment.
• No guidance comparing Claude vs. Copilot capability tradeoffs (e.g., context window differences, tool call behavior, web search availability differences).

---

Severity-Categorized Findings

🚫 Critical Blockers (Score: 0)

No absolute blockers found. A Claude Code user can follow the Quick Start and get a working workflow using engine: claude.

⚠️ Major Obstacles (Score: 6/10 friction)

Obstacle 1: Architecture Diagram Shows "Copilot CLI" as the Only Agent

Impact: Significant confusion — the architecture looks Copilot-specific, undermining confidence that Claude is a first-class engine.

Current State: The AWF firewall diagram in architecture.mdx (lines 174–219) shows:

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

And the MCP Gateway diagram (line 248) shows AGENT["Agent container\nCopilot CLI + MCP client\n172.30.0.20"].

Why It's Problematic: A Claude Code user reading the security architecture will see their engine is not represented, and might assume the security properties described only apply to Copilot.

Suggested Fix: Change COPILOT["Copilot CLI"] to ENGINE["AI Engine\n(Copilot/Claude/Codex)"] and update the MCP Gateway diagram's agent container label similarly.

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

Obstacle 2: Misleading Model Comment in Engine Config Example

Impact: Actively confusing — suggests Copilot engine defaults to a Claude model, creating confusion for both user types.

Current State: docs/src/content/docs/reference/engines.md, lines 84–91:

engine:
  id: copilot
  version: latest                       # defaults to latest
  model: gpt-5                          # defaults to claude-sonnet-4
  args: ["--add-dir", "/workspace"]     # custom CLI arguments
  agent: agent-id                       # custom agent file identifier

The comment # defaults to claude-sonnet-4 on the model: line under id: copilot appears to say the Copilot engine defaults to claude-sonnet-4. This is almost certainly a copy-paste or authoring error.

Why It's Problematic: Claude users may think they need to configure id: copilot with model: claude-sonnet-4, or may be confused about why a Copilot config references Claude. Copilot users will be confused about their own defaults.

Suggested Fix: Fix the comment to accurately reflect the Copilot engine's actual default model (e.g., # e.g., gpt-4o, claude-sonnet-4, etc. or split into separate examples per engine).

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

Obstacle 3: No Claude-Specific Model Reference

Impact: Claude users don't know which model strings are valid for engine: claude.

Current State: The engines reference page (engines.md) shows one combined "Extended Coding Agent Configuration" block using id: copilot with model: gpt-5. There is no example showing id: claude with valid Claude model names.

Why It's Problematic: A user wanting to use a specific Claude model (e.g., Haiku for cost reduction) has no reference for what value to put in model:. They must rely on external Anthropic docs and guess at the correct model ID string.

Suggested Fix: Add a Claude-specific example block showing model configuration:

engine:
  id: claude
  model: claude-haiku-4-5   # cheaper/faster option
  # model: claude-sonnet-4  # balanced (default)
  # model: claude-opus-4    # most capable
```

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

</details>

<details>
<summary><b>Obstacle 4: FAQ "Why do I need a token?" Explains Only Copilot Rationale</b></summary>

**Impact:** Claude users may not understand why they're providing an API key or how billing works.

**Current State:** `docs/src/content/docs/reference/faq.md`, line 209: "When using GitHub Copilot CLI, a Personal Access Token (PAT) with 'Copilot Requests' permission authenticates and associates automation work with your GitHub account. This ensures usage tracking against your subscription..."

The answer gives no explanation for why Claude users need an `ANTHROPIC_API_KEY`.

**Suggested Fix:** Expand this FAQ answer to address all three engines with a parallel structure, explaining that each key authenticates against the respective provider's billing and usage system.

**Affected Files:** `docs/src/content/docs/reference/faq.md`

</details>

<details>
<summary><b>Obstacle 5: Workflow Authoring via AI Only References Copilot Chat</b></summary>

**Impact:** Claude Code users following the "creating workflows with AI" guidance will hit a dead end.

**Current State:** `docs/src/content/docs/reference/faq.md`, line 327: `"AI-assisted authoring using /agent agentic-workflows create in GitHub Copilot Chat provides interactive guidance..."` No equivalent is mentioned for Claude Code users.

**Suggested Fix:** Add a note that Claude Code users can use `gh aw new` for a template, then edit manually or ask Claude Code to help draft workflow frontmatter and instructions. Optionally, document a `/agent` or prompt pattern usable in Claude Code.

**Affected Files:** `docs/src/content/docs/reference/faq.md`

</details>

### 💡 Minor Confusion Points (Score: 3/10)

- **Issue 1:** `gh aw init` description says "Configures Copilot instructions" — not clear to a Claude Code user whether this does anything useful for them. File: `docs/src/content/docs/setup/cli.md`
- **Issue 2:** `docs/src/content/docs/introduction/how-they-work.mdx` mentions "GitHub Copilot (default)" in the AI Engines section but does not explain the implication of that default for a user who doesn't have Copilot — i.e., they need to explicitly set `engine: claude`.
- **Issue 3:** The FAQ "What hidden runtime dependencies does this have?" (`faq.md` line 213) says the default is "GitHub Copilot CLI" without explaining that setting `engine: claude` avoids that dependency entirely. A Claude user might wonder if Copilot CLI is still installed even if they use Claude.
- **Issue 4:** The `assign-to-agent` safe output in `docs/src/content/docs/reference/safe-outputs.md` does not have a prominent "Copilot only" callout. A Claude user might attempt to configure this.

---

## Engine Comparison Analysis

### Available Engines

Based on my review, gh-aw supports these engines:
- `engine: copilot` — First-class, well-documented, is the default, has custom agent support, has the most examples in the repo.
- `engine: claude` — Fully functional, documented in auth and engines pages, 31+ real workflows in the repository use it.
- `engine: codex` — Supported, documented, 10 workflows use it.
- Custom / other — Not currently supported; FAQ encourages contributing support.

### Documentation Quality by Engine

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

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

**Note:** Claude scores lower on Model Config because there are no Claude-specific model name examples in the documentation. The auth docs for Claude are good — `ANTHROPIC_API_KEY` setup is clear and well-placed.

---

## Tool Availability Analysis

### Tools Review

**Engine-Agnostic Tools (all engines):**
- `github:` (GitHub MCP server, all toolsets)
- `edit:` (file editing)
- `bash:` (shell commands with allowlist)
- `web-fetch:` (HTTP fetching)
- `playwright:` (browser automation)
- `agentic-workflows:` (workflow introspection)
- `cache-memory:` / `repo-memory:` (persistent memory)
- Custom MCP servers via `mcp-servers:`

**Engine-Specific Tools:**
- `web-search:` — Documentation notes "some engines require third-party MCP servers for web search." This is slightly ambiguous; Copilot CLI has built-in web search, Claude does not without an MCP server (e.g., Tavily).
- Copilot `agent:` field — Only for Copilot engine custom agents.

**Unclear/Undocumented:**
- Which specific Claude model IDs are supported (as noted above).
- Whether `web-search:` works out of the box with Claude or requires explicit MCP configuration — the tools reference (`tools.md`) says "See Using Web Search" but doesn't call out the per-engine difference prominently.

---

## Authentication Requirements

### Current Documentation Status

Quick Start guide covers authentication for:
- ✅ Copilot (detailed instructions with video tutorials)
- ✅ Claude (clearly documented: `ANTHROPIC_API_KEY`, link to Anthropic platform)
- ✅ Codex (clearly documented: `OPENAI_API_KEY`, link to OpenAI platform)

The auth reference page (`auth.mdx`) is well-structured, listing all three engine secrets at the top with setup steps. The `add-wizard` command handles secret setup interactively for all three.

### Secret Names (Documented)

| Engine | Secret Name | Documentation Quality |
|--------|------------|----------------------|
| Copilot | `COPILOT_GITHUB_TOKEN` | ⭐⭐⭐⭐⭐ (video, detailed steps) |
| Claude | `ANTHROPIC_API_KEY` | ⭐⭐⭐⭐ (clear steps, link to Anthropic docs) |
| Codex | `OPENAI_API_KEY` | ⭐⭐⭐⭐ (clear steps, link to OpenAI docs) |

One minor note: the `auth.mdx` entry for `ANTHROPIC_API_KEY` has a broken internal link: `See also (/gh-aw/reference/engines/#using-claude-by-anthropic-claude-code)` — the parenthetical format looks like it was meant to be a markdown link but is missing the `[]` brackets. This would render as plain text rather than a link.

---

## Example Workflow Analysis

### Workflow Count by Engine (in `.github/workflows/`)

```
Engine: claude  - 31 workflows
Engine: copilot - 73 workflows  
Engine: codex   - 10 workflows

Quality of Examples

Copilot Examples:
Large collection, covering diverse use cases: CI coaching, auto-triage, PR analysis, performance summaries, security scans, etc.

Claude Examples:
31 workflows is a substantial collection and covers real, complex use cases: smoke testing, blog auditing, code metrics, documentation consolidation, schema checking, security red-teaming, and more. The smoke-claude.md workflow in particular is an excellent, comprehensive reference that exercises virtually every Claude-specific capability.

The quality gap: Copilot has more examples (73 vs. 31), but Claude's examples are sophisticated and real — they're not toy examples. The distribution reflects that this project was likely developed primarily with Copilot and then Claude support was added and is now heavily used internally.

---

Recommended Actions

Priority 1: Critical Documentation Fixes

1. Fix misleading model comment in engines.md — The # defaults to claude-sonnet-4 comment under id: copilot is incorrect and confusing. Fix: docs/src/content/docs/reference/engines.md, line 88.
2. Fix broken internal link in auth.mdx — See also (/gh-aw/reference/engines/...) needs to be a proper markdown link [See also](/gh-aw/reference/engines/...). Fix: docs/src/content/docs/reference/auth.mdx, line 110.

Priority 2: Major Improvements

1. Update architecture diagrams to be engine-agnostic — Replace COPILOT["Copilot CLI"] labels with generic ENGINE["AI Engine"] labels. This is a high-visibility change that signals engine equality. Fix: docs/src/content/docs/introduction/architecture.mdx, lines 177 and 248.
2. Add Claude-specific model configuration examples — Add a Claude engine: block showing valid model names to engines.md.
3. Expand FAQ "Why do I need a token?" to cover all engines — Currently only explains Copilot. Fix: docs/src/content/docs/reference/faq.md, line 209.
4. Add non-Copilot authoring guidance to FAQ — Note that gh aw new + manual editing or Claude Code assistance is the path for non-Copilot users. Fix: docs/src/content/docs/reference/faq.md, line 327.
5. Add "Copilot-only features" summary — A small callout box or table noting which features are Copilot-exclusive (assign-to-agent, custom Copilot agents, Copilot Chat authoring) would prevent Claude users from wasting time on features they can't use.

Priority 3: Nice-to-Have Enhancements

1. Add a "Getting Started with Claude" guide — Mirror the Quick Start but focused on Anthropic API key setup, Claude model selection, and Claude-specific capabilities (e.g., large context window).
2. Document web-search availability per engine — Clarify whether Claude requires an MCP server (e.g., Tavily) for web search and how to set it up.
3. Add engine comparison table — A simple table showing feature parity across Copilot, Claude, and Codex would help users choose and understand trade-offs.

---

Positive Findings

What Works Well

• ✅ Quick Start prerequisites correctly list all three AI account options (Copilot, Anthropic Claude, OpenAI Codex) — no Copilot-only gatekeeping at entry.
• ✅ add-wizard command handles Claude engine selection interactively — a smooth onboarding path.
• ✅ ANTHROPIC_API_KEY is well-documented with clear setup steps and link to Anthropic platform.
• ✅ engine: claude is simple to configure — a single line in frontmatter.
• ✅ The repository itself has 31 Claude-engine workflows, demonstrating extensive real-world use.
• ✅ The smoke-claude.md workflow is an excellent, comprehensive reference workflow.
• ✅ Authentication page (auth.mdx) is well-organized and clearly distinguishes the three engine tokens.
• ✅ Tools are broadly engine-agnostic — a Claude user has access to the same GitHub tools, Playwright, bash, MCP servers, etc.
• ✅ gh aw secrets bootstrap --engine claude works for Claude-specific secret discovery.
• ✅ Security architecture documentation is engine-agnostic in substance (only the diagrams are Copilot-labeled).

---

Conclusion

Can Claude Code Users Successfully Adopt gh-aw?

Answer: Yes, with moderate friction

A Claude Code user who reads the documentation carefully will find everything they need to set up and run agentic workflows. The Quick Start correctly identifies Claude as a first-class option, the authentication documentation is clear, and the tooling supports all three engines equally. The real workflows using engine: claude in this repository demonstrate the feature is production-quality, not experimental.

The main friction points are presentational: a diagram that shows Copilot CLI as the only agent, a confusing model comment that implies Copilot defaults to a Claude model, and FAQ answers that explain rationale only in Copilot terms. None of these prevent success, but they accumulate into a sense that Claude is an afterthought — which the actual feature parity does not support.

Overall Assessment Score: 7.5/10

Breakdown:

• Clarity for non-Copilot users: 7/10 (functional, but Copilot-first framing persists)
• Claude engine documentation: 8/10 (auth and setup are good; model config reference missing)
• Alternative approaches provided: 7/10 (available but not always highlighted)
• Engine parity (actual feature coverage): 9/10 (nearly full parity, only Copilot-specific features excluded)

Next Steps

Fix the two quick wins (broken link + model comment) in the next PR. Then tackle the architecture diagram labels and FAQ gaps in a documentation pass. The "Getting Started with Claude" guide would significantly improve the new-user experience for Claude Code users and could draw from the many existing Claude workflows in this repository as examples.

---

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/auth.mdx
• docs/src/content/docs/reference/engines.md
• docs/src/content/docs/reference/faq.md
• .github/workflows/smoke-claude.md (example workflow)
• .github/workflows/audit-workflows.md (example workflow)
• .github/workflows/blog-auditor.md (example workflow)
• Workflow engine distribution across 100+ .github/workflows/*.md files

---

Report Generated: 22160320088
Workflow: claude-code-user-docs-review
Engine Used: claude (eating our own dog food! 🐕)
Date: 2026-02-18

AI generated by Claude Code User Documentation Review

• expires on Feb 25, 2026, 10:37 PM UTC

[github-actions[bot]]

🤖 Beep boop! The smoke test agent was here! 🎉

Just passing through to verify that MCP tools, GitHub API, and all the plumbing works correctly. Nothing to see here... unless you enjoy knowing that an AI just high-fived your discussion. 🖐️✨

— The Copilot Smoke Test Agent, on duty since forever

📰 BREAKING: Report filed by Smoke Copilot for issue #16594

[github-actions[bot]]

💥 WHOOSH! ZAP! POW! 🦸

THE SMOKE TEST AGENT WAS HERE!

KABLAM! Like a bolt from the cosmic void, Claude's smoke test agent swooped in at warp speed — 2026-02-18 — and left its mark upon this discussion!

⚡ SYSTEMS: NOMINAL! ⚡

The agent vanishes into the digital ether... but its legend lives on!

🌟 "With great workflows comes great responsibility." 🌟

💥 [THE END] — Illustrated by Smoke Claude for issue #16594