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

[github-actions[bot]]

Executive Summary

This review evaluates the gh-aw documentation from the perspective of a developer who uses Claude Code as their primary AI assistant and actively does not use GitHub Copilot. The core finding is positive: Claude Code users can successfully adopt gh-aw, and the essential documentation is present. However, the docs are structurally Copilot-first — with 71 occurrences of engine: copilot versus 7 engine: claude in the documentation source files — creating friction and the impression that Claude is second-class.

Key Finding: The documentation supports Claude users adequately but doesn't welcome them proactively. No critical blockers exist, but the cumulative weight of Copilot-defaults and Copilot-centric examples creates a noticeable headwind.

---

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, but the docs lead with Copilot.

The Quick Start quick-start.mdx does the right thing upfront — the Prerequisites section (line 29) explicitly lists all four AI options: "GitHub Copilot, Anthropic Claude, OpenAI Codex, or Google Gemini." Claude is a first-class option here. Step 2 confirms the add-wizard command prompts for engine selection and lists ANTHROPIC_API_KEY as an option (line 70).

Specific Issues Found:

• Issue 1: engines.md line 27 says: "Copilot is the default choice for most users... If you are unsure, start with Copilot." There is no equivalent "If you prefer Claude Code..." path. A developer who actively chose Claude over Copilot will read this and feel like a second-class user rather than a supported use case.

• Issue 2: The CLI reference (cli.md) shows gh aw new my-workflow --engine claude as a supported flag, which is great, but there's no "Getting Started with Claude" guide that mirrors the Copilot experience.

• Issue 3: how-they-work.mdx line 26 mentions "GitHub Copilot (default)" without context explaining that the default can easily be changed. A new user skimming might conclude Copilot is required.

Recommended Fixes:

• Add a "Claude Code users" callout in how-they-work.mdx near the engines description
• Amend the "Which engine should I choose?" section to include a recommendation for Claude users (e.g., "Choose Claude if you use Claude Code and prefer Anthropic's models")

---

Question 2: Inaccessible Features for Non-Copilot Users

What features or steps don't work without Copilot?

Features That Require Copilot (by design):

• engine.agent — custom agent files in .github/agents/ (Copilot-only)
• engine.harness — custom harness script replacement (Copilot-only)
• max-continuations — autopilot multi-run mode (Copilot-only)
• Crush and OpenCode experimental engines — both require COPILOT_GITHUB_TOKEN

Features That Work Without Copilot (well-documented):

• Core workflow execution with engine: claude
• All built-in tools (edit, bash, github, web-fetch, playwright, cache-memory)
• MCP servers (custom and built-in)
• Safe Outputs (create issues, PRs, comments)
• max-turns (Claude-specific, actually superior to Copilot for bounded sessions)
• All CLI commands (gh aw compile, gh aw run, gh aw logs, etc.)

Missing Documentation:

• No explicit "Claude Feature Parity" table or callout confirming what Claude users get
• No "Getting Started with Claude" quick path (separate from the Copilot-default flow)

---

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 & 252: Mermaid diagrams label the agent container as "Copilot CLI" specifically, not a generic "AI Engine" or "Agent CLI". This is technically inaccurate (the container runs whichever engine is configured) and implies the architecture is Copilot-specific.

• File: docs/src/content/docs/introduction/architecture.mdx — Line 228: The AWF network configuration example shows engine: copilot, even though the surrounding text is engine-agnostic.

• File: docs/src/content/docs/reference/engines.md — Line 27: "If you are unsure, start with Copilot" — this is the primary call-to-action for new users with no Claude equivalent.

• File: docs/src/content/docs/reference/engines.md — Line 23: "Copilot CLI is the default — engine: can be omitted when using Copilot" — while accurate, there's no corresponding note that Claude users must always add engine: claude.

Missing Alternative Instructions:

• No "If you use Claude, set engine: claude in all your workflows" orientation note for new users
• No Claude-specific troubleshooting section (Copilot has its own dedicated troubleshooting entries)

---

Severity-Categorized Findings

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

No blockers were identified. A Claude Code user can successfully install, configure, and run workflows using engine: claude following the current documentation.

⚠️ Major Obstacles (Score: 5/10)

Obstacle 1: Architecture Diagram Labels Container as "Copilot CLI"

Impact: Creates false impression that the AWF security architecture is Copilot-specific

Current State: architecture.mdx lines 181 and 252 in Mermaid diagrams:

COPILOT["Copilot CLI"]
...
AGENT["Agent container\nCopilot CLI + MCP client\n172.30.0.20"]

Why It's Problematic: A Claude user reading the security architecture (which they should read before deploying) sees "Copilot CLI" as the agent. This creates confusion about whether the documented security model applies to their Claude-based workflow.

