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

[github-actions[bot]]

Executive Summary

A Claude Code user can adopt gh-aw, but the path is consistently framed around GitHub Copilot — from the default engine:, to the gh aw init artifacts, to the example workflows. The non-Copilot path works but requires the user to actively translate Copilot-centric docs into Claude-equivalent steps. There are no true critical blockers, but multiple major obstacles that would slow down or confuse a developer who has deliberately chosen Claude over Copilot.

Key Finding: gh-aw is genuinely engine-agnostic at the runtime/compiler level, but the documentation, defaults, and worked examples are Copilot-first. A Claude Code user can succeed, but only after they learn to read past the Copilot framing.

---

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?

The README and Quick Start do mention Claude as a supported engine (README.md:40, quick-start.mdx:29, quick-start.mdx:70), so it's not invisible. However:

• The Quick Start title and screenshot center on Copilot — the add-wizard flow is shown installing daily-repo-status, and the only inline > [!NOTE] blocks that walk through token creation are for COPILOT_GITHUB_TOKEN and ANTHROPIC_API_KEY. Codex and Gemini are mentioned in the engine list (quick-start.mdx:70) but not given a setup block. A Claude user gets one short note (quick-start.mdx:82-86) versus a richer Copilot setup (quick-start.mdx:76-79).
• The very first frontmatter sample in Step 4 (quick-start.mdx:130-136) does show engine: claude — this is a real bright spot for Claude users.
• The engine: default is copilot (engines.md:16 and engines.md:24: "Copilot CLI is the default — engine: can be omitted when using Copilot."). A Claude user must remember to set it on every workflow or use --engine claude in gh aw new.

Specific Issues Found:

• README.md:40: "Supports GitHub Copilot, Claude (Anthropic), Codex (OpenAI), and Gemini (Google) — pick whichever AI account you already have." — Good, but the line is buried mid-Overview and easy to miss.
• quick-start.mdx:14: Sample workflow is daily-repo-status from githubnext/agentics — no indication whether the sample needs Copilot or works equally well under engine: claude.
• quick-start.mdx:78: "Setting up COPILOT_GITHUB_TOKEN?" gets numbered step-by-step instructions including the pre-filled PAT creation link; the equivalent for Claude (quick-start.mdx:82-86) is two terse sentences.

Recommended Fixes:

• Add a one-line "Quick choice" callout at the top of the Quick Start: "Pick your engine: Copilot (default) | Claude | Codex | Gemini" linking to that section.
• Make the add-wizard example show both --engine copilot and --engine claude invocations side-by-side.
• Bring the Claude setup note up to parity with the Copilot setup note (same numbered structure, same depth).

---

Question 2: Inaccessible Features for Non-Copilot Users

What features or steps don't work without Copilot?

The engine feature comparison table (engines.md:34-46) is excellent and honest — it shows clearly that several capabilities are Copilot-only. The problem is discoverability: the table is in the engines reference, not surfaced in the Quick Start or how-they-work.mdx. A Claude user might add a feature only to discover later it's Copilot-only.

Features That Require Copilot:

• engine.agent — custom agent files in .github/agents/ (engines.md:41). This is what gh aw init creates by default at .github/agents/agentic-workflows.agent.md (cli.md:134). On Claude, this dispatcher file is created but has no engine-side effect.
• engine.harness — custom Node.js harness wrapper (engines.md:44, engines.md:293-306). Claude can't use it.
• max-continuations — autopilot multi-run mode (engines.md:38). Claude has no equivalent.
• The add-wizard and many sample workflows in githubnext/agentics are written for Copilot defaults.

Features That Work Without Copilot:

• All tools.* (edit, bash, github, playwright, cache-memory, repo-memory, qmd, agentic-workflows, web-fetch) — engine-agnostic per tools.md.
• safe-outputs subsystem — engine-agnostic, designed around the agent's read-only model regardless of engine.
• All MCP server configuration — protocol-level, engine-agnostic.
• Network firewall (AWF), threat detection, integrity filtering, content sanitization — all engine-agnostic (architecture.mdx).
• engine.bare, engine.api-target, engine.env, engine.version, engine.args, tools.timeout, tools.startup-timeout, max-runs, timeout-minutes — all engines per engines.md:34-46 and engines.md:431-437.
• max-turns — Claude-only feature (engines.md:37) — a positive for Claude users.

