🔍 Claude Code User Documentation Review - 2026-04-01

[github-actions[bot]]

Executive Summary

As a developer who uses Claude Code and actively avoids GitHub Copilot, I reviewed the gh-aw documentation to assess whether I could successfully understand and adopt this tool. The good news: Claude is a first-class citizen in gh-aw, with dedicated documentation in engines.md, authentication instructions, version pinning, and custom endpoint support. The interactive add-wizard onboarding explicitly offers Claude as an engine choice. However, there are several friction points: the default engine is Copilot, architecture diagrams name "Copilot CLI" as the agent, no actual example workflow files use engine: claude, and some documentation sections inadvertently use Copilot-centric framing.

Key Finding: Claude Code users can successfully use gh-aw, but will encounter confusion from Copilot-centric defaults and diagrams — particularly if they explore the codebase for examples or follow the architecture diagrams.

---

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?

Short answer: Yes, with some friction. The prerequisites in the Quick Start explicitly list Anthropic Claude as an AI account option alongside Copilot. The gh aw add-wizard command guides through engine selection interactively, which is excellent for first-time users. However, the README itself gives no hint about engine choices — it simply links to the Quick Start without any engine context.

Specific Issues Found:

• README.md — No engine overview in the summary: The README describes gh-aw as "Write agentic workflows in natural language markdown" without ever mentioning that you can use Claude, Copilot, or Codex. A user skimming the README before installing could assume Copilot is required, especially given the GitHub branding.

• how-they-work.mdx — Engines mentioned but Copilot-first: "Workflows support GitHub Copilot (default), Claude by Anthropic, and Codex." This is accurate but buries Claude behind the default. A non-Copilot user reading this might wonder if they're a second-class citizen.

• Quick Start Step 2 is well designed — the wizard handles engine selection, including Claude and Codex. No blocker here.

Recommended Fixes:

• Add a one-liner to the README overview mentioning multiple AI engines: "Works with GitHub Copilot, Claude by Anthropic, OpenAI Codex, and Google Gemini."
• Change "GitHub Copilot (default)" phrasing in how-they-work.mdx to something like "multiple AI engines (GitHub Copilot, Claude, Codex, Gemini) — Copilot is the default if unspecified."

---

Question 2: Inaccessible Features for Non-Copilot Users

What features or steps don't work without Copilot?

Features That Require Copilot:

• engine.agent (custom agent files) — The .github/agents/ custom agent mechanism is Copilot-only. Documented clearly in engines.md with engine.agent: ❌ for Claude/Codex/Gemini. However, Claude Code users who hear about "custom agents" and expect a parallel mechanism will find none.
• max-continuations (autopilot mode — multiple consecutive runs) — Copilot-only. Claude offers max-turns instead (limits per-run chat iterations), but there is no Claude equivalent of running the workflow autonomously multiple times in sequence.
• engine: copilot implicit default — Workflows without an explicit engine: field silently default to Copilot. If a Claude user copies a community workflow that omits engine:, it will attempt to use Copilot rather than Claude.

Features That Work Without Copilot (engine-agnostic):

• All tools: — edit, github, bash, web-fetch, playwright, cache-memory, repo-memory, qmd
• All safe-outputs (create_issue, add_comment, create_pull_request)
• All MCP server integrations (mcp-servers:)
• All security features (AWF, threat detection, content sanitization, secret redaction)
• engine.api-target and ANTHROPIC_BASE_URL custom endpoint routing
• Version pinning (engine.id: claude, version: "2.1.70")
• max-turns (Claude-specific feature, documented)

Missing Documentation:

• No dedicated "Getting Started with Claude" guide. Copilot has a dedicated copilot-custom-agents.md reference page. Claude has no equivalent guide beyond engines.md.
• No documentation explaining what max-turns does differently vs max-continuations and how a Claude user should architect long-running workflows differently.

---

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 (AWF) diagram has a node labeled COPILOT["Copilot CLI"] as the example agent, alongside "WebFetch Tool" and "WebSearch Tool". This visually implies the system is built around Copilot. A Claude user could incorrectly conclude AWF only works with Copilot.

• File: docs/src/content/docs/introduction/architecture.mdx — The MCP Gateway diagram shows AGENT["Agent container\nCopilot CLI + MCP client\n172.30.0.20"]. Again, hardcodes Copilot as the agent in a diagram intended to explain generic architecture.

• File: docs/src/content/docs/reference/engines.md — The Extended Configuration example block uses engine: copilot / id: copilot as the primary example. While this is just a YAML example, all 6 of the args, command, env, and api-target examples default to showing the Copilot engine, with Claude/Codex variants only appearing in dedicated subsections.

