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

[github-actions[bot]]

Executive Summary

This review analyzes the gh-aw documentation from the perspective of a developer who uses Claude Code as their primary AI assistant and does not have a GitHub Copilot subscription. The documentation is in good shape for Claude Code users: the Quick Start guide explicitly presents Claude as a first-class option, authentication is well-documented, and there are 215+ Claude engine workflow examples in the repo. Two substantive issues were found — one with a broken/misdirected URL and one with a Copilot-only example in the web search guide.

Key Finding: Claude Code users can successfully understand and adopt gh-aw with minimal friction. The onboarding experience is genuinely multi-engine friendly from step one.

---

Persona Context

This review was conducted 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?

Yes, clearly. The Quick Start guide (docs/src/content/docs/setup/quick-start.mdx) leads with:

AI Account - GitHub Copilot, Anthropic Claude or OpenAI Codex

Step 2 of the quick start uses gh aw add-wizard, which interactively walks the user through engine selection and secret setup — and explicitly names all three secrets: COPILOT_GITHUB_TOKEN, ANTHROPIC_API_KEY, or OPENAI_API_KEY. This is excellent.

Specific Issues Found:

• Issue 1 (Minor): docs/src/content/docs/introduction/how-they-work.mdx line 26 states "Workflows support GitHub Copilot (default), Claude by Anthropic, and Codex." The parenthetical (default) next to Copilot, without explanation, could cause a new user to wonder whether they need Copilot. A small clarification like "Copilot is the default if engine: is omitted, but Claude and Codex are equally supported" would remove ambiguity.

• Issue 2 (Minor): README.md overview section doesn't mention the supported AI engines at all. A user reading only the README gets no hint that Claude is an option until they click into the Quick Start.

Recommended Fixes:

• In how-they-work.mdx, add a one-sentence clarification: "Any engine can be selected by setting the engine: field — Copilot is simply the default when the field is omitted."
• In README.md, add a brief note in the Overview section: "Works with GitHub Copilot, Claude (Anthropic), Codex (OpenAI), and Gemini (Google)."

---

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, clearly documented in the engine comparison table
• engine.agent (custom agent files in .github/agents/) — Copilot only, documented
• Assigning Copilot coding agent to issues/PRs via safe outputs (assign-to-copilot) — as expected, Copilot-specific

Features That Work Without Copilot (Engine-Agnostic):

• All built-in tools: edit, github, bash, web-fetch, playwright, cache-memory, repo-memory, qmd, agentic-workflows
• All custom MCP servers
• All safe outputs (create-issue, create-comment, create-pr, etc.)
• max-turns (Claude only, but documented)
• All CLI commands (compile, run, logs, audit, trial, etc.)
• The full network firewall and security architecture

Missing Documentation:

• The web-search guide (docs/src/content/docs/guides/web-search.md) only shows a Copilot engine example despite the MCP configuration being engine-agnostic. A Claude user reading this guide would need to mentally substitute engine: copilot with engine: claude — easy but not shown.

---

Question 3: Documentation Gaps and Assumptions

Where does the documentation assume Copilot usage?

Copilot-Centric Language Found In:

• File: docs/src/content/docs/guides/web-search.md — The single code example in this guide uses engine: copilot. A Claude user needs to know this configuration works identically with engine: claude (same Tavily MCP server approach).
• File: docs/src/content/docs/introduction/how-they-work.mdx — "GitHub Copilot (default)" could mislead users into thinking Copilot is the primary/preferred engine.

Missing Alternative Instructions:

• The web search guide should show at least one engine: claude or engine-agnostic example.

---

Severity-Categorized Findings

🚫 Critical Blockers (Score: 0/10)

No critical blockers found. A Claude Code user can successfully complete the entire Quick Start without any Copilot dependency.

⚠️ Major Obstacles (Score: 2)

Obstacle 1: Incorrect ANTHROPIC_API_KEY Setup URL

Impact: User may not find where to create their Anthropic API key

