🔍 Claude Code User Documentation Review - 2026-03-25

[github-actions[bot]]

Executive Summary

As a developer who uses Claude Code and actively avoids GitHub Copilot, I reviewed the core gh-aw documentation to assess whether it is accessible and actionable for non-Copilot users. The overall picture is positive: Claude is treated as a first-class engine, authentication is clearly documented, and a meaningful set of workflow examples (34 of 178) use Claude. However, several issues create Copilot-centric impressions — most notably in the architecture diagrams, the how-they-work.mdx introduction, and the README — that could cause early-stage confusion.

Key Finding: Claude Code users can successfully adopt gh-aw, but will encounter minor friction from Copilot-centric wording and incomplete engine parity documentation in a few key places.

---

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

The Quick Start guide (quick-start.mdx) is the strongest point: prerequisites immediately list Anthropic Claude alongside GitHub Copilot and OpenAI Codex. Step 2 of the wizard explicitly says "Select an AI Engine — Choose between Copilot, Claude, or Codex," and the corresponding secret names (ANTHROPIC_API_KEY, OPENAI_API_KEY, COPILOT_GITHUB_TOKEN) are all called out.

However, the README and how-they-work.mdx — the first two documents many users encounter — do not convey this multi-engine support clearly.

Specific Issues Found:

• README (README.md, entire Overview section): Zero mention of Claude, Codex, or any engine alternatives. A developer landing here first will have no idea that non-Copilot options exist before clicking into deeper docs.
• how-they-work.mdx, line 26: "Workflows support GitHub Copilot (default), Claude by Anthropic, and Codex." Gemini is now documented in engines.md as a supported engine but is completely absent from this introduction page.
• how-they-work.mdx, line 27: Copilot is labeled the default without explaining what that means practically (i.e., that engine: can simply be set to claude to switch).

Recommended Fixes:

• Add a one-liner to the README Overview: "Supports GitHub Copilot, Claude (Anthropic), Codex (OpenAI), and Gemini as AI engines."
• Update how-they-work.mdx to mention Gemini alongside the other three engines.
• Add a sentence in how-they-work.mdx clarifying that non-Copilot engines are equally supported and just need a different secret.

---

Question 2: Inaccessible Features for Non-Copilot Users

What features or steps don't work without Copilot?

Features That Require Copilot (or are Copilot-only):

Feature	Location	Impact
engine.agent (custom agent files, .github/agents/)	engines.md, feature table	Custom Copilot-specific behavior profiles; no Claude equivalent documented
max-continuations (autopilot multi-run mode)	engines.md, feature table	Autopilot consecutive-run feature; no Claude equivalent available
COPILOT_GITHUB_TOKEN PAT requirement	auth.mdx	Must use PAT; no GitHub App option (explicitly noted in auth.mdx)

Features That Work Without Copilot (engine-agnostic):

• All core tools: edit:, bash:, github:, web-fetch:, playwright:, cache-memory:, repo-memory:, qmd:, agentic-workflows:
• All safe-outputs operations (create-issue, add-comment, create-pull-request, etc.)
• All MCP server integrations
• All CLI commands including gh aw init, gh aw compile, gh aw run, gh aw trial, gh aw logs, gh aw audit
• max-turns is actually Claude-only (a Claude advantage over other engines)
• api-target and ANTHROPIC_BASE_URL work for Claude

Missing Documentation:

• No guide explaining what to use instead of engine.agent for Claude users who want custom behavior profiles (the answer appears to be: write detailed system context in the workflow markdown itself, but this isn't stated).

---

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, line 181 — The AWF diagram renders a box labeled COPILOT["Copilot CLI"] inside the "AI Agent Process" subgraph, hardcoding Copilot as the canonical agent in a security architecture diagram that applies to all engines.
• File: docs/src/content/docs/introduction/architecture.mdx, line 252 — The MCP Gateway diagram shows AGENT["Agent container\nCopilot CLI + MCP client\n172.30.0.20"], reinforcing a Copilot-specific mental model of the container architecture.
• File: docs/src/content/docs/reference/auth.mdx, lines 47-49 — The CLI example under "Adding secrets using the CLI" shows only COPILOT_GITHUB_TOKEN as the example, before the reader reaches the individual engine sections.

Missing Alternative Instructions:

• No "Getting Started with Claude" landing page or guide specifically for Claude users (contrast: there is a dedicated Copilot Custom Configuration section in engines.md).
• No explanation of what replaces engine.agent for Claude workflows.

---

Severity-Categorized Findings

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

No critical blockers were identified. Claude users can complete the full quick-start guide without a Copilot subscription.

---

⚠️ Major Obstacles (Score: 3/10)

Obstacle 1: Architecture Diagrams Are Copilot-Specific

Impact: A Claude Code user reading the security architecture page will see "Copilot CLI" hardcoded in all network/container diagrams, undermining confidence that gh-aw works properly with Claude.

Current State: architecture.mdx lines 181 and 252 render "Copilot CLI" as a named node inside the agent container and firewall diagrams. The configuration example beneath the firewall diagram also uses engine: copilot without a note that other engines apply the same pattern.

Why It's Problematic: Security architecture is important for enterprise evaluation. A diagram labeling the agent as "Copilot CLI" when you're using Claude creates doubt about whether the documented safeguards actually apply.

Suggested Fix: Replace COPILOT["Copilot CLI"] with ENGINE["AI Engine\n(Copilot / Claude / Codex / Gemini)"] and update the MCP Gateway diagram to use generic AGENT["Agent container\nAI Engine + MCP client"] language. Add a note under the configuration example: "Replace engine: copilot with engine: claude, codex, or gemini depending on your chosen AI engine."

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

Obstacle 2: README Has Zero Non-Copilot Visibility

Impact: The README is the entry point for most developers discovering gh-aw. It mentions Copilot implicitly (via the "Guardrails" section referencing Copilot-specific links in the community section) but never mentions Claude, Codex, or multi-engine support anywhere in the prose sections.

Current State: The README sections Overview, Guardrails, and Documentation contain no mention of supported AI engines. A developer who does not use Copilot reading only the README would have no indication this tool is relevant to them.

Suggested Fix: Add to the Overview section: "gh-aw supports GitHub Copilot, Claude (Anthropic), Codex (OpenAI), and Gemini (Google) as AI engines — no Copilot subscription required to get started."

Affected Files: README.md

---

💡 Minor Confusion Points (Score: 5/10)

• Gemini omitted from intro: how-they-work.mdx lists "GitHub Copilot, Claude by Anthropic, and Codex" but engines.md now documents Gemini as a 4th engine. File: docs/src/content/docs/introduction/how-they-work.mdx
• "default" language without clarification: engines.md and how-they-work.mdx say Copilot is the "default" without clarifying that the default only applies when engine: is omitted — which implies Copilot is preferred or better. File: docs/src/content/docs/reference/engines.md, how-they-work.mdx
• Auth CLI example is Copilot-first: auth.mdx CLI example snippet under "Adding secrets using the CLI" shows COPILOT_GITHUB_TOKEN as the only example before explaining other options exist. File: docs/src/content/docs/reference/auth.mdx, line 48
• No "what replaces engine.agent?" explanation for Claude: Copilot has a dedicated Copilot Custom Configuration section and a link to "Copilot Agent Files". Claude users wanting equivalent custom-prompt behavior have no comparable guide. File: docs/src/content/docs/reference/engines.md
• max-continuations listed only as Copilot-only without explaining Claude's alternative approach to extended agentic runs (max-turns). The docs note them in the table but don't explain the conceptual difference. File: docs/src/content/docs/reference/engines.md

---

Engine Comparison Analysis

Available Engines

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

Engine	Setup Docs	Examples	Auth Docs	Overall Score
Copilot	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐ (85 workflows)	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐
Claude	⭐⭐⭐⭐	⭐⭐⭐⭐ (34 workflows)	⭐⭐⭐⭐⭐	⭐⭐⭐⭐
Codex	⭐⭐⭐⭐	⭐⭐⭐ (17 workflows)	⭐⭐⭐⭐	⭐⭐⭐
Gemini	⭐⭐⭐	⭐ (0 workflows in repo)	⭐⭐⭐⭐	⭐⭐

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

Notes on Claude's score: Claude setup docs in auth.mdx are clear and complete. The -1 star from perfect comes from the missing "custom agent equivalent" guide and the architecture diagram issue. Claude is a genuinely well-supported second option.

---

Tool Availability Analysis

Engine-Agnostic Tools (work with any engine):

• edit: — file editing
• github: — GitHub API toolsets
• bash: — shell commands
• web-fetch: — web content fetching
• playwright: — browser automation
• cache-memory: — persistent cross-run memory
• repo-memory: — repository-scoped memory
• qmd: — documentation vector search
• agentic-workflows: — workflow introspection
• All mcp-servers: custom integrations

Engine-Specific Tools/Features:

• engine.agent — Copilot only (custom agent files)
• max-continuations — Copilot only (autopilot multi-run)
• max-turns — Claude only (iteration limit per run)
• web-search: — Codex has native support; others require MCP

Unclear/Undocumented:

• Whether Claude Code's native file editing behavior differs from Copilot CLI's file editing in ways that affect the edit: tool configuration

---

Authentication Requirements

Current Documentation

Quick Start guide covers authentication for:

• ✅ Copilot (COPILOT_GITHUB_TOKEN) — detailed instructions with deep-link to PAT creation
• ✅ Claude (ANTHROPIC_API_KEY) — clear instructions with link to platform.claude.com
• ✅ Codex (OPENAI_API_KEY) — clear instructions with link to platform.openai.com
• ✅ Gemini (GEMINI_API_KEY) — clear instructions with link to aistudio.google.com

Missing for Claude Users

• Link to platform.claude.com/docs/en/get-started in auth docs currently has a generic URL that could be more specific (e.g., directly to API key creation)
• No mention of Claude API pricing tier requirements (free vs. paid) that may affect workflow viability at scale

Secret Names

Engine	Secret Name	Notes
Copilot	COPILOT_GITHUB_TOKEN	PAT only, must be user account, needs Copilot license
Claude	ANTHROPIC_API_KEY	Standard API key from Anthropic Console
Codex	OPENAI_API_KEY	Standard API key from OpenAI
Gemini	GEMINI_API_KEY	API key from Google AI Studio

All four are well-documented in auth.mdx.

---

Example Workflow Analysis

Workflow Count by Engine

Engine: copilot  — 85 workflows (48%)
Engine: claude   — 34 workflows (19%)
Engine: codex    — 17 workflows (10%)
Engine: gemini   —  0 workflows  (0%)
Engine: (default/none) — ~42 workflows (23%, resolve to Copilot default)
Total: 178 workflow files

Quality of Examples

Copilot Examples:
Extensive and varied. 85 explicit Copilot workflows cover a wide range of use cases from PR triage to security scanning to automated daily reports.

Claude Examples:
34 workflows is a solid set. However, they are not surfaced prominently in documentation — a user reading the Quick Start would add the daily-repo-status workflow using the engine wizard, and wouldn't know to look at these examples. Adding a "Claude Engine Cookbook" or similar page linking to key Claude workflow examples would significantly improve discoverability.

Codex Examples:
17 workflows; reasonable representation. Similar discoverability issue.

Gemini Examples:
Zero workflow examples despite Gemini being documented as a supported engine in engines.md. This is a gap — at minimum, one example Gemini workflow would validate that the engine integration actually works.

---

Recommended Actions

Priority 1: Critical Documentation Fixes

1. Update architecture.mdx diagrams to be engine-agnostic — Replace "Copilot CLI" labels in the firewall and MCP gateway Mermaid diagrams with generic "AI Engine" labels. Add a note that the configuration example applies to all engines. File: docs/src/content/docs/introduction/architecture.mdx
2. Add engine options to the README — Insert a brief mention of supported engines (Copilot, Claude, Codex, Gemini) in the Overview section so the very first touchpoint communicates multi-engine support. File: README.md

Priority 2: Major Improvements

1. Update how-they-work.mdx to include Gemini — Add Gemini to the engine list in the "AI Engines" section and verify the list stays in sync with engines.md. File: docs/src/content/docs/introduction/how-they-work.mdx
2. Add a Claude-equivalent of "Custom Agent Configuration" section — Explain how Claude Code users can customize behavior (e.g., via workflow markdown content, max-turns, model selection via engine.model) in the same way Copilot users configure engine.agent. File: docs/src/content/docs/reference/engines.md
3. Add at least one Gemini example workflow — Validate and publish a simple Gemini workflow example so the engine isn't undocumented in practice. File: .github/workflows/ or engines.md

Priority 3: Nice-to-Have Enhancements

1. Add a "Claude Engine Cookbook" section or guide — Curate 3-5 best Claude workflow examples with brief descriptions of what makes them good Claude use cases (given Claude's strengths with long context, complex reasoning).
2. Clarify "default" language — Where "Copilot is the default" appears, add: "Setting engine: claude (or codex, gemini) is all that's needed to switch engines."
3. Add Claude API cost considerations — Brief note in auth docs that Claude API is pay-per-use and users should be aware of costs for frequently-triggered workflows.

---

Positive Findings

What Works Well

• ✅ Quick Start prerequisites immediately list Claude alongside Copilot — no Copilot assumption at the critical first step
• ✅ Authentication documentation is thorough for all four engines with clear setup steps and correct secret names
• ✅ Engine feature comparison table in engines.md is excellent — shows max-turns as Claude-only, max-continuations as Copilot-only, making tradeoffs clear
• ✅ CLI supports --engine claude across all relevant commands (gh aw new, gh aw run, gh aw validate, gh aw add, gh aw secrets bootstrap)
• ✅ gh aw new --engine claude generates correct Claude frontmatter automatically
• ✅ 34 real Claude workflow examples exist in the repository demonstrating production use
• ✅ The add-wizard interactive setup handles engine selection and secret configuration for all engines
• ✅ api-target and ANTHROPIC_BASE_URL for Claude proxy support is well-documented
• ✅ Security architecture (SafeOutputs, firewall) is truly engine-agnostic in implementation even if diagrams show Copilot

---

Conclusion

Can Claude Code Users Successfully Adopt gh-aw?

Answer: Yes, with modest effort

The core documentation — quick start, authentication, engines reference — provides everything a Claude Code user needs to get started. Authentication is clear, the wizard handles engine selection, and there are 34 production workflow examples using Claude. A motivated developer who follows the Quick Start guide can be running their first Claude-powered agentic workflow in under 10 minutes.

The friction points are real but shallow: the README and how-they-work.mdx introduction create an initial "is this just for Copilot users?" impression that the Quick Start then dispels. The architecture diagrams, while technically accurate, paint a Copilot-specific picture of the runtime that could cause doubt. And the absence of any Gemini examples (despite engine documentation existing) is a credibility gap.

The single biggest ROI fix is updating the two architecture diagrams from "Copilot CLI" to "AI Engine" — this is a 5-minute change that eliminates the most visually prominent Copilot-only signal in the docs.

Overall Assessment Score: 7.5/10

Breakdown:

• Clarity for non-Copilot users: 6/10 (README + architecture diagrams Copilot-centric)
• Claude engine documentation: 8/10 (auth + quick start excellent; missing custom-agent equivalent guide)
• Alternative approaches provided: 8/10 (feature table is good; just needs Gemini sync)
• Engine parity: 8/10 (most features work; max-continuations and engine.agent are real Copilot advantages)

---

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/engines.md
• docs/src/content/docs/reference/auth.mdx
• .github/workflows/*.md (178 workflow files analyzed for engine distribution)

---

References:

• §23542826056

AI generated by Claude Code User Documentation Review · history

• expires on Mar 26, 2026, 1:18 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 #23121.