Missing Documentation:

• What does gh aw init produce that is Copilot-specific vs. engine-agnostic? cli.md:134 says it creates .github/agents/agentic-workflows.agent.md — there is no note that this file is Copilot-only.
• For non-Copilot users, is gh aw init still necessary? Should --no-mcp or some flag skip the Copilot-specific dispatcher agent?
• No "Claude-equivalent" callout next to features like engine.agent or max-continuations pointing to the closest substitute (e.g., "use sub-workflows" or "increase max-turns instead").

---

Question 3: Documentation Gaps and Assumptions

Where does the documentation assume Copilot usage?

The assumption surfaces in three places:

1. Defaults and worked examples lean Copilot.

• engines.md:16,24: Copilot is the default engine — workflow authors who forget engine: silently get Copilot.
• Across docs/src/content/docs/, I counted ~40 engine: copilot snippets vs. ~5 engine: claude snippets. The Patterns and Reference sections almost universally show Copilot in code samples (e.g., architecture.mdx:228, cost-management.md:193, all four examples in audit.md:174-252).
• In the project's own .github/workflows/ directory, there are 100+ Copilot workflows, 52 Claude workflows, 9 Codex workflows, and 0 Gemini workflows — yet Gemini is advertised on README.md:40 as a supported engine. The repo eats its own dog food more enthusiastically with Copilot than with the alternatives.

2. gh aw init is implicitly Copilot-oriented.

• cli.md:132-145: gh aw init creates .github/agents/agentic-workflows.agent.md. The "agent file" concept is documented in engines.md:41 and copilot-custom-agents.md as Copilot-only. There is no warning that running gh aw init produces Copilot-specific scaffolding.

3. "Claude Code" terminology is ambiguous.

• engines.md:17 calls the engine "Claude by Anthropic (Claude Code)" — but a Claude Code user (i.e., a developer who uses the Anthropic Claude Code CLI on their own laptop) might not immediately realize that engine: claude actually launches the Claude Code CLI inside the runner. A one-line clarification ("This is the same claude CLI you may already have installed locally") would help.
• The Copilot BYOK mode (engines.md:201-268) lets users route Copilot CLI to Anthropic — which is a third meaning of "using Claude". This is genuinely confusing for newcomers.

Copilot-Centric Language Found In:

