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

[github-actions[bot]]

As a developer who uses Claude Code (not GitHub Copilot), I reviewed the core gh-aw documentation to determine whether I can successfully understand and adopt this tool. The short answer is yes, with some friction — the fundamentals are documented, but several Copilot-centric patterns create confusion along the way.

Key Finding: A Claude Code user can get gh-aw working, but will encounter assumptions baked into examples, diagrams, and engine recommendations that may slow adoption or cause second-guessing.

---

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?

Mostly yes. The Quick Start (docs/src/content/docs/setup/quick-start.mdx) lists all AI engine options clearly in prerequisites (line 29):

"AI Account - GitHub Copilot, Anthropic Claude, OpenAI Codex, or Google Gemini"

The add-wizard command (Step 2) explicitly says it will "Select an AI Engine - Choose between Copilot, Claude, Codex, or Gemini." This is reassuring.

Specific Issues Found:

• Issue 1: quick-start.mdx, line 70 — The secret setup bullet lists COPILOT_GITHUB_TOKEN first with a parenthetical explanation "(a separate GitHub token with Copilot access — distinct from the default GITHUB_TOKEN)". All other engine secrets (ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY) are listed without elaboration. The asymmetry signals Copilot as the primary path.
• Issue 2: quick-start.mdx — The sample workflow linked in Step 2 (githubnext/agentics/daily-repo-status) has no engine: field, meaning it defaults to Copilot. A Claude user who runs gh aw add-wizard is prompted to choose their engine, but the text doesn't clearly explain that their engine selection will override the workflow default. If a user skips the wizard and copies the workflow directly, they get a Copilot workflow.
• Issue 3: introduction/overview.mdx, line 13 — Uses "coding agents (like Copilot CLI, Claude by Anthropic, or Codex)" with Copilot mentioned first and defined as the reference point.

Recommended Fixes:

• Add parenthetical descriptions for ANTHROPIC_API_KEY etc. similar to the Copilot token description.
• Add a callout in Quick Start Step 2 clarifying: "The engine you select will be set in the workflow's frontmatter — you don't need a Copilot subscription."
• Consider leading with a neutral engine name in overview examples, or add "(any engine)" clarification.

---

Question 2: Inaccessible Features for Non-Copilot Users

What features or steps don't work without Copilot?

Features That Require Copilot:

• max-continuations (autopilot mode with multiple consecutive runs) — Copilot-only per engines.md feature table
• engine.agent (custom agent files in .github/agents/) — Copilot-only
• engine.driver (custom driver script) — Copilot-only
• assign-to-copilot safe output — explicitly requires Copilot as the assignee

Features That Work Without Copilot (engine-agnostic):

• All safe-outputs (create-issue, add-comment, create-pull-request, etc.)
• All MCP servers
• All tools (edit, bash, github, playwright, cache-memory, repo-memory, etc.)
• max-turns — Claude-specific equivalent of turn limits
• web-fetch tool
• web-search tool (via MCP for Claude)
• engine.api-target, engine.env, engine.args, engine.command, engine.version
• Compilation, validation, all CLI commands

Missing Documentation:

• No "what can I do as a Claude user that I can't with Copilot?" section. The engines.md line 27 says "If you are unsure, start with Copilot and switch later" — this is the opposite advice for someone who already chose Claude.
• No Claude-specific workflow creation guide or tutorial.

---

Question 3: Documentation Gaps and Assumptions

Where does the documentation assume Copilot usage?

Copilot-Centric Language Found In:

• File: docs/src/content/docs/reference/engines.md, line 27 — "Copilot is the default choice for most users because it supports the broadest gh-aw feature set... If you are unsure, start with Copilot and switch later." For someone who chose Claude, this reads as a demotion of their choice.
• File: docs/src/content/docs/introduction/architecture.mdx, lines ~186-190 — The Agent Workflow Firewall (AWF) mermaid diagram labels the agent component as COPILOT["Copilot CLI"]. The other tools shown (WebFetch, WebSearch) are generic, but the agent itself is labeled as Copilot CLI. A Claude user reading this wonders: "Does AWF support me?"
• File: docs/src/content/docs/introduction/architecture.mdx, line 228 — The network configuration example uses engine: copilot as the only example shown.
• File: docs/src/content/docs/reference/faq.md, line 221 — "When using the default GitHub Copilot CLI" language throughout the FAQ when describing how things work.
• File: docs/src/content/docs/setup/cli.md, secrets bootstrap section — The example shows --engine copilot as the illustrative flag value.