Current State: docs/src/content/docs/reference/auth.mdx line 103 says:

Create an API key at (platform.claude.com/redacted)

Why It's Problematic: This URL navigates to a documentation/getting-started page, not the API key creation interface. A user following this link will need to navigate further to actually create an API key. The correct direct link for API key creation is https://console.anthropic.com/settings/keys.

Suggested Fix: Change the URL to https://console.anthropic.com/settings/keys to take users directly to the API key creation page.

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

Obstacle 2: Web Search Guide Is Copilot-Only

Impact: Claude users following the web search guide may not realize the configuration works the same way for them

Current State: docs/src/content/docs/guides/web-search.md contains one code example using engine: copilot. The title, intro, and all setup steps are engine-agnostic, but the only code sample hardcodes Copilot.

Why It's Problematic: A Claude user who reaches this guide will see engine: copilot and may wonder if web search requires Copilot, or whether there's a different procedure for Claude.

Suggested Fix: Either (a) change the example to engine: claude, (b) remove the engine: line from the example to make it clearly engine-agnostic, or (c) add a brief note: "Replace engine: copilot with your preferred engine — the Tavily MCP configuration is the same for all engines."

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

💡 Minor Confusion Points (Score: 4)

• Issue 1: how-they-work.mdx — "GitHub Copilot (default)" without contextual clarification that any engine is equally valid - File: docs/src/content/docs/introduction/how-they-work.mdx
• Issue 2: engines.md — The link for Claude points to https://www.anthropic.com/index/claude which is an outdated URL (likely redirects but not current) - File: docs/src/content/docs/reference/engines.md
• Issue 3: Quick Start prerequisites list "GitHub Copilot, Anthropic Claude or OpenAI Codex" but omit Gemini, which is a fully supported 4th engine - File: docs/src/content/docs/setup/quick-start.mdx
• Issue 4: README.md overview has no mention of supported AI engines — a user skimming the README gets no signal that Claude is supported before clicking into docs

---

Engine Comparison Analysis

Available Engines

Based on the review, gh-aw supports 4 engines with the following documentation quality:

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

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

Claude scores slightly below Copilot mainly due to the auth URL issue and the web-search guide's Copilot-only example. The engine comparison table (engines.md) is well-executed and clearly shows Claude-specific features like max-turns.

---

Tool Availability Analysis

Tools Review

Engine-Agnostic Tools (work with all engines):

• edit — file editing
• github — GitHub API operations (all toolsets)
• bash — shell commands
• web-fetch — fetch web content
• playwright — browser automation
• cache-memory — persistent cross-run storage
• repo-memory — repository-specific memory
• qmd — documentation vector search
• agentic-workflows — workflow introspection

Engine-Specific Tools/Features:

• engine.agent (custom agent files) — Copilot only
• max-turns — Claude only
• max-continuations (autopilot) — Copilot only
• tools.web-search built-in — Codex only (opt-in); all others use MCP

Unclear/Undocumented:

• Web search via MCP: works for Claude but the guide only demonstrates Copilot

---

Authentication Requirements

Current Documentation

Quick Start authentication documentation covers:

• ✅ Copilot: detailed instructions with PAT setup
• ✅ Claude: documented with URL issue (see Obstacle 1)
• ✅ Codex: fully documented
• ✅ Gemini: fully documented

Missing for Claude Users

• The ANTHROPIC_API_KEY setup URL (platform.claude.com/docs/en/get-started) should be console.anthropic.com/settings/keys
• No mention of Anthropic's usage tiers or rate limits (minor)

Secret Names

Engine	Secret Name	Documentation Status
Copilot	COPILOT_GITHUB_TOKEN	✅ Fully documented
Claude	ANTHROPIC_API_KEY	✅ Documented (URL needs fix)
Codex	OPENAI_API_KEY	✅ Fully documented
Gemini	GEMINI_API_KEY	✅ Fully documented

---

Example Workflow Analysis

Workflow Count by Engine