• File: docs/src/content/docs/setup/quick-start.mdx — Title screenshot/video shows add-wizard flow; Copilot secret gets the detailed step-by-step note.
• File: docs/src/content/docs/reference/audit.md:174-252 — All four configuration examples use engine: copilot.
• File: docs/src/content/docs/patterns/*.md — Patterns docs (spec-ops.md, side-repo-ops.mdx, central-repo-ops.mdx, deterministic-ops.md) use engine: copilot almost exclusively; deterministic-ops.md:71 is one of the few with engine: claude.
• File: docs/src/content/docs/blog/2026-02-05-how-workflows-work.md:210 — The frontmatter sample says engine: copilot # or claude, codex, custom. The custom engine value is referenced but I could not find a corresponding reference page.
• File: docs/src/content/docs/reference/auth.mdx:109 — Claude API key creation link goes to platform.claude.com/docs/en/get-started but the troubleshooting section at auth.mdx:199 links to console.anthropic.com and quick-start.mdx:84 links to console.anthropic.com/settings/keys. Three different URLs for the same task.

Missing Alternative Instructions:

• No Claude-Code-flavored "Quick Start" variant. Even a small section header "Using Claude as your engine" with the corresponding gh aw add-wizard --engine claude ... invocation would help.
• No "Why Claude vs Copilot?" guidance. The engines reference says only "Choose the engine that best matches your needs" (engines.md:28).
• No comparison of cost between engines — cost-management.md exists but its example is Copilot-only (cost-management.md:193).

---

Severity-Categorized Findings

🚫 Critical Blockers (Score: 0/10)

No critical blockers found. Every Claude-as-engine code path is documented somewhere, and ANTHROPIC_API_KEY setup is described in auth.mdx. A determined Claude user can succeed.

⚠️ Major Obstacles (Score: 4/10)

Obstacle 1: Quick Start is Copilot-first

Impact: A Claude user has to mentally translate the entire flow on their first read.

Current State: quick-start.mdx walks through Copilot setup as the canonical path; the Claude note is half the size and lacks the pre-filled PAT link equivalent.

Why It's Problematic: First-time users abandon docs that feel like they don't speak their setup.

Suggested Fix: Add a <Tabs> block with one tab per engine, each showing the matching gh aw add-wizard --engine <name> command and matching secret setup. Or add a "For Claude users" sibling section to Step 2.

Affected Files: docs/src/content/docs/setup/quick-start.mdx

Obstacle 2: `gh aw init` creates Copilot-specific scaffolding silently

Impact: Claude users get a .github/agents/agentic-workflows.agent.md file that has no effect under engine: claude. They will either commit it confused, or delete it not knowing it was Copilot-only.

Current State: cli.md:132-145 describes gh aw init but does not mention that the dispatcher agent file is Copilot-only. engines.md:41 does say engine.agent is Copilot-only, but a newcomer won't connect the dots.

Why It's Problematic: Silent Copilot defaults erode trust when a Claude user discovers they've been given dead scaffolding.

Suggested Fix: Add a note to cli.md init section: "If you plan to use engine: claude, engine: codex, or engine: gemini, the dispatcher agent file is created but has no effect — Copilot-style custom agents are not supported on those engines." Consider an --engine flag on init that skips the dispatcher file for non-Copilot engines.

Affected Files: docs/src/content/docs/setup/cli.md, cmd/gh-aw/init implementation

Obstacle 3: Sample workflows skew Copilot

Impact: Claude users can't easily find a "this is what a complete Claude workflow looks like" reference.

Current State: In the patterns/reference docs, ~40 engine: copilot examples vs. ~5 engine: claude examples. The audit.md reference has four configuration examples, all Copilot. Of the in-repo .github/workflows/, 52 use Claude vs. 100+ Copilot.

Why It's Problematic: Examples are the primary way developers learn. Without representative Claude examples, every Claude user re-derives the same configuration.

Suggested Fix: For each pattern doc with multiple examples, include at least one Claude version. Add a "Engine-agnostic by default" callout to tools.md so users know which features are universal.

Affected Files: docs/src/content/docs/patterns/*.md, docs/src/content/docs/reference/audit.md, docs/src/content/docs/reference/cost-management.md

Obstacle 4: Inconsistent Anthropic Console URLs and unclear `CLAUDE_CODE_OAUTH_TOKEN` handling

Impact: Three different URLs documented for creating the same API key, and a Claude Code user who already has CLAUDE_CODE_OAUTH_TOKEN configured locally will be confused to learn it is silently ignored.

Current State:

• quick-start.mdx:84 → console.anthropic.com/settings/keys
• auth.mdx:109 → platform.claude.com/docs/en/get-started
• auth.mdx:199 → console.anthropic.com

auth.mdx:121-123 does explicitly say CLAUDE_CODE_OAUTH_TOKEN is unsupported, which is good — but a Claude Code user might never read auth docs in detail.

Why It's Problematic: URL drift signals the docs are not being kept in sync; the OAuth caveat surprises Claude Code users who already use that token locally.

Suggested Fix: Pick one canonical URL (console.anthropic.com/settings/keys) and use it everywhere. Promote the OAuth-not-supported note from a buried subsection to a callout in the Quick Start whenever a user selects Claude.

Affected Files: docs/src/content/docs/setup/quick-start.mdx, docs/src/content/docs/reference/auth.mdx

💡 Minor Confusion Points (Score: 6/10)

• Gemini is advertised as supported but has zero in-repo example workflows — README.md:40 lists Gemini; counts: 0 .github/workflows/*.md files use engine: gemini. File: README.md, .github/workflows/
• engine: copilot # or claude, codex, custom comment in blog — custom is referenced but I could not find a custom engine reference page. Misleading. File: docs/src/content/docs/blog/2026-02-05-how-workflows-work.md:210
• "Claude Code" vs "Claude by Anthropic" terminology — engines.md:17 uses both names in one row. A Claude Code user might not realize that engine: claude is the Claude Code CLI. File: docs/src/content/docs/reference/engines.md
• Copilot BYOK section makes "using Claude" mean three different things — could confuse new Claude users into thinking they need BYOK. File: docs/src/content/docs/reference/engines.md:201-268
• tools.timeout defaults differ per engine but only Claude/Codex are documented — engines.md:381-388 says Copilot/Gemini/Crush are "not enforced by gh-aw (engine-managed)" — the meaning of that phrase is opaque.
• network.allowed configuration example in architecture.mdx:227-237 uses engine: copilot — even the security architecture overview uses Copilot in its illustration.

---

Engine Comparison Analysis

Available Engines

Based on engines.md:14-23 and README.md:40, gh-aw supports:

• engine: copilot — Documented thoroughly. Default. Setup well-described in Quick Start.
• engine: claude — Documented adequately. Engine reference and auth reference both cover it. Few worked examples in docs.
• engine: codex — Documented in reference but underrepresented in Quick Start examples.
• engine: gemini — Listed as supported, but has 0 example workflows in the repo and minimal docs coverage.
• engine: crush, opencode, pi — Listed as experimental in engines.md:20-22.
• engine: custom — Referenced once in a blog comment but I could not locate a reference page.

Documentation Quality by Engine

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

---

Tool Availability Analysis

Tools Review

Analyzed tool compatibility based on tools.md and engines.md:34-46:

Engine-Agnostic Tools:

• edit: — file editing
• bash: — shell commands (gated by Claude permission mode caveat, engines.md:439-470)
• github: — GitHub API toolsets (engine-agnostic protocol)
• playwright: — browser automation
• cache-memory:, repo-memory: — persistent memory
• qmd: — vector search
• agentic-workflows: — workflow introspection
• web-fetch: — universal (all engines per engines.md:39)
• mcp-servers: — engine-agnostic protocol

Engine-Specific Tools:

• web-search: — native on Codex (opt-in); requires third-party MCP for other engines (engines.md:40, tools.md:65-67).
• engine.agent — Copilot only.
• engine.harness — Copilot only.

Unclear/Undocumented:

• tools.cli-proxy: true (tools.md:129-149) — does it work consistently across all engines? Doc shows Copilot context (safeoutputs, mcpscripts mounted as CLIs) but no per-engine note.
• The Claude bypassPermissions quirk (engines.md:447-450) is a security caveat unique to Claude that's easy to miss when copy-pasting Copilot configs.

---

Authentication Requirements

Current Documentation

• ✅ Copilot — detailed Quick Start note + pre-filled PAT creation URL.
• ⚠️ Claude — covered in auth.mdx and quick-start.mdx, but inconsistent URLs (three different links) and CLAUDE_CODE_OAUTH_TOKEN rejection buried.
• ⚠️ Codex — covered, with CODEX_API_KEY / OPENAI_API_KEY fallback documented.
• ⚠️ Gemini — minimal coverage, no Quick Start setup note.
• ❌ "Custom" engine (referenced in blog comment) — no reference documentation found.

Missing for Claude Users

• A "why isn't CLAUDE_CODE_OAUTH_TOKEN supported?" explainer or roadmap note. Right now it's a one-paragraph rejection in auth.mdx:121-123.
• Cost/billing comparison — cost-management.md exists but its example is Copilot-only.
• Anthropic Console URL must be consistent across all docs.

Secret Names

• Copilot: COPILOT_GITHUB_TOKEN (documented)
• Claude: ANTHROPIC_API_KEY (documented; CLAUDE_CODE_OAUTH_TOKEN explicitly unsupported)
• Codex: OPENAI_API_KEY or CODEX_API_KEY (both documented)
• Gemini: GEMINI_API_KEY (documented)

---

Example Workflow Analysis

Workflow Count by Engine (in .github/workflows/)

Engine: copilot - 100+ workflows found
Engine: claude  -  52 workflows found
Engine: codex   -   9 workflows found
Engine: gemini  -   0 workflows found

In the documentation site (docs/src/content/docs/):

engine: copilot - ~40 snippets
engine: claude  -   5 snippets
engine: codex   -   1 snippet (network.md)
engine: gemini  -   1 snippet (network.md)

Quality of Examples

Copilot Examples: Comprehensive, varied, span every pattern (spec-ops, side-repo-ops, central-repo-ops, deterministic-ops, research-plan-assign-ops).

Claude Examples: Adequate to demonstrate the engine works, but a Claude-first user lacks a complete "reference workflow" in the docs that matches the comprehensiveness of Copilot examples. The deterministic-ops.md:71 Claude example is one of the most complete in the docs.

---

Recommended Actions

Priority 1: Critical Documentation Fixes

1. Reduce Copilot-first framing in Quick Start — bring Claude/Codex/Gemini setup notes to parity with Copilot's. File: docs/src/content/docs/setup/quick-start.mdx
2. Document gh aw init engine-specific behavior — add a note that the dispatcher agent file is Copilot-only. File: docs/src/content/docs/setup/cli.md
3. Unify Anthropic Console URLs — pick one canonical URL and use it everywhere. File: docs/src/content/docs/reference/auth.mdx, docs/src/content/docs/setup/quick-start.mdx

Priority 2: Major Improvements

1. Add Claude variants to pattern docs — at least one engine: claude example per pattern. File: docs/src/content/docs/patterns/*.md
2. Add an "engines comparison" section to how-they-work.mdx — surface the feature matrix earlier so users know what's portable. File: docs/src/content/docs/introduction/how-they-work.mdx
3. Document or remove the "custom" engine reference — engine: copilot # or claude, codex, custom in blog suggests custom exists; verify and document, or remove from comments. File: docs/src/content/docs/blog/2026-02-05-how-workflows-work.md
4. Add Gemini example workflows or downgrade Gemini messaging — zero in-repo Gemini workflows undermines the "pick any AI account" promise. File: README.md (or add Gemini workflows)

Priority 3: Nice-to-Have Enhancements

1. "Why choose Claude?" guidance — a paragraph in engines.md:26-28 would help non-Copilot users self-select.
2. Promote the CLAUDE_CODE_OAUTH_TOKEN rejection from buried subsection to a Quick Start callout — Claude Code users carrying that token locally will be surprised.
3. Clarify "Claude Code" terminology — make explicit that engine: claude is the Anthropic Claude Code CLI running inside the runner.
4. Cost comparison — cost-management.md should show side-by-side Copilot vs Claude vs Codex examples.

---

Positive Findings

What Works Well

• ✅ README.md:40 does mention all four engines up-front.
• ✅ The engine feature comparison table at engines.md:34-46 is excellent — clear, accurate, and honest about what's Copilot-only.
• ✅ auth.mdx covers all four engines in one reference page with consistent structure.
• ✅ The --engine flag is supported on gh aw new, gh aw add-wizard, gh aw compile, gh aw trial, gh aw run — so the CLI itself is genuinely engine-agnostic.
• ✅ gh aw secrets bootstrap --engine claude (cli.md:240-245) makes setup much easier for non-Copilot users.
• ✅ Security architecture (architecture.mdx) is engine-agnostic and applies equally to Claude workflows.
• ✅ max-turns is documented as a Claude-specific positive feature (engines.md:404-417), not framed as a limitation.
• ✅ The Claude permission mode security model (engines.md:439-470) is documented in depth — a real strength for security-conscious Claude users.

---

Conclusion

Can Claude Code Users Successfully Adopt gh-aw?

Answer: Yes, with significant effort and patience to read past Copilot-framed examples.

Reasoning: All the building blocks for a Claude-based gh-aw workflow exist and are documented somewhere. The CLI accepts --engine claude everywhere it matters. The auth reference, engine reference, and feature comparison table are honest and complete. But the path of least resistance documented in the Quick Start is Copilot-shaped, and a Claude user will spend their first hour translating Copilot-flavored snippets into Claude equivalents. There are no hard blockers — just enough friction that a less determined user might give up before reaching the working Claude workflow.

Overall Assessment Score: 6/10

Breakdown:

• Clarity for non-Copilot users: 6/10
• Claude engine documentation: 7/10
• Alternative approaches provided: 6/10
• Engine parity: 5/10

Next Steps

If the team can take only one action, add a Claude variant to the Quick Start (full setup, full example, full secret link) at parity with the Copilot variant. That single change removes most of the onboarding friction documented above.

If the team can take two actions, also add a note to gh aw init that the dispatcher agent file is Copilot-only so non-Copilot users aren't silently given dead scaffolding.

---

Appendix: Files Reviewed

Complete List of Documentation Files Analyzed

• README.md
• docs/src/content/docs/setup/quick-start.mdx
• docs/src/content/docs/setup/cli.md
• 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/reference/engines.md
• docs/src/content/docs/reference/auth.mdx
• Engine usage scan across docs/src/content/docs/ and .github/workflows/

---

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

Generated by 📝 Claude Code User Documentation Review · ● 15.5M · ◷

• expires on May 21, 2026, 1:26 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 #33757.