Missing Alternative Instructions:

• No section in the docs explaining "AWF works with all engines — here's how it wraps Claude Code specifically"
• No Claude-specific "first workflow" tutorial or guide

---

Severity-Categorized Findings

🚫 Critical Blockers (Score: 0 — no true blockers)

None. Claude users can successfully set up and run gh-aw. The authentication docs are complete, the CLI supports --engine claude, and 47 Claude workflow examples exist in the repo.

⚠️ Major Obstacles (Score: 3 found)

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

Impact: Claude users reading the security architecture will wonder if AWF applies to their engine.

Current State: The Agent Workflow Firewall flowchart in architecture.mdx (the AWF section) labels the agent process as COPILOT["Copilot CLI"], with WEB["WebFetch Tool"] and SEARCH["WebSearch Tool"] as sibling processes. No mention of Claude or other engines as valid agent processes.

Why It's Problematic: The architecture section is critical for understanding security guarantees. A Claude user seeing only "Copilot CLI" in the agent container may incorrectly assume AWF isolation doesn't apply to their setup, or that Claude runs differently.

Suggested Fix: Change the diagram label from COPILOT["Copilot CLI"] to something like AGENT["AI Agent\n(Copilot, Claude, Codex, Gemini)"]. Add a caption note: "AWF wraps all supported engines identically."

Affected Files: docs/src/content/docs/introduction/architecture.mdx (AWF flowchart)

Obstacle 2: Quick Start Sample Workflow Defaults to Copilot Without Explanation

Impact: Users who add daily-repo-status without going through the full add-wizard flow will silently get a Copilot workflow.

Current State: daily-repo-status.md has no engine: field. The Quick Start text says add-wizard will prompt for engine selection, but doesn't explain that this selection injects engine: into the workflow or that the sample's default is Copilot.

Why It's Problematic: A Claude user who manually copies the workflow (or reads the workflow file directly) sees no engine: field and may not realize they need to add one. The docs don't warn that omitting engine: means Copilot is used.

Suggested Fix: Add a callout in Step 2: "Note: if you add a workflow without specifying an engine, it defaults to Copilot. The wizard will prompt you to choose your engine and inject it automatically."

Affected Files: docs/src/content/docs/setup/quick-start.mdx (Step 2)

Obstacle 3: "Which Engine Should I Choose?" Section Recommends Copilot First and Unconditionally

Impact: Discourages Claude Code users who have already chosen Claude, or creates doubt about their choice.

Current State: engines.md, line 27: "Copilot is the default choice for most users because it supports the broadest gh-aw feature set... If you are unsure, start with Copilot and switch later by changing only engine: and the corresponding secret."

Why It's Problematic: While technically accurate, this is the gh-aw documentation — users who arrived here already have an AI tool preference. The advice to "start with Copilot" is unhelpful and mildly off-putting for Claude users. It also overstates the Copilot advantage: the "broadest feature set" difference amounts to max-continuations, engine.agent, and engine.driver — niche features many users won't need.

Suggested Fix: Reframe the section to be user-need-centric: "If you already have a Claude subscription, use engine: claude. If you have a Copilot subscription, use engine: copilot (default, omit the field). Choose based on your existing AI subscription — most core features work with all engines."

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

💡 Minor Confusion Points (Score: 5 found)

