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

[github-actions[bot]]

This is a daily automated review of the gh-aw documentation from the perspective of a developer who uses Claude Code as their primary AI assistant and does not use GitHub Copilot. The goal is to identify blockers, gaps, and assumptions that prevent successful adoption by non-Copilot users.

Persona Context

Reviewing 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

Files reviewed: README.md, docs/src/content/docs/setup/quick-start.mdx, docs/src/content/docs/introduction/how-they-work.mdx, docs/src/content/docs/reference/tools.md, docs/src/content/docs/setup/cli.md, docs/src/content/docs/reference/auth.mdx, docs/src/content/docs/reference/engines.md

---

Executive Summary

Claude Code users can successfully adopt gh-aw. The core documentation — Quick Start, Authentication reference, Engines reference, and CLI reference — all treat Claude as a first-class engine alongside Copilot. The interactive wizard (gh aw add-wizard) prompts for engine selection and handles Claude API key setup. No critical blockers exist for non-Copilot users.

Key Finding: The documentation is well-structured for multi-engine use. The main friction points are cosmetic: a few persistent stale URLs, Gemini being inconsistently listed across pages, and the Quick Start ordering that lists Copilot's token first. None prevent adoption.

Trend: Score remains 8/10. One new minor issue found (inconsistent Gemini mention in how-they-work.mdx). Claude engine workflow examples grew from 35 → 37 since the last run — a positive signal.

---

Question 1: Onboarding Experience

Can a Claude Code user understand and get started with gh-aw?

Yes, with minor friction. The Quick Start prerequisites (quick-start.mdx, line 29) explicitly list:

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

The add-wizard step (Step 2) correctly states that it will "Select an AI Engine — Choose between Copilot, Claude, or Codex" and documents all three secrets (COPILOT_GITHUB_TOKEN, ANTHROPIC_API_KEY, OPENAI_API_KEY).

Specific Issues Found:

• Quick Start lists Gemini as a 4th supported engine in auth.mdx and engines.md but NOT in prerequisites or add-wizard step description (quick-start.mdx line 29 and 68). This inconsistency means a Gemini user would be confused, though Claude users are unaffected.
• README.md makes no mention of Claude, Codex, or alternative engines. The main project landing page simply describes the tool generically and links to docs. A developer discovering the project via GitHub would not know from the README alone that non-Copilot engines are supported.

Recommended Fixes:

• Add Gemini to Quick Start prerequisites line 29: GitHub Copilot, Anthropic Claude, OpenAI Codex, or Google Gemini
• Add one sentence to README Overview: "Supports multiple AI engines including GitHub Copilot, Claude by Anthropic, OpenAI Codex, and Google Gemini."

---

Question 2: Inaccessible Features for Non-Copilot Users

What features or steps don't work without Copilot?

Features That Require Copilot exclusively:

• max-continuations (autopilot mode with multiple consecutive runs) — engines.md feature table, Copilot-only
• engine.agent (custom agent files in .github/agents/) — Copilot-only, documented in engines.md
• Assigning Copilot coding agent to issues/PRs via safe outputs — inherently 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
• Custom MCP servers (mcp-servers:)
• All safe outputs operations (create-issue, create-comment, create-pr, etc.)
• max-turns (Claude-only per feature table, but documented clearly)
• gh aw compile, gh aw run, gh aw trial, gh aw logs, gh aw audit — all engine-agnostic CLI tools
• Network permissions, permissions model, frontmatter configuration

Missing Documentation:

• No "what can I do with Claude that I can't do with Copilot?" section. The feature comparison table in engines.md shows max-turns is Claude-only but doesn't explain why this is valuable or how to use it.
• The engine.agent Copilot custom agent feature has a dedicated reference page — there's no equivalent Claude-specific configuration guide.

---

Question 3: Documentation Gaps and Assumptions

Where does the documentation assume Copilot usage?

Copilot-as-Default Assumption:

• how-they-work.mdx line 26: "Workflows support GitHub Copilot (default), Claude by Anthropic, and Codex." The "(default)" label is accurate but not explained. A Claude user wondering "what happens if I use a workflow without engine: specified?" could be confused until they find engines.md which explains the default more explicitly.
• cli.md init command: runs in "interactive mode for engine selection" — good, no Copilot assumption.

Copilot-Centric Language Found In:

• File: how-they-work.mdx line 26 — Copilot listed first with "(default)", Gemini omitted entirely from this introductory page
• File: auth.mdx lines 17–18 — Copilot listed first in the engine-secret mapping table (ordering preference, not a functional issue)
• File: engines.md Copilot Custom Configuration section — has a dedicated subsection with a reference page; Claude has no equivalent

Missing Alternative Instructions:

• No "Getting Started with Claude engine" guide or landing page. Discoverable via engines.md and auth.mdx but no dedicated onboarding path.
• No explicit statement that workflows without engine: field use Copilot by default — discoverable in engines.md but not in Quick Start or How They Work.