Suggested Fix: Change labels to generic "Agent CLI" or "AI Engine (Copilot/Claude/Codex)"

Affected Files: docs/src/content/docs/introduction/architecture.mdx lines 181, 252

Obstacle 2: "Start with Copilot" Recommendation Without Claude Alternative

Impact: Claude users feel directed away from their preferred tool

Current State: engines.md line 27: "Copilot is the default choice for most users... If you are unsure, start with Copilot and switch later."

Why It's Problematic: This reads as a directive to use Copilot. The guidance for Claude users is tucked into a single clause: "Choose Claude when you want stronger control over turn limits" — framing Claude as a niche choice rather than a fully supported primary engine.

Suggested Fix: Add parallel guidance: "Choose Claude if you use Claude Code, prefer Anthropic models, or want strong per-run turn budget control via max-turns."

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

Obstacle 3: Documentation Examples Heavily Weighted Toward Copilot

Impact: Claude users must constantly translate examples

Current State: Analysis of documentation source files:

• engine: copilot appears 71 times across docs
• engine: claude appears 7 times across docs

Why It's Problematic: Nearly every code snippet a Claude user encounters will show engine: copilot. While changing it is trivial, it signals that Copilot is the assumed baseline, not Claude.

Suggested Fix: Rotate some examples to use engine: claude or show generic multi-engine examples. Priority: architecture.mdx, network.md, and reference/sandbox.md.

Affected Files: Multiple — highest priority: docs/src/content/docs/introduction/architecture.mdx, docs/src/content/docs/reference/sandbox.md, docs/src/content/docs/reference/network.md

💡 Minor Confusion Points (Score: 3/10)

• Issue 1: CLAUDE_CODE_OAUTH_TOKEN clarification is buried in auth.mdx — A Claude Code user's first instinct is to use their Claude Code OAuth token. The note that this is unsupported (only ANTHROPIC_API_KEY works) exists but is at line 121 of auth.mdx, not surfaced in the Quick Start or engines page.

• Issue 2: engines.md table shows Claude engine as "Claude by Anthropic (Claude Code)" linking to anthropic.com/index/claude, but Claude Code users know Claude Code as a CLI tool — the link to a general Claude page may confuse them about whether they need the API key (yes) or the Claude Code CLI credentials (no).

• Issue 3: The threat-detection.md examples (lines 163, 241, 286) use engine: copilot in detection configuration examples without Claude alternatives shown.

• Issue 4: There is no "Claude-first" workflow template in gh aw new suggestions — the default template in cli.md (line 191) shows engine: claude in that specific example, which is good, but the wizard flow defaults to asking users to choose rather than pre-setting Claude.

• Issue 5: The how-they-work.mdx section on AI Engines says "Workflows support GitHub Copilot (default), Claude by Anthropic, Codex, and Gemini" — the parenthetical (default) after Copilot gives subtle primacy without explanation for non-Copilot users.

---

Engine Comparison Analysis

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

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

Note: Claude scores well overall but lags Copilot primarily on example density.

---

Tool Availability Analysis

Engine-Agnostic Tools (work with Claude):

• edit:, bash:, github:, web-fetch:, playwright:
• cache-memory:, repo-memory:, qmd:
• agentic-workflows:, custom MCP servers
• All Safe Outputs operations

Copilot-Only Tools:

• engine.agent (custom Copilot agent files)
• engine.harness (custom harness script)
• max-continuations (autopilot multi-run mode)

Claude-Exclusive:

• max-turns (per-run AI iteration budget) — actually superior for controlled executions

Unclear/Undocumented:

• Web search via MCP for Claude — tools.md notes "Some engines require third-party MCP servers for web search" but doesn't specify which MCP server to use for Claude users

---

Authentication Requirements

Quick Start guide covers authentication for:

• ✅ Copilot — detailed instructions with link to PAT creation
• ✅ Claude — ANTHROPIC_API_KEY with link to Anthropic Console
• ✅ Codex — OPENAI_API_KEY with platform.openai.com link
• ✅ Gemini — GEMINI_API_KEY with aistudio.google.com link

Missing for Claude Users:

• No early warning in Quick Start that CLAUDE_CODE_OAUTH_TOKEN doesn't work (only in auth reference)
• No "Claude Code users" note explaining that the API key from console.anthropic.com is different from their Claude Code session

Secret Names Documented:

• Copilot: COPILOT_GITHUB_TOKEN ✅
• Claude: ANTHROPIC_API_KEY ✅
• Codex: OPENAI_API_KEY / CODEX_API_KEY ✅
• Gemini: GEMINI_API_KEY ✅

---

Example Workflow Analysis

Workflow Count by Engine (in .github/workflows/):