• Issue 1: architecture.mdx network configuration example (line ~228) shows engine: copilot as the only engine in the YAML sample. — File: docs/src/content/docs/introduction/architecture.mdx
• Issue 2: faq.md uses "defaulting to GitHub Copilot CLI" throughout when describing how workflows execute, without a Claude/Codex alternative description. — File: docs/src/content/docs/reference/faq.md
• Issue 3: cli.md secrets bootstrap example shows --engine copilot as the example argument — File: docs/src/content/docs/setup/cli.md
• Issue 4: quick-start.mdx line 70 — Secret names listed asymmetrically: Copilot token has detailed explanation, others don't. — File: docs/src/content/docs/setup/quick-start.mdx
• Issue 5: No "Why would I use Claude over Copilot?" section anywhere in the docs — users with Claude subscriptions get no affirmation of their choice.

---

Engine Comparison Analysis

Available Engines

Based on my review, gh-aw supports: copilot (default), claude, codex, gemini, crush (experimental), opencode (experimental).

Documentation Quality by Engine

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

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

Notes on Claude rating: Auth docs are excellent (full section, troubleshooting, custom endpoint docs). Examples are good (47 workflows). Setup docs are solid but no dedicated "Claude user guide." Gemini has 0 workflow examples in this repo.

---

Tool Availability Analysis

Tools Review

Engine-Agnostic Tools (work with all engines):

• edit, bash, web-fetch, github, playwright, cache-memory, repo-memory, agentic-workflows, qmd
• All MCP server integrations (mcp-servers:)
• All safe-outputs
• All network/firewall features

Engine-Specific Tools:

• web-search — Native for Codex (opt-in); requires MCP server for Claude, Copilot, Gemini
• engine.agent — Copilot only (custom agent files)
• engine.driver — Copilot only
• max-continuations — Copilot only
• max-turns — Claude only

Unclear/Undocumented:

• Whether tools.mount-as-clis works identically for all engines (not explicitly stated)

---

Authentication Requirements

Current Documentation

Quick Start and auth docs cover authentication for:

• ✅ Copilot: Detailed instructions, troubleshooting, pre-filled PAT creation link
• ✅ Claude: Setup steps, custom endpoint docs, explicit note that CLAUDE_CODE_OAUTH_TOKEN is NOT supported
• ✅ Codex: Setup steps, Azure endpoint docs, CODEX_API_KEY alternative
• ✅ Gemini: Setup steps

Missing for Claude Users