• .github/workflows/ci.yml — The project's own CI workflow uses engine: copilot, meaning the repo "eats its own dogfood" but only with Copilot.

Missing Alternative Instructions:

• No explanation of how to migrate an existing Copilot workflow to Claude (e.g., change engine: copilot → engine: claude, swap COPILOT_GITHUB_TOKEN → ANTHROPIC_API_KEY, note max-continuations is not available).
• No "engine selection guide" explaining which engine to choose for different use cases.

---

Severity-Categorized Findings

🚫 Critical Blockers (Score: 1/10)

No genuine critical blockers found

Claude users can get started without Copilot. The add-wizard command explicitly asks for engine choice. Authentication for Claude (ANTHROPIC_API_KEY) is documented in engines.md, tokens.md, faq.md, and cost-management.md. There are no steps in the Quick Start that fail without Copilot.

Score rationale: 1/10 means "essentially no blockers" — the documentation gives Claude users a viable path.

⚠️ Major Obstacles (Score: 5/10)

Obstacle 1: Architecture Diagrams Hard-Code "Copilot CLI"

Impact: Confusion about whether AWF and MCP Gateway work with Claude

Current State: architecture.mdx contains Mermaid diagrams where the agent node is literally labeled COPILOT["Copilot CLI"]. One diagram shows AGENT["Agent container\nCopilot CLI + MCP client\n172.30.0.20"].

Why It's Problematic: A Claude Code user reading the security architecture section — which is important for understanding the security model — will see "Copilot CLI" as the agent and may conclude that the security architecture only applies to Copilot. This is not true; Claude runs in the same AWF container.

Suggested Fix: Change diagram nodes to use engine-neutral labels: AGENT["AI Agent\n(Claude/Copilot/Codex)\n172.30.0.20"] and ENGINE["AI Engine\n(Copilot, Claude, Codex)"].

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

Obstacle 2: Zero Example Workflows Using Claude Engine

Impact: No working examples for Claude users to copy-paste or learn from

Current State: Searching .github/workflows/ for engine: claude returns zero results. The CI uses engine: copilot. There are no .md or .yml workflow files in the repo demonstrating a Claude-engine workflow.

Why It's Problematic: When developers learn by example, they look at the repository's own workflows. Finding zero Claude examples — while the project's own CI uses Copilot — sends a subtle signal that Copilot is the "real" engine and Claude is an afterthought.

Suggested Fix: Add at least one example workflow in the docs or .github/workflows/ using engine: claude to demonstrate the pattern. The documentation examples/ directory could include a daily-repo-status-claude.md variant.

Affected Files: .github/workflows/ (no Claude examples exist)

Obstacle 3: Copilot Default Without Prominent Warning

Impact: Silent engine mismatch when copying community workflows

Current State: engines.md states "Copilot CLI is the default — engine: can be omitted when using Copilot." The feature comparison table shows Copilot as the first column with most features marked supported.

Why It's Problematic: If a Claude user copies a community workflow that omits the engine: field, it will silently attempt to use Copilot and fail (missing COPILOT_GITHUB_TOKEN). The error message they'll get won't intuitively guide them to add engine: claude.

Suggested Fix: Add a callout in engines.md and in the frontmatter reference: "⚠️ If you don't use Copilot, always specify engine: in your workflow frontmatter — omitting it defaults to Copilot CLI."

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

Obstacle 4: No Claude-Specific Getting-Started Guide

Impact: Asymmetric documentation depth — Copilot has a dedicated custom agents page, Claude does not

Current State: copilot-custom-agents.md is a dedicated reference page for the Copilot engine.agent feature. Claude has no equivalent landing page. Claude-specific features (max-turns, ANTHROPIC_BASE_URL) are scattered in engines.md.

Why It's Problematic: A Claude Code user who wants to understand all their options has to search across multiple reference pages. There's no "Using Claude with gh-aw" guide they can follow.

Suggested Fix: Create a docs/src/content/docs/guides/claude.md page covering: setting engine: claude, obtaining ANTHROPIC_API_KEY, using max-turns, setting a custom ANTHROPIC_BASE_URL, and noting the feature differences from Copilot.