Engine: copilot - 250+ workflow files
Engine: claude  - 215 workflow files
Engine: codex   -  63 workflow files
Engine: gemini  - (not separately counted, smaller)

Quality of Examples

Copilot Examples: Comprehensive, covers all features including custom agents. Expected as the default engine.

Claude Examples: Strong — 215 files demonstrates Claude is a first-class supported engine with real production workflows. Claude examples include daily reports, research workflows, CI analysis patterns, and more.

Codex Examples: Moderate coverage with 63 files. Sufficient for most use cases.

---

Recommended Actions

Priority 1: Critical Documentation Fixes

1. Fix ANTHROPIC_API_KEY URL — Change (platform.claude.com/redacted) to https://console.anthropic.com/settings/keys` - File: docs/src/content/docs/reference/auth.mdx

2. Add Claude example to web search guide — Either change engine: copilot to engine: claude or add a note that the MCP configuration is engine-agnostic - File: docs/src/content/docs/guides/web-search.md

Priority 2: Major Improvements

1. Clarify "default" engine language — In how-they-work.mdx, add a sentence explaining that engine: claude (or any other) can be set to override the Copilot default - File: docs/src/content/docs/introduction/how-they-work.mdx

2. Update Claude link in engines.md — Change https://www.anthropic.com/index/claude to a current Anthropic URL - File: docs/src/content/docs/reference/engines.md

3. Add Gemini to Quick Start prerequisites — The prerequisites list only 3 engines but Gemini is a fully supported 4th option - File: docs/src/content/docs/setup/quick-start.mdx

Priority 3: Nice-to-Have Enhancements

1. Add engine mention to README overview — A brief line listing supported AI engines would help users scanning the README
2. Add a "Why Claude instead of Copilot?" FAQ entry — Brief comparison of when each engine shines
3. Add Claude-specific web search example — A dedicated workflow showing web search with Claude engine

---

Positive Findings

What Works Well for Claude Code Users

• ✅ Quick Start is exemplary — Explicitly presents Claude as an option in prerequisites and engine selection step
• ✅ add-wizard handles everything — Interactive setup guides users through engine selection with no Copilot assumption
• ✅ Authentication docs are complete — ANTHROPIC_API_KEY is clearly documented with setup steps
• ✅ Engine comparison table — engines.md provides clear, accurate feature comparison across all engines
• ✅ 215 Claude workflow examples — Strong signal that Claude is a production-supported engine
• ✅ CLI --engine claude flag — Shown explicitly in gh aw new documentation
• ✅ gh aw secrets bootstrap --engine claude — Engine-specific secret validation supported
• ✅ All built-in tools are engine-agnostic — No tool lock-in to Copilot
• ✅ max-turns is Claude-specific and documented — Claude-unique features are called out properly

---

Conclusion

Can Claude Code Users Successfully Adopt gh-aw?

Answer: Yes, with minimal friction

The documentation correctly positions Claude as a first-class AI engine from the first touchpoint (Quick Start prerequisites) through to reference documentation. The add-wizard command provides a guided, engine-neutral setup experience. Authentication is documented for all engines. With 215 Claude workflow examples in the repo, there's no question Claude is a genuine, supported choice.

The two substantive issues (auth URL and web search guide) are real but small — a determined Claude Code user would work around them in minutes. The 4 minor issues are polish-level improvements.

Overall Assessment Score: 8/10

Breakdown:

• Clarity for non-Copilot users: 8/10
• Claude engine documentation: 8/10
• Alternative approaches provided: 9/10
• Engine parity (examples & features): 8/10

Next Steps

1. Fix the ANTHROPIC_API_KEY URL in auth.mdx — 5 minute fix with high impact
2. Update web-search.md to show a Claude-engine example — 10 minute fix
3. Minor polish to how-they-work.mdx and README.md for clarity

---

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/guides/web-search.md

---

References:

• §23709821367

AI generated by Claude Code User Documentation Review · history

• expires on Mar 30, 2026, 1:17 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 #23552.