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

[github-actions[bot]]

Executive Summary

I reviewed the gh-aw documentation from the perspective of a developer who uses Claude Code as their primary AI assistant and has no GitHub Copilot access. The documentation has improved substantially: authentication, tools, CLI commands, and engine configuration are all well-covered for non-Copilot users. However, several Copilot-centric patterns persist — most notably in architectural diagrams, the workflow-authoring guide, and the gh aw init description — that create friction and confusion for Claude Code users evaluating this tool.

Key Finding: Claude Code users can successfully use gh-aw, but they will encounter several documentation gaps that require them to work past Copilot-centric framing before reaching the Claude-specific instructions they need.

---

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?

Generally yes, but with friction. The Quick Start prerequisites explicitly list "Anthropic Claude" alongside Copilot and Codex — this is the first thing a new user reads and it correctly sets expectations. The add-wizard interactive command also presents engine selection early. However, subsequent documentation sections revert to Copilot-centric framing that could confuse or discourage a non-Copilot user.

Specific Issues Found:

• docs/src/content/docs/setup/creating-workflows.mdx line 20–21: The GitHub Web Interface authoring section opens with "If you have access to GitHub Copilot, you can create and edit Agentic Workflows directly from the Web Interface." This explicitly gates a major authoring path on Copilot with no alternative offered for Claude users. A new user without Copilot would feel this entire section doesn't apply to them.
• docs/src/content/docs/setup/creating-workflows.mdx lines 104–128: The gh aw init section explains the command primarily in terms of Copilot Chat benefits: registering the /agent agentic-workflows dispatcher in Copilot Chat, enabling workflow authoring via Copilot on github.com. Claude users running gh aw init won't get these benefits, and the docs don't explain what they do get (.gitattributes setup, VS Code settings).
• docs/src/content/docs/introduction/architecture.mdx line 181 and 252: The AWF firewall diagram shows COPILOT["Copilot CLI"] as the sole entry in the "AI Agent Process" box. The MCP Gateway diagram labels the agent container as "Copilot CLI + MCP client". These diagrams apply to ALL engines but mislead users into thinking only Copilot is supported at the infrastructure level.

Recommended Fixes:

• In creating-workflows.mdx: Add a note after the Copilot web interface paragraph, e.g., "If you use Claude Code, Codex, or another agent, use the VSCode/Agent section below instead."
• In creating-workflows.mdx: Rewrite the gh aw init section to describe the full set of benefits for all users, and note explicitly which parts (the dispatcher agent) are Copilot-specific.
• In architecture.mdx: Replace COPILOT["Copilot CLI"] with AGENT["AI Engine\n(Copilot CLI, Claude Code, etc.)"] and fix the MCP Gateway label similarly.

---

Question 2: Inaccessible Features for Non-Copilot Users

What features or steps don't work without Copilot?

Features That Require Copilot:

• GitHub Web Interface workflow authoring (creating-workflows.mdx line 20) — requires Copilot chat on github.com
• /agent agentic-workflows dispatcher (creating-workflows.mdx line 123) — Copilot Chat specific
• max-continuations — Copilot-only engine feature (well documented in engines.md comparison table)
• engine.agent custom agent files — Copilot-only (well documented)
• assign-to-copilot safe output — explicitly assigns to Copilot coding agent (clearly named, no confusion)
• COPILOT_GITHUB_TOKEN with GitHub App — not supported (PAT only); documented clearly

Features That Work Without Copilot:

• All core workflow execution with engine: claude, engine: codex, or engine: gemini
• All tools: edit:, bash:, github:, web-fetch:, playwright:, cache-memory:, repo-memory:, agentic-workflows:, qmd: — completely engine-agnostic
• The full Safe Outputs system (create-issue, add-comment, create-pull-request, etc.)
• All MCP server integrations
• All CLI commands (gh aw compile, gh aw run, gh aw logs, gh aw audit, etc.)
• max-turns — Claude-only but a positive feature for Claude users, not a restriction

Missing Documentation:

• No explicit table or callout box stating "These features work with any engine" at the top of the tools or quick-start docs.
• The creating-workflows.mdx "Initialize the Repository" section doesn't list what non-Copilot users actually gain from running gh aw init.

---

Question 3: Documentation Gaps and Assumptions

Where does the documentation assume Copilot usage?

Copilot-Centric Language Found In:

File	Issue
docs/src/content/docs/setup/creating-workflows.mdx line 20	Web UI authoring gated on "If you have access to GitHub Copilot"
docs/src/content/docs/setup/creating-workflows.mdx line 118	gh aw init benefits described only as Copilot Chat features
docs/src/content/docs/introduction/architecture.mdx line 181	AWF firewall diagram: COPILOT["Copilot CLI"] in the AI Agent box
docs/src/content/docs/introduction/architecture.mdx line 252	MCP gateway diagram: agent container labeled "Copilot CLI + MCP client"
docs/src/content/docs/reference/auth.mdx line 125	"See also AI Engines...for additional configuration needed when using Claude with GitHub MCP" links to engines.md#available-coding-agents — an anchor that doesn't lead to Claude+MCP-specific configuration.

Missing Alternative Instructions:

• No "Quick Start for Claude users" path or callout box: "Not using Copilot? Here's what to do instead..."
• No explicit mention that omitting engine: in a workflow defaults to Copilot (requiring COPILOT_GITHUB_TOKEN) — a silent gotcha for users who copy-paste example workflows.
• The broken/vague cross-reference in auth.mdx: "additional configuration needed when using Claude with GitHub MCP" points to the top of engines.md, which has no Claude+GitHub MCP-specific section.

---

Severity-Categorized Findings

🚫 Critical Blockers (Score: 1/10)

No true blockers exist. A Claude Code user who carefully reads the documentation can get started. The authentication page is excellent and covers Claude setup in full detail.

---

⚠️ Major Obstacles (Score: 5/10)

Obstacle 1: Architecture Diagrams Show Only "Copilot CLI"

Impact: Confusion about whether Claude/Codex actually work at the infrastructure level

Current State: architecture.mdx has two Mermaid diagrams that label engine-agnostic containers with "Copilot CLI":

• AWF firewall diagram (line 181): COPILOT["Copilot CLI"] inside the "AI Agent Process" subgraph
• MCP gateway diagram (line 252): agent container label reads "Agent container\nCopilot CLI + MCP client\n172.30.0.20"

Why It's Problematic: The architecture page is often consulted by users evaluating security and compatibility. Seeing only "Copilot CLI" in the infrastructure diagrams signals that the entire infrastructure is Copilot-specific, undermining confidence that Claude will work.

Suggested Fix: Replace "Copilot CLI" labels with "AI Engine (Copilot/Claude/Codex)" in both diagrams.

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

Obstacle 2: Creating Workflows Guide is Copilot-Gated at Entry Point

Impact: Claude Code users feel the "official" workflow authoring path is unavailable to them

Current State: The GitHub Web Interface authoring section (the first method shown) opens with: "If you have access to GitHub Copilot, you can create and edit Agentic Workflows directly from the Web Interface." No equivalent web-based authoring path for Claude users is offered. The gh aw init section describes the dispatcher agent as: "registers the agentic-workflows custom agent in GitHub Copilot and enables workflow authoring via /agent agentic-workflows in Copilot Chat on github.com". Non-Copilot users would get no authoring UX from gh aw init and would not understand what value they receive from running it.

Why It's Problematic: A Claude user reading this guide would conclude: (a) web authoring requires Copilot, (b) gh aw init doesn't benefit them. Both impressions are only partially true — gh aw init does set up .gitattributes and VS Code settings — but these benefits are buried.

Suggested Fix:

• Add a note: "Claude Code and other AI coding agents can also author workflows — see the section below."
• In the gh aw init section, add a paragraph: "Even without Copilot, gh aw init sets up .gitattributes, VS Code settings, and MCP integration so your local Claude Code or Codex agent can author workflows."

Affected Files: docs/src/content/docs/setup/creating-workflows.mdx

Obstacle 3: Broken Cross-Reference for Claude + GitHub MCP Additional Config

Impact: Users following auth docs to understand Claude + GitHub MCP requirements end up on a page that doesn't answer their question

Current State: auth.mdx line 125 states: "See also AI Engines for additional configuration needed when using Claude with GitHub MCP." The same pattern repeats for Codex (line 167) and Gemini (line 185). The anchor #available-coding-agents resolves to the comparison table at the top of engines.md, which doesn't have a Claude+GitHub MCP-specific configuration section.

Why It's Problematic: Users following this cross-reference expecting to find "additional configuration for Claude+MCP" land on a generic engine table. The actual additional configuration (needing a PAT for remote mode) is in github-tools.md, not linked from here.

Suggested Fix: Either remove the "See also" if there's nothing Claude-specific in engines.md, or link directly to the relevant github-tools.md section on remote mode authentication.

Affected Files: docs/src/content/docs/reference/auth.mdx

Obstacle 4: No Warning That Omitting `engine:` Defaults to Copilot

Impact: Claude users copying example workflows without an engine: field will get confusing authentication errors

