🔍 Claude Code User Documentation Review - 2026-02-24

[github-actions[bot]]

Executive Summary

As a developer who uses Claude Code (not GitHub Copilot), I reviewed the gh-aw documentation to assess how accessible it is for non-Copilot users. The overall experience is reasonably accessible — the core path works well, prerequisites are honest, and authentication for Claude is documented. However, there are persistent, recurring friction points in secondary docs and examples that signal a Copilot-first design perspective. No critical blockers exist, but 6 significant pain points and 10 minor confusions remain unresolved from prior review cycles.

Key Finding: Claude Code users can successfully adopt gh-aw with some friction. The onboarding path (quick start + engines ref + auth ref) is solid. The friction lives in surrounding documentation — architecture diagrams, workflow creation guides, troubleshooting, and example counts — all of which have a Copilot-centric orientation.

Trend: This is the third consecutive daily review. The score remains stable at 7/10. No issues from the previous two reviews have been addressed. The ANTHROPIC_API_KEY URL issue (flagged Feb 22) remains unresolved.

---

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?

Yes, with minor friction. The quick start guide (docs/src/content/docs/setup/quick-start.mdx) correctly lists Claude as a valid AI Account option in prerequisites alongside Copilot and Codex. The gh aw add-wizard command offers an interactive engine selection step that includes Claude, and the authentication reference documents ANTHROPIC_API_KEY clearly.

The first-run experience via add-wizard is genuinely engine-agnostic at the CLI level. A Claude user can complete the quick start without hitting any hard walls.

Specific Issues Found:

• Issue 1: creating-workflows.mdx line 21 — The "GitHub Web Interface" section opens with **If you have access to GitHub Copilot**, explicitly gating this path. There is no alternative workflow creation path for Claude Code users in the web interface section. File: docs/src/content/docs/setup/creating-workflows.mdx
• Issue 2: creating-workflows.mdx line 96 — The step-by-step instructions say "If not using Copilot, also adjust the engine: field" — this implies adjusting the engine field is an afterthought and Copilot is the default everyone starts with. No proactive guidance for Claude-first users.
• Issue 3: add-wizard is the primary UX path shown in the quick start, but it is absent from the cli.md commands reference. A user who searches the CLI reference to understand what add-wizard does will find nothing. File: docs/src/content/docs/setup/cli.md

Recommended Fixes:

• Add a "No Copilot access? Use Claude Code or Codex CLI instead:" callout in the web interface section of creating-workflows.mdx
• Reframe step 3 of CLI-based creation to say "Set the engine: field to claude, codex, or leave default copilot" rather than treating non-Copilot as an afterthought
• Document gh aw add-wizard in cli.md alongside gh aw add

---

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 — The creating-workflows.mdx explicitly gates the web interface section with "If you have access to GitHub Copilot." No alternative web-based authoring path is provided. Claude Code users must use the CLI path.
• /agent agentic-workflows Copilot Chat command — The custom-agent-for-aw.mdx guide focuses on Copilot Chat's /agent command. While Claude Code users can still install the agent file and use the markdown with Claude Code directly, this is not explained.
• assign-to-agent safe output with Copilot — The assign-to-copilot.mdx page documents assigning the Copilot coding agent to issues/PRs. Claude Code users cannot use this feature without Copilot. This is documented but could more clearly note the limitation upfront.

Features That Work Without Copilot (Engine-Agnostic):

• All core tools: github:, edit:, bash:, playwright:, cache-memory:, repo-memory:, agentic-workflows:, custom mcp-servers:
• All safe outputs: create-issue, add-comment, create-pull-request, create-discussion, dispatch-workflow
• CLI commands: init, add, compile, run, status, logs, audit, health, mcp, secrets
• Network configuration, lockdown mode, threat detection, secret redaction
• web-fetch tool

Missing Documentation:

• No explicit list anywhere of "Claude vs Copilot feature parity"
• web-search: tool is documented as "engine-dependent" but no table or guide clarifies which engines need an MCP server vs. have native support

---

Question 3: Documentation Clarity for Non-Copilot Users

Where does the documentation assume Copilot usage?

Copilot-Centric Language Found In:

• File: docs/src/content/docs/introduction/architecture.mdx — Mermaid diagram (line 177) shows COPILOT["Copilot CLI"] as the sole agent process in the AWF network diagram. A second diagram (line 248) labels the agent container "Agent container\nCopilot CLI + MCP client\n172.30.0.20". For a Claude user reading the architecture documentation, this creates a false impression that the system is Copilot-specific at the infrastructure level.
• File: docs/src/content/docs/setup/creating-workflows.mdx — The entire "GitHub Web Interface" section is Copilot-gated. The CLI authoring section recommends "VSCode Agent Mode" which is a Copilot product, before mentioning other coding agents.
• File: docs/src/content/docs/guides/web-search.md — The example workflow uses engine: copilot only. No Claude equivalent shown.
• File: docs/src/content/docs/reference/engines.md lines 74-75 — In the "Extended Coding Agent Configuration" example, the YAML block shows engine: id: copilot with model: gpt-5 # defaults to claude-sonnet-4. This comment states the default model for the Copilot engine is claude-sonnet-4, which is accurate (Copilot uses Claude models), but is jarring and confusing for a Claude Code user who expects claude-sonnet-4 to be the Claude engine's model, not Copilot's.
• File: docs/src/content/docs/troubleshooting/common-issues.md — Only Copilot-specific troubleshooting sections exist (Copilot CLI Not Found, Copilot License or Inference Access Issues). No Claude-specific troubleshooting exists.
• File: docs/src/content/docs/reference/auth.mdx line 112 — ANTHROPIC_API_KEY setup URL: (platform.claude.com/redacted) — This URL appears incorrect. The Anthropic API keys are at https://console.anthropic.com`. The platform.claude.com URL may redirect or be a docs URL, not the actual key creation page. This issue was first flagged on 2026-02-22 and remains unresolved.

Missing Alternative Instructions:

• No guide equivalent to custom-agent-for-aw.mdx for Claude Code users (how to use Claude Code's CLAUDE.md / project instructions with agentic workflows)
• No Claude-specific troubleshooting (e.g., what to do if ANTHROPIC_API_KEY is misconfigured or quota is exceeded)

---

Severity-Categorized Findings

🚫 Critical Blockers (Score: 0/10)

None. A Claude Code user can successfully set up and run gh-aw workflows.

⚠️ Major Obstacles (Score: 6 obstacles identified)

Obstacle 1: Architecture Diagrams Show Copilot CLI as the Only Agent

Impact: Significant confusion for Claude users reading architecture docs

Current State: Two mermaid diagrams in architecture.mdx specifically label the agent as "Copilot CLI". Line 177 shows COPILOT["Copilot CLI"] and line 248 shows "Agent container\nCopilot CLI + MCP client\n172.30.0.20".

Why It's Problematic: A Claude Code user reading the security architecture documentation (which is detailed and important) will see diagrams that make it appear the entire system is built around Copilot CLI. This undermines confidence that Claude is a first-class citizen.

Suggested Fix: Replace "Copilot CLI" with "AI Agent (Copilot/Claude/Codex)" in these diagram nodes.

Affected Files: docs/src/content/docs/introduction/architecture.mdx lines 177, 248

Obstacle 2: GitHub Web Interface Workflow Creation is Copilot-Only

Impact: Claude Code users cannot use the web interface creation path

Current State: creating-workflows.mdx explicitly states "If you have access to GitHub Copilot, you can create and edit Agentic Workflows directly from the Web Interface." No alternative is offered in this section.

Why It's Problematic: For a Claude Code user who wants a quick, non-CLI way to create workflows, this section provides nothing useful. The section could at minimum note that Claude Code users can use the CLI path in the next section, or suggest using Claude Code directly in the terminal as an equivalent approach.

Suggested Fix: Add a note: "If you use Claude Code or another coding agent instead of Copilot, use the CLI authoring approach in the next section — it works with any coding agent."

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

Obstacle 3: ANTHROPIC_API_KEY Setup URL May Be Wrong (Unresolved, 3rd Day)

Impact: Claude users may be sent to the wrong URL when setting up their API key

Current State: auth.mdx line 112: `Create an API key at (platform.claude.com/redacted)

Why It's Problematic: The Anthropic API keys are created at https://console.anthropic.com/api-keys, not at a documentation page. platform.claude.com appears to be a docs/marketing subdomain. This issue has been flagged in the cache for three consecutive review cycles (Feb 22, 23, 24) with no fix.

Suggested Fix: Update the URL to https://console.anthropic.com/api-keys

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

Obstacle 4: Web Search Guide Has No Claude Engine Example

Impact: Claude users who want web search must figure out the configuration themselves

Current State: web-search.md contains a single complete workflow example using engine: copilot. The tools reference notes "Some engines require third-party MCP servers for web search" but the guide doesn't show which engines this applies to or provide a Claude-specific example.

Suggested Fix: Add a note clarifying which engines support native web-search: vs. require a Tavily/Exa MCP server, and add a Claude-specific example.

Affected Files: docs/src/content/docs/guides/web-search.md

Obstacle 5: No Claude-Specific Troubleshooting

Impact: When Claude engine workflows fail, users have no troubleshooting docs to consult

Current State: The troubleshooting guide has two Copilot-specific sections ("Copilot CLI Not Found", "Copilot License or Inference Access Issues") but zero Claude-specific sections.

Suggested Fix: Add a "Claude Engine Issues" section covering: invalid/expired ANTHROPIC_API_KEY, rate limiting behavior, model selection errors.

Affected Files: docs/src/content/docs/troubleshooting/common-issues.md

Obstacle 6: `add-wizard` Command Undocumented in CLI Reference

Impact: Users following the quick start who then look up the CLI reference are confused

Current State: quick-start.mdx uses gh aw add-wizard as the primary onboarding command, and it appears in multiple example docs, but cli.md (the CLI commands reference) does not document add-wizard as a command.

Suggested Fix: Add add-wizard documentation to cli.md in the "Getting Workflows" section alongside add.

Affected Files: docs/src/content/docs/setup/cli.md

💡 Minor Confusion Points (10 identified)

• Issue 1: engines.md line 75 — Comment # defaults to claude-sonnet-4 appears next to model: gpt-5 inside a copilot engine block. This is saying Copilot uses Claude Sonnet as its default model, which is confusing to a Claude engine user who expects that to be their model. File: docs/src/content/docs/reference/engines.md
• Issue 2: how-they-work.mdx says "GitHub Copilot (default)" but doesn't explain why Copilot is the default or what it means for Claude users (no behavioral difference, just needs engine: field). File: docs/src/content/docs/introduction/how-they-work.mdx
• Issue 3: README.md has zero mentions of Claude or alternative engines. File: README.md
• Issue 4: creating-workflows.mdx line 96 says "If not using Copilot, also adjust the engine: field" — frames non-Copilot usage as exceptional. Should be: "Set engine: to claude, codex, gemini, or leave blank for copilot (default)." File: docs/src/content/docs/setup/creating-workflows.mdx
• Issue 5: faq.md "How is my code processed?" — The Copilot answer links to Copilot documentation, but the Claude/Codex answer just says "Uses respective providers' APIs with their data handling policies" with no link. A Claude user wanting to understand data privacy has no link to follow. File: docs/src/content/docs/reference/faq.md
• Issue 6: custom-agent-for-aw.mdx — Titled "Copilot Agent Files support for Agentic Workflows" but actually contains instructions useful for any coding agent. No mention of how Claude Code users can use equivalent context/instructions. File: docs/src/content/docs/reference/custom-agent-for-aw.mdx
• Issue 7: Engine example count imbalance in documentation — engine: copilot appears 44 times, engine: claude appears 5 times, engine: codex appears 2 times across all docs. This creates an impression of Copilot-centricity even when the underlying feature set is equivalent.
• Issue 8: secrets bootstrap --engine copilot is mentioned as an option but the equivalent --engine claude usage isn't highlighted in the quick start or auth guide. File: docs/src/content/docs/setup/cli.md
• Issue 9: The assign-to-copilot.mdx page (which is Copilot-only) is listed in the auth reference and could confuse Claude users into thinking it's a general feature. A brief "This feature requires GitHub Copilot" note at the top would help. File: docs/src/content/docs/reference/assign-to-copilot.mdx
• Issue 10: No "engine comparison" or "choosing an engine" guide exists. A Claude Code user has to infer from scattered references that Claude and Copilot have feature parity for core workflows.

---

Engine Comparison Analysis

Available Engines

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

• engine: copilot — Default. Well-documented with detailed troubleshooting, web interface authoring, and custom agents
• engine: claude — Fully functional. Clear setup docs, but fewer examples and no troubleshooting
• engine: codex — Functional. Documented in engines reference, minimal examples
• engine: gemini — Functional. Documented in engines reference, minimal examples (newest addition)

Documentation Quality by Engine

Engine	Setup Docs	Examples in Docs	Auth Docs	Troubleshooting	Overall
Copilot	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐ (44 examples)	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐
Claude	⭐⭐⭐⭐	⭐⭐⭐ (5 examples)	⭐⭐⭐⭐	⭐ (none)	⭐⭐⭐
Codex	⭐⭐⭐⭐	⭐⭐ (2 examples)	⭐⭐⭐⭐	⭐ (none)	⭐⭐⭐
Gemini	⭐⭐⭐	⭐⭐ (2 examples)	⭐⭐⭐⭐	⭐ (none)	⭐⭐

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

---

Tool Availability Analysis

Engine-Agnostic Tools (work with any engine):

• github: — GitHub API operations, all toolsets
• edit: — File editing
• bash: — Shell commands
• playwright: — Browser automation
• cache-memory: — Persistent memory across runs
• repo-memory: — Repository-specific memory
• agentic-workflows: — Workflow introspection
• web-fetch: — Fetch web content
• Custom mcp-servers: — Any MCP server

Engine-Specific / Partially Engine-Specific:

• web-search: — Engine-dependent (some engines need a third-party MCP server, others may have native support)
• copilot tool / assign-to-agent safe output — Copilot only (assigns Copilot coding agent to issues/PRs)
• Copilot agent: field in engine config — Copilot custom agents only

Unclear/Undocumented:

• Which engines support native web-search: vs. require Tavily/Exa MCP server — not documented clearly
• Whether api-proxy (token isolation) works for all engines or only Copilot — architecture docs imply Copilot only

---

Authentication Requirements

Current Documentation

• ✅ Copilot — Detailed instructions with video walkthrough, troubleshooting section
• ✅ Claude — Instructions present but setup URL may be wrong (platform.claude.com/docs/en/get-started vs console.anthropic.com/api-keys)
• ✅ Codex — Instructions present, link to OpenAI API keys
• ✅ Gemini — Instructions present, link to Google AI Studio

Missing for Claude Users

• No troubleshooting for invalid/expired ANTHROPIC_API_KEY
• No link to Anthropic data processing policy for users who want to understand privacy
• The CLAUDE_CODE_OAUTH_TOKEN FAQ entry is excellent — explicitly states it's not supported and only ANTHROPIC_API_KEY works

Secret Names

• Copilot: COPILOT_GITHUB_TOKEN (documented, with video)
• Claude: ANTHROPIC_API_KEY (documented, setup URL needs verification)
• Codex: OPENAI_API_KEY (documented)
• Gemini: GEMINI_API_KEY (documented)

---

Example Workflow Analysis

Workflow Count by Engine (in docs)

Engine: copilot  - 44 examples in documentation
Engine: claude   -  5 examples in documentation
Engine: codex    -  2 examples in documentation
Engine: gemini   -  2 examples in documentation

Note: No .github/workflows/*.md files were found in the gh-aw repository itself (clean workflows directory).

Quality of Examples

Copilot Examples: Comprehensive. Appear throughout quick start, guides, reference docs, and troubleshooting with many real-world scenarios (issue triage, PR review, CI doctor, daily reports, web search).

Claude Examples: Sparse but present. Found in: engines.md (basic setup), faq.md (switching engines), deterministic-agentic-patterns.md (scheduling), serena.md (refactoring), network.md (network config). These are functional but narrowly scoped — no end-to-end Claude workflow example for new users.

---

Recommended Actions

Priority 1: Critical Documentation Fixes

1. Fix ANTHROPIC_API_KEY setup URL — Change (platform.claude.com/redacted) to the correct Anthropic Console URL for API key creation. *This has been flagged for 3 consecutive days without resolution.* File: docs/src/content/docs/reference/auth.mdx:112`

2. Update architecture diagrams to be engine-agnostic — Replace "Copilot CLI" labels in mermaid diagrams with "AI Agent (Copilot/Claude/Codex/Gemini)". File: docs/src/content/docs/introduction/architecture.mdx:177,248

3. Document add-wizard in CLI reference — The primary onboarding command is absent from the CLI reference. File: docs/src/content/docs/setup/cli.md

Priority 2: Major Improvements

1. Add Claude Code path in creating-workflows.mdx — The web interface section explicitly gates on Copilot access. Add a note or alternative section for Claude Code users. File: docs/src/content/docs/setup/creating-workflows.mdx:21

2. Add Claude-specific troubleshooting section — Mirror the Copilot-specific troubleshooting sections with equivalent Claude content. File: docs/src/content/docs/troubleshooting/common-issues.md

3. Add Claude engine example to web-search guide — The web search guide should show a Claude-specific workflow example alongside the Copilot one. File: docs/src/content/docs/guides/web-search.md

4. Clarify web-search: engine compatibility — Document which engines have native web-search: support vs. require an MCP server. File: docs/src/content/docs/reference/tools.md

Priority 3: Nice-to-Have Enhancements

1. Add an "Choosing an AI Engine" guide — A brief comparison of Copilot vs. Claude vs. Codex for different use cases would help users make an informed choice without having to read all engine docs

2. Add more Claude workflow examples — Aim for 15+ Claude engine examples across guides (vs. 5 today) to approach the practical coverage Copilot gets

3. Add data privacy links for non-Copilot engines — The FAQ's "How is my code and data processed?" section should link to Anthropic/OpenAI/Google data policies, not just Copilot's

4. Add Anthropic data processing link in auth page — Mirror the "See Copilot documentation" cross-reference with equivalent Anthropic link

---

Positive Findings

What Works Well for Claude Code Users

• ✅ Quick start prerequisites explicitly mention Claude as a valid option (not buried)
• ✅ gh aw add-wizard interactive engine selection includes Claude
• ✅ gh aw secrets bootstrap --engine claude works and is documented
• ✅ All core tools (github:, edit:, bash:, playwright:, cache-memory:) are engine-agnostic
• ✅ All safe outputs (create-issue, add-comment, create-pull-request) are engine-agnostic
• ✅ Authentication reference has clear, parallel documentation for Claude (ANTHROPIC_API_KEY)
• ✅ FAQ explicitly addresses CLAUDE_CODE_OAUTH_TOKEN — a proactive, Claude-user-specific answer
• ✅ Billing documentation for Claude is clear (billed to Anthropic account via API key)
• ✅ Network config reference shows a Claude-specific example
• ✅ Gemini added as a fourth engine — demonstrates commitment to engine diversity beyond Copilot
• ✅ how-they-work.mdx mentions Claude and Codex alongside Copilot in the first paragraph

---

Conclusion

Can Claude Code Users Successfully Adopt gh-aw?

Answer: Yes, with minor effort

Reasoning: The functional path works. A Claude Code developer can install the extension, run add-wizard, select Claude, provide their ANTHROPIC_API_KEY, and have a working workflow in ~10 minutes. The core documentation (quick start, engines reference, auth reference) is genuinely inclusive of Claude users. The pain points are real but not blocking — they manifest as extra searching, occasional confusion, and a subtle sense that the tool was designed with Copilot users as the primary audience.

The main ongoing risk is the ANTHROPIC_API_KEY URL pointing to what appears to be an incorrect setup URL — if a new Claude user follows that link and can't find how to create an API key, that's a real first-day failure point.

Overall Assessment Score: 7/10

Breakdown:

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

Trend

• 2026-02-22: 7/10
• 2026-02-23: 7/10
• 2026-02-24: 7/10 (stable — no improvements or regressions)

Next Steps

The most impactful single fix would be updating the ANTHROPIC_API_KEY setup URL (Priority 1, item 1). This has been flagged three days in a row. After that, updating the architecture diagrams to remove Copilot-only branding would improve the experience for all non-Copilot engine users systematically.

---

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
• docs/src/content/docs/reference/faq.md
• docs/src/content/docs/setup/creating-workflows.mdx
• docs/src/content/docs/reference/copilot-custom-agents.md
• docs/src/content/docs/reference/custom-agent-for-aw.mdx
• docs/src/content/docs/reference/assign-to-copilot.mdx
• docs/src/content/docs/guides/web-search.md
• docs/src/content/docs/troubleshooting/common-issues.md (sampled)

---

Report Generated: 22372935606
Workflow: claude-code-user-docs-review
Review Date: 2026-02-24
Score Trend: 7/10 → 7/10 → 7/10 (stable, 3 days)
Engine Used: claude (eating our own dog food)

AI generated by Claude Code User Documentation Review

• expires on Feb 25, 2026, 10:39 PM UTC

[github-actions[bot]]

🤖 Smoke test agent was here!

Just passing through on my smoke-testing duties. Everything's running smoothly! The copilot smoke test agent officially visited this discussion at 2026-02-25T00:09:13Z. 🚀✨

(beep boop, this is an automated smoke test)

📰 BREAKING: Report filed by Smoke Copilot

[github-actions[bot]]

💥 WHOOSH! 🦸

A mysterious figure drops from the sky, cape billowing...

"SMOKE TEST AGENT — CLAUDE EDITION — WAS HERE!"

⚡ POW! All systems tested. All circuits firing!
🔥 BAM! GitHub MCP, Serena, Playwright, Tavily — ALL VANQUISHED!
💫 ZAP! Build compiled. Files written. PRs reviewed!

The agent surveys the battlefield, satisfied...

"Run 22375720540 — mission accomplished. The cloud fortress stands secure."

— Claude Smoke Test Agent, 2026-02-25 🦸♂️💨

💥 [THE END] — Illustrated by Smoke Claude

[github-actions[bot]]

This discussion was automatically closed because it expired on 2026-02-25T22:39:41.448Z.

Closed by Workflow