Engine: copilot  → 89 workflows
Engine: claude   → 47 workflows
Engine: codex    → 11 workflows
Engine: gemini   →  0 workflows (not counted)

Assessment: 47 Claude workflows is a strong showing — there are real, production-quality examples to learn from. However, Copilot still has nearly 2× the examples, which reinforces its positioning as the primary engine.

Claude Examples Quality: The Claude workflows present (e.g., ci-doctor.md, audit-workflows.md, aw-failure-investigator.md) are high-quality and demonstrate the engine fully. A Claude user can find good role models.

---

Recommended Actions

Priority 1: Critical Documentation Fixes

1. Fix architecture diagrams to use generic agent labels — Change "Copilot CLI" labels in AWF diagrams to "Agent CLI" or "AI Engine" — File: docs/src/content/docs/introduction/architecture.mdx lines 181, 252

2. Add Claude advocate language to engine selection guidance — Add a parallel recommendation in the "Which engine should I choose?" section for users who prefer Claude Code — File: docs/src/content/docs/reference/engines.md line 27

3. Add CLAUDE_CODE_OAUTH_TOKEN warning to Quick Start — Add a callout in the Quick Start auth step noting that Claude Code OAuth tokens don't work; ANTHROPIC_API_KEY is required — File: docs/src/content/docs/setup/quick-start.mdx

Priority 2: Major Improvements

1. Rotate some code examples to use engine: claude — Replace a portion of engine: copilot examples in architecture, sandbox, and network docs with Claude examples — Files: architecture.mdx, sandbox.md, network.md

2. Add web search MCP server recommendation for Claude — The tools doc mentions MCP for web search but doesn't name the MCP server for Claude users — File: docs/src/content/docs/reference/tools.md line 65

3. Create a "Claude users" note in how-they-work.mdx — A short callout for non-Copilot users explaining that engine: defaults to Copilot and they should add engine: claude — File: docs/src/content/docs/introduction/how-they-work.mdx

Priority 3: Nice-to-Have Enhancements

1. Add "Getting Started with Claude" guide — A dedicated quick path for Claude Code users mirroring the default quick start
2. Add more engine: claude examples in reference docs — Especially in threat-detection.md examples
3. Link Claude engine entry to Claude Code docs — The engines table links to anthropic.com/index/claude; a link to the Claude Code CLI docs would be more relevant for gh-aw users

---

Positive Findings

What Works Well for Claude Code Users:

• ✅ Prerequisites in Quick Start explicitly list Claude as a valid engine option (not an afterthought)
• ✅ add-wizard interactive engine selection includes Claude with correct secret name
• ✅ Auth documentation provides dedicated, complete setup for ANTHROPIC_API_KEY
• ✅ 47 Claude engine workflow examples in the repo (substantial real-world reference)
• ✅ Feature comparison table is clear and honest about per-engine capabilities
• ✅ CLAUDE_CODE_OAUTH_TOKEN explicitly documented as unsupported (prevents a common mistake)
• ✅ max-turns documented as Claude-specific feature with clear examples
• ✅ gh aw new --engine claude command creates Claude-first workflow templates
• ✅ gh aw secrets bootstrap --engine claude validates Claude API key before upload
• ✅ Troubleshooting auth errors covers Claude 401/403 cases explicitly

---

Conclusion

Can Claude Code Users Successfully Adopt gh-aw?

Answer: Yes, with minor friction

The documentation contains all the information a Claude Code user needs to successfully adopt gh-aw. Authentication is documented, features are compared honestly, and there are ~47 Claude workflow examples to learn from. The Quick Start even lists Claude as a first-class option in prerequisites.

The friction comes from the structural default toward Copilot: 71 documentation examples use engine: copilot vs 7 for Claude; the primary engine recommendation says "start with Copilot"; architecture diagrams show "Copilot CLI." None of this is a blocker, but it creates a cumulative impression that Claude is a supported but secondary option.

A Claude Code user who reads carefully will succeed. One who skims may get confused or feel unwelcome.

Overall Assessment Score: 7/10

Breakdown:

• Clarity for non-Copilot users: 6/10
• Claude engine documentation: 7/10
• Alternative approaches provided: 8/10
• Engine parity (feature + docs): 7/10

Next Steps

Fix the architecture diagram labels (Priority 1, low effort), add a Claude advocate sentence to the engine selection guide (Priority 1, trivial), and add the CLAUDE_CODE_OAUTH_TOKEN warning to Quick Start (Priority 1, low effort). These three changes would meaningfully improve the Claude user experience with minimal authoring effort.

---

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
• .github/workflows/*.md (engine distribution analysis)
• docs/src/content/docs/reference/ (grep analysis for engine occurrences)

---

References:

• §25111083828

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

• expires on Apr 30, 2026, 1:22 PM UTC