Current State: engines.md states "Copilot CLI is the default — engine: can be omitted when using Copilot." The quick-start and other guides don't prominently warn that copy-pasting workflow snippets without setting engine: claude will require COPILOT_GITHUB_TOKEN and fail with cryptic errors for Claude users.

Why It's Problematic: Many documentation examples omit engine:. A Claude Code user who tries one of these examples will see a Copilot authentication failure with no clear indication of what went wrong.

Suggested Fix: Add a tip box in quick-start.mdx and the quick reference in how-they-work.mdx: "The default engine is Copilot. If you're using Claude, always add engine: claude to your workflow frontmatter (or use gh aw new --engine claude to auto-populate it)."

Affected Files: docs/src/content/docs/setup/quick-start.mdx, docs/src/content/docs/introduction/how-they-work.mdx

---

💡 Minor Confusion Points (Score: 3/10)

• Copilot-first language in auth secrets example — auth.mdx shows gh aw secrets set COPILOT_GITHUB_TOKEN as the only CLI example in the "Adding secrets using the CLI" section before showing the table. File: docs/src/content/docs/reference/auth.mdx
• No "Why Claude vs. Copilot?" comparison — No guidance on when to choose Claude over Copilot (capability trade-offs, cost, licensing). Docs treat this as "pick one" without explaining differences.
• MCP server documentation uses engine: copilot — The network configuration example in architecture.mdx line 228 uses engine: copilot as the only example. Could easily show engine: claude or omit the engine field.
• secrets bootstrap --engine only lists copilot/claude/codex — Gemini is missing from --engine option list in CLI docs: gh aw secrets bootstrap --engine copilot. Possible stale docs.
• No Claude Code-specific "getting started" callout — Users coming from Claude Code as their entry point have no "start here if you're a Claude Code user" guide.

---

Engine Comparison Analysis

Available Engines

Based on my review, gh-aw supports four engines: copilot (default), claude, codex, and gemini.

Documentation Quality by Engine

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

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

Notes:

• Claude auth docs are excellent — the explicit note that CLAUDE_CODE_OAUTH_TOKEN is NOT supported is uniquely helpful for Claude Code users.
• Claude has 45 real-world workflow examples in .github/workflows/ (vs. ~93 Copilot) — a meaningful body of examples.
• Gemini coverage is notably thinner than other engines.

---

Tool Availability Analysis

Tools Review

Engine-Agnostic Tools (all engines):

• edit: — file editing
• bash: — shell commands
• github: — GitHub API (all toolsets)
• web-fetch: — HTTP fetching
• playwright: — browser automation
• cache-memory: — persistent memory
• repo-memory: — repository-scoped memory
• agentic-workflows: — workflow introspection
• qmd: — vector search
• All MCP server integrations (mcp-servers:)

Engine-Specific Features:

• max-turns — Claude only (advantage, not limitation)
• max-continuations — Copilot only
• engine.agent — Copilot only
• web-search: — Codex opt-in; all others via MCP
• Tool timeout defaults — differ by engine (Claude: 60s, Codex: 120s, others: engine-managed)

Conclusion: Tools are almost entirely engine-agnostic. The Claude engine has no missing tools relative to Copilot.

---

Authentication Requirements

Current Documentation Status

Quick Start guide covers authentication for:

• ✅ Copilot — detailed instructions with pre-filled PAT creation link
• ✅ Claude — full docs including explicit CLAUDE_CODE_OAUTH_TOKEN is NOT supported note
• ✅ Codex — full docs with CODEX_API_KEY / OPENAI_API_KEY fallback chain explained
• ✅ Gemini — basic docs present

Claude-Specific Auth Notes (Positive Findings)

The auth page handles Claude Code users exceptionally well:

"CLAUDE_CODE_OAUTH_TOKEN is not supported by GitHub Agentic Workflows. The only supported authentication method for the Claude engine is ANTHROPIC_API_KEY. Provider-based OAuth authentication (such as billing through a Claude Teams or Claude Max subscription) is not supported."

This is exactly the kind of Claude-aware documentation that prevents frustrating auth failures.

Secret Names Reference

Engine	Primary Secret	Alternative
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

Total workflows in .github/workflows/: 191
Engine: claude  — 45 workflows (~24%)
Engine: copilot — 93 workflows (~49%)
Engine: codex/gemini/default — remainder

Quality of Examples

Claude Examples: 45 workflows including audit-workflows.md, deep-report.md, scout.md, go-fan.md, security-compliance.md, and this very workflow (claude-code-user-docs-review.md). These demonstrate that Claude workflows are production-grade and well-used in this repository.

Coverage: Claude examples cover scheduling, issue analysis, code auditing, safe outputs, and multi-turn operations. Sufficient for a new user to understand what's possible.