• No direct link to create an Anthropic API key from the Console in the auth doc (the URL (platform.claude.com/redacted) is a docs page, not the actual key creation page like https://console.anthropic.com/settings/keys`)
• No note about Anthropic API billing tiers or free tier availability (Copilot auth docs implicitly acknowledge a subscription is needed; Claude auth could note free tier options)

Secret Names

• Copilot: COPILOT_GITHUB_TOKEN (documented)
• Claude: ANTHROPIC_API_KEY (documented)
• Codex: OPENAI_API_KEY or CODEX_API_KEY (documented)
• Gemini: GEMINI_API_KEY (documented)

---

Example Workflow Analysis

Workflow Count by Engine

Engine: copilot (explicit) - 88 workflows
Engine: copilot (implicit default) - 24 workflows (no engine: field)
Engine: claude              - 47 workflows
Engine: codex               - 10 workflows
Engine: gemini              - 0 workflows
Total                       - 201 workflows

Quality of Examples

Copilot Examples: Numerous, covering full feature range including max-continuations and custom agent files.

Claude Examples: Strong showing at 47 workflows, including production-grade workflows like deep-report.md, audit-workflows.md, scout.md. These demonstrate real usage patterns. However, there's no curated "start here with Claude" collection or index pointing to them.

Codex Examples: Present but limited.

Gemini Examples: None found in this repo's .github/workflows/.

---

Recommended Actions

Priority 1: Critical Documentation Fixes

1. Fix the AWF architecture diagram — Replace COPILOT["Copilot CLI"] with a generic agent label and add a note that AWF wraps all engines. — File: docs/src/content/docs/introduction/architecture.mdx
2. Add engine default warning in Quick Start — Clarify that workflows without engine: default to Copilot; add-wizard handles this, but users should know. — File: docs/src/content/docs/setup/quick-start.mdx
3. Fix the Anthropic Console link — Point directly to https://console.anthropic.com/settings/keys rather than the general get-started docs page. — File: docs/src/content/docs/reference/auth.mdx

Priority 2: Major Improvements

1. Reframe "Which engine should I choose?" — Write it from user-subscription-first perspective rather than defaulting to Copilot recommendation. — File: docs/src/content/docs/reference/engines.md
2. Equalize secret description detail in Quick Start — Give ANTHROPIC_API_KEY etc. the same inline context as COPILOT_GITHUB_TOKEN. — File: docs/src/content/docs/setup/quick-start.mdx
3. Add architecture example YAML for non-Copilot engines — The network configuration example in architecture.mdx only shows engine: copilot. Add a parallel Claude example. — File: docs/src/content/docs/introduction/architecture.mdx

Priority 3: Nice-to-Have Enhancements

1. Create a "Claude User Quick Start" variant or callout — A short note in the main Quick Start or a sidebar link: "Using Claude? Here's what's different."
2. Add Gemini workflow examples — Currently zero examples exist in this repo.
3. Add a "Claude vs. Copilot feature parity" section — Clearly state what's the same and different, framed positively for both.

---

Positive Findings

What Works Well

• ✅ Prerequisites in Quick Start lists all 4 engine options with equal prominence
• ✅ add-wizard prompts for engine selection interactively
• ✅ Authentication docs are comprehensive and symmetric for all engines
• ✅ 47 Claude workflow examples exist and are production-quality
• ✅ Claude-specific max-turns is well-documented with examples
• ✅ Claude tool enforcement security model has its own dedicated section in engines.md
• ✅ gh aw new --engine claude is documented, generating correct frontmatter
• ✅ CLAUDE_CODE_OAUTH_TOKEN unsupported status is explicitly documented (saves confusion)
• ✅ Custom Anthropic endpoint (ANTHROPIC_BASE_URL) is documented
• ✅ gh aw secrets bootstrap --engine claude exists and is documented

---

Conclusion

Can Claude Code Users Successfully Adopt gh-aw?

Answer: Yes, with moderate effort

The core infrastructure — authentication, CLI, compilation, safe-outputs — works identically for Claude users. The auth documentation is genuinely complete and helpful. With 47 Claude workflow examples available, there's solid evidence of real-world Claude usage.

The friction comes from cultural Copilot-centrism in diagrams and recommendations, not from missing functionality. The AWF architecture diagram labeling the agent as "Copilot CLI" is the most confusing issue — it could make Claude users doubt whether security isolation applies to them.

A motivated user will get through these friction points, but they'll need to mentally translate "when they say Copilot, does this also apply to me?" several times along the way.

Overall Assessment Score: 7/10

Breakdown:

• Clarity for non-Copilot users: 6/10 (diagram issues, engine recommendation framing)
• Claude engine documentation: 8/10 (auth and examples are solid)
• Alternative approaches provided: 7/10 (present but not highlighted)
• Engine parity: 8/10 (most features work; differences are clearly tabulated)

Next Steps

1. Fix the AWF diagram (quick win, high impact)
2. Add a "default engine" warning in Quick Start
3. Reframe engine recommendation language to be subscription-first

---

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/introduction/overview.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 (sample analysis: 201 workflow files)

---

Report Generated: §24891405826
Workflow: claude-code-user-docs-review
Engine Used: codex (via gh-aw harness; analysis performed by Claude Sonnet 4.6)

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

• expires on Apr 25, 2026, 1:20 PM UTC

[github-actions[bot]]

💥 KA-BOOM! The smoke test agent has ARRIVED! 🦸♂️⚡

WHOOOOSH! Like a lightning bolt from the digital cosmos, Claude Agent Run §24891531297 blazed through this documentation faster than a speeding pull request!

"With great agentic power comes great smoke testing responsibility!"
— Claude, probably

ZAP! ✅ Tests passed! POW! 🤖 Systems nominal! WHAM! 🚀 Engine validated!

The smoke test agent was here... and the workflows shall live on! 🌟

— Your friendly neighborhood Claude Agent, signing off 💫

💥 [THE END] — Illustrated by Smoke Claude · ● 289K · ◷