Affected Files: docs/src/content/docs/guides/ (file doesn't exist)

💡 Minor Confusion Points (Score: 5/10)

• No "Choose your engine" guidance: The docs don't explain when to choose Claude vs Copilot vs Codex. A user who just wants to use Claude doesn't know if they're missing features. File: docs/src/content/docs/reference/engines.md
• max-turns description is Claude-only but not celebrated: The feature table shows max-turns: ✅ for Claude as a differentiator. This is a Claude advantage, but there's no callout highlighting it as a reason to choose Claude. File: engines.md
• Quick Start video likely shows Copilot: The video install-and-add-workflow-in-cli.mp4 is probably a Copilot demo. No text description indicates which engine is being shown. File: docs/src/content/docs/setup/quick-start.mdx
• FAQ answers may be Copilot-centric: Without reading all FAQ entries, there's a risk that troubleshooting answers assume Copilot setup. File: docs/src/content/docs/reference/faq.md
• No comparison of AI output quality between engines: Developers choosing between Claude and Copilot would benefit from real-world guidance. No such guidance exists.

---

Engine Comparison Analysis

Available Engines

Based on my review, gh-aw supports four engines with dedicated documentation:

• engine: copilot — Default. Extensively documented, custom agents, max-continuations, most examples.
• engine: claude — Well documented in engines.md, tokens.md, faq.md. max-turns unique advantage.
• engine: codex — Documented. web-search opt-in is the key difference.
• engine: gemini — Listed in the comparison table. Least documentation coverage.

Documentation Quality by Engine

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

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

---

Tool Availability Analysis

Tools Review

Engine-Agnostic Tools (all engines):

• tools.edit — File editing
• tools.github — GitHub API operations (toolsets, remote/local)
• tools.bash — Shell command execution
• tools.web-fetch — Web content fetching
• tools.playwright — Browser automation
• tools.cache-memory — Persistent memory across runs
• tools.repo-memory — Repository-specific memory
• tools.qmd — Vector search over documentation
• tools.agentic-workflows — Workflow introspection
• mcp-servers: — All custom MCP server integrations

Engine-Specific Tools:

• tools.web-search — Available for all engines but: Codex requires explicit opt-in; other engines use MCP server
• engine.agent — Copilot-only (custom agent files in .github/agents/)
• max-continuations — Copilot-only
• max-turns — Claude-only

Unclear/Undocumented:

• Whether third-party MCP servers for web-search work identically across all engines
• Whether the agentic-workflows: introspection tool behaves consistently across engines

---

Authentication Requirements

Current Documentation

Quick Start guide covers authentication for:

• ✅ Copilot (detailed instructions, COPILOT_GITHUB_TOKEN with fine-grained PAT requirements)
• ✅ Claude (documented in engines.md, tokens.md: ANTHROPIC_API_KEY)
• ✅ Codex (documented: OPENAI_API_KEY)
• ✅ Gemini (documented: GEMINI_API_KEY)

Missing for Claude Users

• How to obtain ANTHROPIC_API_KEY: The docs link to engines.md and the auth reference but don't include a direct link to console.anthropic.com for key generation. Copilot setup instructions typically include a direct link to the settings page.
• Billing information: cost-management.md covers Claude billing but it's not prominently linked from the Quick Start.
• OAuth note: faq.md correctly states OAuth is not supported for Claude (only ANTHROPIC_API_KEY) — but this is buried in the FAQ rather than in a prominent note in the Quick Start.

Secret Names

• Copilot: COPILOT_GITHUB_TOKEN (documented extensively, 10+ files)
• Claude: ANTHROPIC_API_KEY (documented in 8 files including primary references)
• Codex: OPENAI_API_KEY (documented)
• Gemini: GEMINI_API_KEY (documented)

---

Example Workflow Analysis

Workflow Count by Engine

Engine: copilot - at least 1 workflow found (.github/workflows/ci.yml)
Engine: claude  - 0 workflows found
Engine: codex   - 0 workflows found
Engine: gemini  - 0 workflows found

Quality of Examples

Copilot Examples:
The project's own CI (ci.yml) uses engine: copilot. This is the only concrete workflow example in the repo itself, and it reinforces Copilot as the "official" engine.

Claude Examples:
None exist in .github/workflows/. The engines.md reference page has YAML snippets showing engine.id: claude for version pinning and ANTHROPIC_BASE_URL routing, but these are configuration fragments, not complete runnable workflows. A developer wanting to validate that Claude works end-to-end has no reference implementation.

---

Recommended Actions

Priority 1: Critical Documentation Fixes

1. Fix architecture diagrams to remove Copilot-specific labels — Change "Copilot CLI" in AWF/MCP Gateway diagrams to "AI Agent (Claude/Copilot/Codex/Gemini)". File: docs/src/content/docs/introduction/architecture.mdx
2. Add engine: default warning in frontmatter and engines docs — Warn Claude/Codex users that omitting engine: defaults to Copilot. Files: docs/src/content/docs/reference/engines.md, docs/src/content/docs/reference/frontmatter.md
3. Add at least one Claude engine example workflow — Either in .github/workflows/ or docs/src/content/docs/examples/. This is the highest-leverage fix for Claude user confidence.

Priority 2: Major Improvements

1. Create a "Using Claude with gh-aw" guide — Cover setup, ANTHROPIC_API_KEY, max-turns, ANTHROPIC_BASE_URL, and a working example. Target file: docs/src/content/docs/guides/claude.md
2. Add a direct link to Anthropic API key creation in the authentication documentation — Similar to how Copilot docs link to GitHub settings pages. File: docs/src/content/docs/reference/tokens.md
3. Update the README to mention multi-engine support — One sentence in the overview mentioning Claude, Codex, Gemini as alternatives to Copilot. File: README.md

Priority 3: Nice-to-Have Enhancements

1. Add an "engine selection guide" explaining tradeoffs between engines (cost, capabilities, use cases). Currently there's feature comparison but no guidance on which to choose.
2. Document a Copilot → Claude migration path — A brief section in engines.md showing what to change when switching from Copilot to Claude.
3. Highlight Claude's max-turns as a differentiating feature in the Quick Start or overview docs, rather than only noting it in the feature comparison table footnote.
4. Update the CI/CD workflow to optionally include a Claude-engine run alongside the Copilot run, demonstrating dual-engine capability.

---

Positive Findings

What Works Well

• ✅ engines.md is comprehensive and accurate — All four engines documented with feature comparison table, version pinning, custom endpoints, and env vars. This is excellent reference material.
• ✅ add-wizard handles multi-engine onboarding — The interactive wizard explicitly asks which engine to use and configures the correct secret. Claude Code users who use this path will have a smooth experience.
• ✅ ANTHROPIC_API_KEY is documented in 8 files — Authentication for Claude is not hidden or undocumented.
• ✅ max-turns is documented as Claude-specific — The feature comparison table correctly identifies Claude differentiators.
• ✅ Custom endpoint support for Claude — ANTHROPIC_BASE_URL and api-target for Claude proxies is documented, which is important for enterprise users.
• ✅ Tools are genuinely engine-agnostic — All major tools (playwright, cache-memory, github, bash, web-fetch, MCP servers) work with any engine.
• ✅ Security architecture applies equally to all engines — AWF, threat detection, SafeOutputs all work regardless of engine choice.
• ✅ Version pinning for Claude is documented — engine: id: claude, version: "2.1.70" example is present.

---

Conclusion

Can Claude Code Users Successfully Adopt gh-aw?

Answer: Yes, With Minor Effort

Reasoning: The core functionality — installing gh-aw, adding a workflow, selecting Claude as the engine, setting ANTHROPIC_API_KEY, and running the workflow — is fully documented and accessible. The add-wizard interactive onboarding is the smoothest path and works well for Claude users. The engines.md reference page is thorough. No step in the documented process is genuinely blocked for Claude users.

The friction comes from implicit Copilot-centricity: architecture diagrams that name "Copilot CLI" as the agent, zero example workflows using Claude, a CI pipeline that uses Copilot, and a README that doesn't mention multi-engine support. These create doubt and confusion for a Claude Code user exploring the repository, even though the actual feature support is solid.

Overall Assessment Score: 7/10

Breakdown:

• Clarity for non-Copilot users: 6/10 (diagrams and defaults are Copilot-centric)
• Claude engine documentation: 8/10 (engines.md is solid; missing a dedicated guide)
• Alternative approaches provided: 7/10 (alternatives documented but not prominently)
• Engine parity: 7/10 (most tools work; max-continuations and custom agents are notable gaps)

Next Steps

The highest-value improvement is adding one working Claude engine example workflow. This single change would validate Claude support in a way that documentation alone cannot. Following that, fixing the architecture diagrams to be engine-neutral and adding a "Using Claude" guide would complete the documentation story for Claude Code users.

---

Appendix: Files Reviewed

Complete List of Documentation Files Analyzed

• README.md
• docs/src/content/docs/setup/quick-start.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/setup/cli.md
• docs/src/content/docs/reference/engines.md (additional)
• .github/workflows/ci.yml (engine usage grep)
• Cross-referenced: tokens.md, faq.md, cost-management.md (via search results)

---

References:

• §23850453751

AI generated by Claude Code User Documentation Review · history

• expires on Apr 2, 2026, 1:23 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 #24112.