Gap: No "hello world" Claude-specific example in the documentation site itself — examples live in .github/workflows/ but aren't featured on a docs page dedicated to Claude engine usage.

---

Recommended Actions

Priority 1: Critical Documentation Fixes

1. Fix architecture.mdx diagrams — Replace "Copilot CLI" labels with engine-agnostic labels in both the AWF firewall diagram and the MCP Gateway diagram. File: docs/src/content/docs/introduction/architecture.mdx lines 181, 252
2. Fix broken cross-reference in auth.mdx — The "additional configuration needed when using Claude with GitHub MCP" link should either point to the correct github-tools remote mode section or be removed. File: docs/src/content/docs/reference/auth.mdx lines 125, 167, 185
3. Add default-engine warning — Add a tip box in quick-start and how-they-work noting that omitting engine: defaults to Copilot. Files: docs/src/content/docs/setup/quick-start.mdx, docs/src/content/docs/introduction/how-they-work.mdx

Priority 2: Major Improvements

1. Rewrite gh aw init section for non-Copilot users — Document what value gh aw init provides for Claude Code users (.gitattributes, VS Code settings, MCP tools). File: docs/src/content/docs/setup/creating-workflows.mdx line 102+
2. Add non-Copilot alternative for web authoring — After the Copilot-gated web interface section, add a short paragraph for Claude Code / Codex users explaining they can use the CLI or their local agent to author workflows. File: docs/src/content/docs/setup/creating-workflows.mdx line 20+
3. Feature a Claude workflow on the documentation site — Add a documentation page or callout under "Examples" that highlights a real Claude engine workflow end-to-end, analogous to the quick start's Copilot-default approach.

Priority 3: Nice-to-Have Enhancements

1. "Why choose Claude?" section in engines.md — Compare Claude vs. Copilot trade-offs (e.g., max-turns control, API key billing, Claude Code familiarity) to help users make an informed choice.
2. Add engine: claude to more documentation examples — When showing workflow frontmatter snippets in reference docs, alternate the engine used rather than always defaulting to Copilot.
3. "Getting started as a Claude Code user" callout — A short boxed section near the top of quick-start linking to Claude-specific setup steps.

---

Positive Findings

What Works Well for Claude Code Users

• ✅ Quick Start prerequisites explicitly name Claude alongside Copilot and Codex — sets correct expectations immediately
• ✅ Auth page is excellent — ANTHROPIC_API_KEY documented in full with a unique, Claude-Code-aware note that CLAUDE_CODE_OAUTH_TOKEN is not supported
• ✅ Engine comparison table in engines.md is comprehensive and honest about per-engine differences
• ✅ 45 production Claude workflows in this repo provide strong real-world examples
• ✅ gh aw new --engine claude generates correctly-configured templates
• ✅ gh aw secrets bootstrap --engine claude provides Claude-specific secret validation
• ✅ max-turns is a Claude-only advantage clearly documented
• ✅ All tools are engine-agnostic — nothing Claude Code users expect is missing
• ✅ add-wizard engine selection makes first-run experience smooth regardless of engine choice
• ✅ Creating workflows section (non-web) explicitly lists Claude as a supported coding agent (line 70: "VSCode/Claude/Codex/Copilot")

---

Conclusion

Can Claude Code Users Successfully Adopt gh-aw?

Answer: Yes, with moderate effort

Reasoning: The core gh-aw feature set works equally well with Claude. Authentication documentation is strong and Claude-aware. The CLI, tools, and safe-outputs system are fully engine-agnostic. A Claude Code user who works through the quick start and reads the auth page will have a functional setup.

The friction comes from Copilot-centric framing in architectural diagrams, the creating-workflows guide's web interface section, the gh aw init description, and a few misleading cross-references. These are papercuts, not walls — but they cumulatively signal to a Claude Code user that they are a second-class user of this tool, which isn't accurate.

Overall Assessment Score: 7/10

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

Next Steps

1. Fix the three architectural diagram labels in architecture.mdx (fast, high-impact)
2. Repair the broken cross-reference in auth.mdx (fast fix)
3. Add a default-engine warning callout in quick-start.mdx (fast, high-value for new users)
4. Revise creating-workflows.mdx to neutralize Copilot-centric authoring framing (medium effort)

---

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/overview.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/reference/engines.md
• docs/src/content/docs/reference/auth.mdx
• docs/src/content/docs/reference/github-tools.md
• .github/workflows/*.md (sampled 10+ Claude and Copilot workflows)

---

References:

• §24400997952

Workflow: claude-code-user-docs-review | Engine: claude (eating our own dog food 🐕)

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

• expires on Apr 15, 2026, 1:22 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 #26433.