---

Severity-Categorized Findings

🚫 Critical Blockers — Score: 0/10

None found. Claude engine is fully supported with clear authentication documentation, CLI support, and workflow examples.

⚠️ Major Obstacles — Score: 2/10

Obstacle 1: README gives no indication that non-Copilot engines are supported

Impact: First-time discovery friction — developers finding the project via GitHub may assume Copilot is required before reading the docs.

Current State: README.md Overview section describes gh-aw generically without mentioning any AI engine. The only AI reference is an implicit one through the Guardrails section.

Why It's Problematic: A Claude Code user evaluating whether to invest time in this tool gets no signal from the main project page that Claude is supported. They must click through to documentation to find this out.

Suggested Fix: Add to README Overview: "Supports multiple AI coding agents including GitHub Copilot (default), Claude by Anthropic, OpenAI Codex, and Google Gemini — bring your own API key."

Affected Files: README.md (lines 33–35)

💡 Minor Confusion Points — Score: 6/10

• Issue 1 (PERSISTENT day 7): auth.mdx line 103 — ANTHROPIC_API_KEY setup URL is (platform.claude.com/redacted) (a docs page) rather than the direct API key creation page (https://console.anthropic.com/settings/keys`). Minor UX friction.
• Issue 2 (PERSISTENT day 7): Web search guide (/gh-aw/guides/web-search/) — based on previous reviews, only shows engine: copilot example, no Claude MCP web search example. (Not re-read today but unresolved from previous runs.)
• Issue 3 (PERSISTENT day 7): quick-start.mdx line 29 and 68 — Gemini missing from Quick Start prerequisites and add-wizard step description, despite being documented in auth.mdx and engines.md.
• Issue 4 (PERSISTENT day 7): engines.md line 18 — Claude entry links to https://www.anthropic.com/index/claude which is potentially a stale URL (Anthropic has reorganized their site).
• Issue 5 (PERSISTENT day 4): architecture.mdx — AWF firewall diagram labels the agent component as "Copilot CLI" instead of a generic "AI Agent" label, implying the architecture is Copilot-specific.
• Issue 6 (NEW day 1): how-they-work.mdx line 26 — AI Engines section lists "GitHub Copilot (default), Claude by Anthropic, and Codex" — omits Gemini despite it being a supported 4th engine in engines.md and auth.mdx.

---

Engine Comparison Analysis

Available Engines

Engine	engine: value	Required Secret	Notes
GitHub Copilot	copilot (default)	COPILOT_GITHUB_TOKEN	Requires active Copilot license
Claude by Anthropic	claude	ANTHROPIC_API_KEY	Claude Code, pay-per-use API
OpenAI Codex	codex	OPENAI_API_KEY	Web search opt-in required
Google Gemini	gemini	GEMINI_API_KEY	Newest; fewest workflow examples

Documentation Quality by Engine

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

Rating Scale: ⭐⭐⭐⭐⭐ Excellent · ⭐⭐⭐⭐ Good · ⭐⭐⭐ Fair · ⭐⭐ Poor · ⭐ Missing/Minimal

---

Tool Availability Analysis

Engine-Agnostic Tools (work with any engine):

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

Engine-Specific Notes:

• web-search — Codex: opt-in via explicit declaration; Copilot/Claude/Gemini: requires third-party MCP server
• engine.agent — Copilot only (custom agent files)
• max-turns — Claude only
• max-continuations — Copilot only

Unclear/Undocumented:

• Tool timeout defaults: tools.md mentions "Claude: 60s, Codex: 120s" but doesn't state Copilot's or Gemini's defaults.

---

Authentication Requirements

Current Documentation Coverage

• ✅ Copilot — Detailed instructions with pre-filled PAT creation link, troubleshooting section
• ✅ Claude — ANTHROPIC_API_KEY documented with setup steps; URL slightly suboptimal (docs page vs. direct key creation page)
• ✅ Codex — OPENAI_API_KEY documented with setup steps and direct URL
• ✅ Gemini — GEMINI_API_KEY documented with Google AI Studio URL

Secret Names Reference

Engine	Secret Name	Documentation
Copilot	COPILOT_GITHUB_TOKEN	✅ Detailed with PAT setup
Claude	ANTHROPIC_API_KEY	✅ Documented (URL needs fix)
Codex	OPENAI_API_KEY	✅ Documented
Gemini	GEMINI_API_KEY	✅ Documented

---

Example Workflow Analysis

Workflow Count by Engine

engine: claude  — 37 workflows  (+2 since 2026-04-03)
engine: copilot — 89 workflows
engine: codex   — 17 workflows
engine: gemini  —  0 workflows
(workflows without explicit engine: use Copilot default)

Quality Assessment

Claude Examples (37 workflows): Solid representation across diverse use cases including typist.md, static-analysis-report.md, shared MCP components, and semantic refactoring. These provide practical reference for Claude-specific configurations.

Copilot Examples (89 workflows): The largest set. Many use default engine (no explicit engine: field) which defaults to Copilot.

Codex Examples (17 workflows): Adequate for reference.

Gemini Examples (0 workflows): No production examples yet — Gemini appears documentation-complete but example-starved.

---

Recommended Actions

Priority 1: Quick Wins (Low Effort, High Impact)

1. Fix ANTHROPIC_API_KEY setup URL — Change platform.claude.com/docs/en/get-started to https://console.anthropic.com/settings/keys in docs/src/content/docs/reference/auth.mdx line 103. Day 7 without a fix.
2. Add Gemini to Quick Start prerequisites — docs/src/content/docs/setup/quick-start.mdx line 29: add "or Google Gemini" to the AI Account bullet.
3. Add Gemini to how-they-work.mdx engine list — docs/src/content/docs/introduction/how-they-work.mdx line 26: add ", and Gemini by Google" after Codex.
4. Update Claude link in engines.md — Verify anthropic.com/index/claude still resolves correctly; if not, update to current URL.

Priority 2: Meaningful Improvements

1. Add engine diversity statement to README — One sentence in Overview mentioning all four engines signals to evaluators that Copilot is not required.
2. Generalize architecture.mdx diagram labels — Replace "Copilot CLI" with "AI Agent/Engine" in the AWF firewall diagram to reflect multi-engine reality.
3. Add Claude web search MCP example to web search guide — Mirror the existing Copilot web search example with a Claude equivalent using an MCP server.

Priority 3: Nice-to-Have Enhancements

1. Add a "Choosing Your Engine" section to how-they-work.mdx or as a standalone guide: tradeoffs between Copilot (GitHub-native), Claude (powerful reasoning, pay-per-use), Codex (OpenAI ecosystem), Gemini.
2. Document Claude-specific features — max-turns is Claude-only but has no dedicated explanation of when/why to use it.
3. Add Gemini workflow examples — At least 1–2 example workflows to validate and demonstrate Gemini support.

---

Positive Findings

What works well for Claude Code users:

• ✅ add-wizard is engine-neutral — Interactive setup correctly prompts for engine selection and handles all API keys
• ✅ Auth reference is comprehensive — All four engines documented with clear secret names and setup steps
• ✅ Engines reference page is excellent — Feature comparison table clearly shows per-engine capabilities; Claude-specific features (max-turns) are documented
• ✅ 37 Claude workflow examples — More than enough to learn from and adapt
• ✅ CLI tools are engine-agnostic — compile, run, trial, logs, audit all work regardless of engine
• ✅ --engine claude flag available on key CLI commands — gh aw new, gh aw add, gh aw validate, gh aw init all support engine selection
• ✅ secrets bootstrap supports all engines — gh aw secrets bootstrap --engine claude works
• ✅ Custom API endpoint support — ANTHROPIC_BASE_URL env var and api-target field documented for Claude, enabling corporate proxy/custom endpoint use

---

Conclusion

Can Claude Code Users Successfully Adopt gh-aw?

Answer: Yes, with minor friction.

The documentation presents Claude as a genuine first-class engine. The Quick Start wizard, authentication reference, and engines reference all handle Claude cleanly. A developer with an Anthropic API key can follow the Quick Start guide, select Claude when prompted, and have a working agentic workflow in under 10 minutes.

The friction points are real but minor: a slightly wrong URL for getting an API key, Gemini being inconsistently listed across pages, and the README not signaling multi-engine support to first-time visitors. None of these would block a motivated Claude user.

Overall Assessment Score: 8/10

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

Trend vs. Previous Run (2026-04-03)

• Score: unchanged at 8/10
• Critical blockers: 0 (unchanged)
• Major obstacles: 1 (unchanged — README omits engine diversity)
• Minor issues: 6 (+1 new: how-they-work.mdx Gemini omission)
• Claude workflow examples: +2 (35 → 37) — positive growth
• Persistent issues aging: 5 issues now at day 7 (API key URL, web search example, Gemini in Quick Start, Claude link, architecture diagram)

Next Steps

The 5 issues persisting since day 7 (especially the ANTHROPIC_API_KEY URL and Gemini in Quick Start) are small fixes that could be batched into a single documentation PR. The architecture diagram label change and README improvement are slightly larger but straightforward. No urgent action required — the documentation is serving Claude users adequately as-is.

---

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/reference/tools.md
• docs/src/content/docs/setup/cli.md
• docs/src/content/docs/reference/auth.mdx
• docs/src/content/docs/reference/engines.md

---

Report Generated: §24002231502
Workflow: claude-code-user-docs-review
Engine Used: claude (eating our own dog food)

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

• expires on Apr 6, 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 #24891.