You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
I reviewed gh-aw documentation as a developer who uses Claude Code as my primary AI assistant and does not use GitHub Copilot. The good news: gh-aw genuinely supports Claude as a first-class engine — engines.md and auth.mdx document it clearly, the add-wizard flow lets me pick Claude, and there are no hard blockers preventing adoption. The harder news: the surrounding documentation is Copilot-first by gravity. The README never names Claude or any non-Copilot engine, the Quick Start has a Copilot-only secret setup callout with no Claude equivalent, code examples skew ~6.6:1 toward Copilot, and there is no Claude-specific guide under guides/.
Key Finding: A Claude Code user can adopt gh-aw, but has to assemble the path themselves by reading the reference pages (engines.md, auth.mdx) — the marketing surface (README, Quick Start) implicitly assumes Copilot.
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?
Yes, with friction. The Quick Start does list Claude as a choice in Step 2:
Select an AI Engine - Choose between Copilot, Claude, Codex, or Gemini.
Set up the required secret - COPILOT_GITHUB_TOKEN, ANTHROPIC_API_KEY, OPENAI_API_KEY, or GEMINI_API_KEY.
So the engine choice is surfaced. But the very next block is a Copilot-only NOTE:
Setting up COPILOT_GITHUB_TOKEN?
Create a fine-grained PAT under your user account.
Under Permissions → Account permissions, set Copilot Requests to Read...
There is no parallel "Setting up ANTHROPIC_API_KEY?" note. A Claude user has to context-switch to auth.mdx to find equivalent instructions.
Specific Issues Found:
README.md:32-34: The Quick Start callout never names alternative engines. A reader who doesn't already know gh-aw supports Claude/Codex/Gemini has no signal here.
README.md overall: The word "Claude" does not appear once. The word "Copilot" appears multiple times.
docs/src/content/docs/setup/quick-start.mdx:75-80: Copilot-only setup TIP without a Claude equivalent. The asymmetry suggests Copilot is the "real" path and Claude is a footnote option.
docs/src/content/docs/introduction/how-they-work.mdx:26: Engine support is mentioned, but Copilot is flagged "(default)" without ever showing what changes when you pick something else.
Recommended Fixes:
Add a one-line mention of alternative engines in the README Quick Start blurb: "gh-aw supports GitHub Copilot (default), Claude, Codex, and Gemini engines."
In quick-start.mdx, add a sibling NOTE block for ANTHROPIC_API_KEY mirroring the Copilot one, or refactor the secret-setup block into a tabbed/per-engine list.
Consider a "Choose your engine" section at the top of the Quick Start with a 4-row table linking to per-engine setup paths.
Question 2: Inaccessible Features for Non-Copilot Users
What features or steps don't work without Copilot?
The feature comparison table in engines.md:33-44 is honest and useful — kudos for publishing it. Concretely, Copilot-only features include:
engine.agent — custom agent files in .github/agents/. Note: copilot-custom-agents.md:8 clarifies that "Copilot supports agent files natively, while other engines (Claude, Codex) inject the markdown body as a prompt" — so it's a degraded experience, not a hard block.
All compilation, audit, logs, validate, fix, upgrade commands
BYOK via COPILOT_PROVIDER_BASE_URL — note this lets you route Copilot to Anthropic, but it's still framed as a Copilot mode
Where documentation is unclear:
gh aw init (cli.md:134) creates .github/agents/agentic-workflows.agent.md. The doc says "creates the dispatcher agent file" but doesn't say: Is this useful at all if I pick Claude? Given copilot-custom-agents.md is explicit that "Copilot supports agent files natively, while other engines (Claude, Codex) inject the markdown body as a prompt," the artifact is partially relevant — but a Claude user reading init's description has no idea.
web-search is "via MCP" for Claude (per engines.md:39). The pointer to /gh-aw/guides/web-search/ exists, but tools.md:65 says "Some engines require third-party MCP servers for web search" without explicit per-engine guidance until you click through.
Question 3: Documentation Gaps and Assumptions
Where does the documentation assume Copilot usage?
Copilot-Centric Language Found In:
README.md — zero non-Copilot engine names. Even the contents/overview lean Copilot-implicit.
docs/src/content/docs/introduction/architecture.mdx:188-191 — the AWF diagram explicitly labels the agent process as "Copilot CLI" + WebFetch + WebSearch. This is a security architecture diagram that ought to be engine-agnostic — most of those mechanisms apply equally to Claude. Calling the AI agent "COPILOT" in the diagram nodes (COPILOT["Copilot CLI"]) signals to a Claude user that the architecture is built for Copilot.
docs/src/content/docs/setup/cli.md:134 — gh aw init creates a "dispatcher agent file" without explaining how that artifact interacts with non-Copilot engines.
Engine examples imbalance (counted in docs/src/content/docs/):
Engine
Code-block occurrences
engine: copilot / id: copilot
99 (39 files)
engine: claude / id: claude
15 (11 files)
engine: codex / id: codex
5
engine: gemini / id: gemini
1
engine: crush
0 in code blocks
engine: opencode
0 in code blocks
In addition, the vast majority of examples in docs/src/content/docs/examples/ and docs/src/content/docs/patterns/ omit engine: entirely — relying on the Copilot default. This means a Claude user copy-pasting an example silently gets a workflow that won't run for them unless they add engine: claude and have ANTHROPIC_API_KEY set.
Missing Alternative Instructions:
No guides/claude-setup.md or equivalent. The docs/src/content/docs/guides/ directory has 18+ guides — for MCP, network config, packaging, self-hosted runners, audit, web search, etc. — but none for Claude (or any specific engine).
No "Why pick Claude over Copilot?" guidance beyond the one paragraph in engines.md:27.
No example workflows under docs/src/content/docs/examples/ that explicitly set engine: claude.
Severity-Categorized Findings
🚫 Critical Blockers (Score: 0/10 — none found)
Good news: I found no hard blockers that prevent a Claude Code user from adopting gh-aw. Claude is a fully supported, documented engine. add-wizard lets me pick it. ANTHROPIC_API_KEY is documented. The compiler, audit, logs, and safe-outputs subsystems all work with Claude.
⚠️ Major Obstacles (Score: 4/10)
Obstacle 1: README never mentions non-Copilot engines
Impact: First-impression mismatch — a Claude Code user reading the README has no signal that gh-aw is for them.
Current State:README.md references "Copilot" multiple times (in the ## ⚠️ retirement notice and prerequisites), but never names Claude, Codex, or Gemini.
Why It's Problematic: Many readers stop at the README. If their AI tool of choice isn't listed, they assume the tool isn't for them and move on. This is a discovery problem more than a documentation gap.
Suggested Fix: Add a single sentence to the Overview/Quick Start section: "Workflows can run on GitHub Copilot (default), Claude by Anthropic, OpenAI Codex, or Google Gemini." And/or replace the Copilot icon in any branding with engine logos.
Affected Files:README.md
Obstacle 2: Quick Start has a Copilot-only secret-setup callout with no Claude equivalent
Impact: Asymmetric onboarding — the documented happy path is implicitly Copilot.
Current State:quick-start.mdx:75-80 includes a step-by-step NOTE for creating COPILOT_GITHUB_TOKEN (fine-grained PAT with specific permissions). The matching Claude flow — get an Anthropic API key from console.anthropic.com — is only reachable by following a link to auth.mdx.
Why It's Problematic: A user who picked Claude during add-wizard then sees Copilot-only setup instructions on the Quick Start page and has to context-switch to find the Claude flow. It makes Claude feel like a second-class choice.
Suggested Fix: Replace the single NOTE with a tabbed block (Starlight supports tabs) or a per-engine collapsible section, so each engine gets equal-weight setup instructions inline.
Obstacle 3: Example/pattern workflows almost never set `engine:` explicitly
Impact: Copy-paste hazard — examples silently default to Copilot.
Current State: Across docs/src/content/docs/examples/ and docs/src/content/docs/patterns/, the vast majority of workflow code blocks omit engine: entirely. A Claude user copying one of these will get a workflow that fails (or silently uses Copilot if they have that token) unless they remember to add engine: claude.
Why It's Problematic: It's not a documentation falsehood — defaults are real — but it bakes Copilot-as-norm into every example. It also means a Claude user has 15 Claude examples to learn from versus 99 Copilot examples, even when the pattern itself is engine-agnostic.
Suggested Fix:
Add a doc-build linter that requires explicit engine: in every documentation example, OR
Add an editorial guideline that examples should cycle through engines, OR
At minimum, add a few engine: claude examples in the examples/ directory mirroring the existing scheduled / issue-triggered patterns.
Obstacle 4: No dedicated Claude (or per-engine) setup guide
Impact: The guides/ directory has 18+ topic guides but zero per-engine setup walkthroughs.
Current State: Claude is covered by the reference pages engines.md and auth.mdx. There is no equivalent of "Setting up your first Claude workflow end-to-end" — the kind of guide that would mirror the Quick Start but use Claude throughout.
Why It's Problematic: Reference pages answer "what fields exist?" Guides answer "how do I actually do this?" A Claude user has no narrative walkthrough — they have to compose one from engines.md + auth.mdx + the generic Quick Start.
Suggested Fix: Add docs/src/content/docs/guides/using-claude.md (or using-each-engine.md) with: get API key → store secret → write a engine: claude workflow → compile → run → observe in gh aw logs. Bonus: explain when to pick Claude (the engines.md:27 paragraph is a good seed).
Affected Files:docs/src/content/docs/guides/ (new file)
💡 Minor Confusion Points (Score: 6/10)
Architecture diagram labels say "Copilot CLI" — docs/src/content/docs/introduction/architecture.mdx:188-191 and the AWF section show COPILOT["Copilot CLI"] as the agent node. The mechanism is engine-agnostic; the diagram should label it "Agent CLI" or list all engines.
gh aw init ambiguity for non-Copilot users — cli.md:134 says it creates a "dispatcher agent file" without explaining whether/how this artifact applies to a Claude workflow.
gh aw new --engine claude is documented but not surfaced — cli.md:181 shows gh aw new my-workflow --engine claude, but this isn't promoted as the "Claude-first" entry point anywhere prominent.
engines.md:27 says "If you are unsure, start with Copilot" — this is reasonable framing for the typical reader but adds friction for someone who has already decided on Claude. Consider symmetrically presenting trade-offs.
crush and opencode engines have zero code examples — They're listed in the support matrix but a reader has no example to start from.
COPILOT_GITHUB_TOKEN is required for crush engine — engines.md:20 says Crush uses COPILOT_GITHUB_TOKEN. This is surprising and not explained — does "experimental Crush" actually require a Copilot subscription? If yes, that's a real blocker for those engines.
✅ Codex: auth.mdx:129-167 — both CODEX_API_KEY and OPENAI_API_KEY documented, Azure example included
✅ Gemini: auth.mdx:171-185 — straightforward
auth.mdx is good. The gap isn't auth.mdx itself — it's that Quick Start doesn't link to the Claude/Codex/Gemini auth sections with the same prominence as it links to Copilot.
Missing for Claude Users
No mention in the Quick Start that the Claude API key comes from console.anthropic.com (vs the Copilot PAT pre-fill link, which makes Copilot setup feel friction-free)
No callout about Claude pricing/rate limits versus Copilot (Copilot users have a subscription; Claude users pay per token)
Example Workflow Analysis
Workflow Count by Engine (in docs/src/content/docs/)
Engine: copilot - 99 occurrences across 39 files
Engine: claude - 15 occurrences across 11 files
Engine: codex - 5 occurrences across 5 files
Engine: gemini - 1 occurrence across 1 file
Engine: crush - 0 in code examples
Engine: opencode - 0 in code examples
Quality of Examples
Copilot Examples: Plentiful, varied, cover all major patterns (issue ops, multi-repo, scheduled, project ops, etc.).
Claude Examples: Present but mostly incidental — Claude appears in engines.md reference snippets, faq.md discussion, and a handful of patterns (research-plan-assign-ops, multi-repo-ops, examples/multi-repo.md). A Claude user looking for "show me a Claude workflow that does X" has thin pickings for most X.
Gemini/Codex Examples: Token presence only — borderline undocumented from a usage perspective.
Recommended Actions
Priority 1: Critical Documentation Fixes
(No critical fixes — gh-aw works for Claude users today. The Priority 2 list is what would unlock smooth adoption.)
Priority 2: Major Improvements
Add non-Copilot engine names to the README — even one sentence — File: README.md
Refactor Quick Start secret setup into per-engine tabs with a Claude callout matching the Copilot one — File: docs/src/content/docs/setup/quick-start.mdx
Add a guides/using-claude.md walkthrough mirroring the Quick Start but Claude-throughout — File: docs/src/content/docs/guides/using-claude.md (new)
Re-label architecture diagram nodes from "Copilot CLI" to engine-agnostic "Agent CLI" or include all four engines — File: docs/src/content/docs/introduction/architecture.mdx
Add at least 3 engine: claude examples under docs/src/content/docs/examples/ covering scheduled, issue-triggered, and PR-triggered patterns — File: docs/src/content/docs/examples/
Priority 3: Nice-to-Have Enhancements
Make engine: explicit in every documentation example to remove silent-default ambiguity
Document why Crush/OpenCode need COPILOT_GITHUB_TOKEN (or change that requirement)
Add a "When to use which engine?" decision matrix in engines.md beyond the current one paragraph
Add a "Migrating from Copilot to Claude" note (or vice-versa) covering which features behave differently
Add inline engine-comparison badges to feature reference pages (e.g., next to engine.agent, badge "Copilot only")
Positive Findings
What Works Well
✅ engines.md has an honest, well-structured feature parity table showing exactly what Copilot/Claude/Codex/Gemini support. This is exemplary technical writing — kudos.
✅ auth.mdx covers all four primary engines with equal depth and includes troubleshooting per engine.
✅ add-wizard interactive flow surfaces the engine choice explicitly and prompts for the right secret.
✅ gh aw new --engine claude does exist and injects the correct frontmatter — cli.md:181.
✅ The Claude security model (engines.md:437-471, bypassPermissions vs acceptEdits) is documented in serious detail — this is real Claude-specific engineering.
✅ BYOK section in engines.md:199-266 shows Anthropic and Azure providers as first-class examples, not just Copilot.
✅ Compilation, audit, logs, validate, fix, upgrade — all engine-agnostic and well-documented.
✅ auth.mdx:121-123 is explicit that CLAUDE_CODE_OAUTH_TOKEN is NOT supported. Being explicit about unsupported things is excellent docs hygiene.
Conclusion
Can Claude Code Users Successfully Adopt gh-aw?
Answer: Yes, with moderate effort.
Reasoning: Nothing in the documentation or product prevents a Claude Code user from using gh-aw — Claude is a documented, supported engine with auth, examples (sparse but present), and a security model spelled out in depth. The friction is discovery and framing: a reader who arrives via the README has no signal that Claude is supported, the Quick Start has Copilot-only setup callouts, and the examples skew 6.6:1 toward Copilot. A motivated reader who walks the reference pages will succeed. A casual visitor who scans the README and Quick Start may conclude the tool is Copilot-only and bounce.
Overall Assessment Score: 6.5/10
Breakdown:
Clarity for non-Copilot users: 7/10
Claude engine documentation: 6/10
Alternative approaches provided: 7/10
Engine parity: 6/10
Next Steps
The highest-leverage fixes are textual, not structural:
Three sentences added across README.md and quick-start.mdx would resolve most discovery problems.
One new guides/using-claude.md page would close the narrative-walkthrough gap.
A handful of engine: claude examples sprinkled into examples/ would correct the 6.6:1 imbalance signal.
The product is in good shape for non-Copilot users; the documentation surface just hasn't caught up to that fact yet.
reacted with thumbs up emoji reacted with thumbs down emoji reacted with laugh emoji reacted with hooray emoji reacted with confused emoji reacted with heart emoji reacted with rocket emoji reacted with eyes emoji
Uh oh!
There was an error while loading. Please reload this page.
-
Executive Summary
I reviewed gh-aw documentation as a developer who uses Claude Code as my primary AI assistant and does not use GitHub Copilot. The good news: gh-aw genuinely supports Claude as a first-class engine —
engines.mdandauth.mdxdocument it clearly, theadd-wizardflow lets me pick Claude, and there are no hard blockers preventing adoption. The harder news: the surrounding documentation is Copilot-first by gravity. The README never names Claude or any non-Copilot engine, the Quick Start has a Copilot-only secret setup callout with no Claude equivalent, code examples skew ~6.6:1 toward Copilot, and there is no Claude-specific guide underguides/.Key Finding: A Claude Code user can adopt gh-aw, but has to assemble the path themselves by reading the reference pages (
engines.md,auth.mdx) — the marketing surface (README, Quick Start) implicitly assumes Copilot.Persona Context
I reviewed this documentation as a developer who:
Question 1: Onboarding Experience
Can a Claude Code user understand and get started with gh-aw?
Yes, with friction. The Quick Start does list Claude as a choice in Step 2:
So the engine choice is surfaced. But the very next block is a Copilot-only NOTE:
There is no parallel "Setting up
ANTHROPIC_API_KEY?" note. A Claude user has to context-switch toauth.mdxto find equivalent instructions.Specific Issues Found:
README.md:32-34: The Quick Start callout never names alternative engines. A reader who doesn't already know gh-aw supports Claude/Codex/Gemini has no signal here.README.mdoverall: The word "Claude" does not appear once. The word "Copilot" appears multiple times.docs/src/content/docs/setup/quick-start.mdx:75-80: Copilot-only setup TIP without a Claude equivalent. The asymmetry suggests Copilot is the "real" path and Claude is a footnote option.docs/src/content/docs/introduction/how-they-work.mdx:26: Engine support is mentioned, but Copilot is flagged "(default)" without ever showing what changes when you pick something else.Recommended Fixes:
quick-start.mdx, add a sibling NOTE block forANTHROPIC_API_KEYmirroring the Copilot one, or refactor the secret-setup block into a tabbed/per-engine list.Question 2: Inaccessible Features for Non-Copilot Users
What features or steps don't work without Copilot?
The feature comparison table in
engines.md:33-44is honest and useful — kudos for publishing it. Concretely, Copilot-only features include:engine.agent— custom agent files in.github/agents/. Note:copilot-custom-agents.md:8clarifies that "Copilot supports agent files natively, while other engines (Claude, Codex) inject the markdown body as a prompt" — so it's a degraded experience, not a hard block.engine.harness— custom Node.js harness wrapper (Copilot-only)max-continuations— autopilot-style multi-run mode (Copilot-only)assign-to-copilotsafe output — by definition Copilot-specificClaude-only:
max-turns(iteration budget).Engine-agnostic (work the same for Claude):
tools: github:,bash:,edit:,web-fetch:,playwright:,cache-memory:,repo-memory:,qmd:,agentic-workflows:,cli-proxy:mcp-servers:(custom MCP)safe-outputs:(exceptassign-to-copilot)COPILOT_PROVIDER_BASE_URL— note this lets you route Copilot to Anthropic, but it's still framed as a Copilot modeWhere documentation is unclear:
gh aw init(cli.md:134) creates.github/agents/agentic-workflows.agent.md. The doc says "creates the dispatcher agent file" but doesn't say: Is this useful at all if I pick Claude? Givencopilot-custom-agents.mdis explicit that "Copilot supports agent files natively, while other engines (Claude, Codex) inject the markdown body as a prompt," the artifact is partially relevant — but a Claude user readinginit's description has no idea.web-searchis "via MCP" for Claude (perengines.md:39). The pointer to/gh-aw/guides/web-search/exists, buttools.md:65says "Some engines require third-party MCP servers for web search" without explicit per-engine guidance until you click through.Question 3: Documentation Gaps and Assumptions
Where does the documentation assume Copilot usage?
Copilot-Centric Language Found In:
README.md— zero non-Copilot engine names. Even the contents/overview lean Copilot-implicit.docs/src/content/docs/setup/quick-start.mdx:75-80— Copilot-only secret calloutdocs/src/content/docs/introduction/architecture.mdx:188-191— the AWF diagram explicitly labels the agent process as "Copilot CLI" + WebFetch + WebSearch. This is a security architecture diagram that ought to be engine-agnostic — most of those mechanisms apply equally to Claude. Calling the AI agent "COPILOT" in the diagram nodes (COPILOT["Copilot CLI"]) signals to a Claude user that the architecture is built for Copilot.docs/src/content/docs/introduction/architecture.mdx:281—ENGINE["AI Engine<br/>(Copilot, Claude, Codex)"]— better here, lists multiple engines (and forgets Gemini).docs/src/content/docs/setup/cli.md:134—gh aw initcreates a "dispatcher agent file" without explaining how that artifact interacts with non-Copilot engines.Engine examples imbalance (counted in
docs/src/content/docs/):engine: copilot/id: copilotengine: claude/id: claudeengine: codex/id: codexengine: gemini/id: geminiengine: crushengine: opencodeIn addition, the vast majority of examples in
docs/src/content/docs/examples/anddocs/src/content/docs/patterns/omitengine:entirely — relying on the Copilot default. This means a Claude user copy-pasting an example silently gets a workflow that won't run for them unless they addengine: claudeand haveANTHROPIC_API_KEYset.Missing Alternative Instructions:
guides/claude-setup.mdor equivalent. Thedocs/src/content/docs/guides/directory has 18+ guides — for MCP, network config, packaging, self-hosted runners, audit, web search, etc. — but none for Claude (or any specific engine).engines.md:27.docs/src/content/docs/examples/that explicitly setengine: claude.Severity-Categorized Findings
🚫 Critical Blockers (Score: 0/10 — none found)
Good news: I found no hard blockers that prevent a Claude Code user from adopting gh-aw. Claude is a fully supported, documented engine.
add-wizardlets me pick it.ANTHROPIC_API_KEYis documented. The compiler, audit, logs, and safe-outputs subsystems all work with Claude.Obstacle 1: README never mentions non-Copilot engines
Impact: First-impression mismatch — a Claude Code user reading the README has no signal that gh-aw is for them.
Current State:
README.mdreferences "Copilot" multiple times (in the## ⚠️retirement notice and prerequisites), but never names Claude, Codex, or Gemini.Why It's Problematic: Many readers stop at the README. If their AI tool of choice isn't listed, they assume the tool isn't for them and move on. This is a discovery problem more than a documentation gap.
Suggested Fix: Add a single sentence to the Overview/Quick Start section: "Workflows can run on GitHub Copilot (default), Claude by Anthropic, OpenAI Codex, or Google Gemini." And/or replace the Copilot icon in any branding with engine logos.
Affected Files:
README.mdObstacle 2: Quick Start has a Copilot-only secret-setup callout with no Claude equivalent
Impact: Asymmetric onboarding — the documented happy path is implicitly Copilot.
Current State:
quick-start.mdx:75-80includes a step-by-step NOTE for creatingCOPILOT_GITHUB_TOKEN(fine-grained PAT with specific permissions). The matching Claude flow — get an Anthropic API key from console.anthropic.com — is only reachable by following a link toauth.mdx.Why It's Problematic: A user who picked Claude during
add-wizardthen sees Copilot-only setup instructions on the Quick Start page and has to context-switch to find the Claude flow. It makes Claude feel like a second-class choice.Suggested Fix: Replace the single NOTE with a tabbed block (Starlight supports tabs) or a per-engine collapsible section, so each engine gets equal-weight setup instructions inline.
Affected Files:
docs/src/content/docs/setup/quick-start.mdxObstacle 3: Example/pattern workflows almost never set `engine:` explicitly
Impact: Copy-paste hazard — examples silently default to Copilot.
Current State: Across
docs/src/content/docs/examples/anddocs/src/content/docs/patterns/, the vast majority of workflow code blocks omitengine:entirely. A Claude user copying one of these will get a workflow that fails (or silently uses Copilot if they have that token) unless they remember to addengine: claude.Why It's Problematic: It's not a documentation falsehood — defaults are real — but it bakes Copilot-as-norm into every example. It also means a Claude user has 15 Claude examples to learn from versus 99 Copilot examples, even when the pattern itself is engine-agnostic.
Suggested Fix:
engine:in every documentation example, ORengine: claudeexamples in theexamples/directory mirroring the existing scheduled / issue-triggered patterns.Affected Files:
docs/src/content/docs/examples/*,docs/src/content/docs/patterns/*Obstacle 4: No dedicated Claude (or per-engine) setup guide
Impact: The
guides/directory has 18+ topic guides but zero per-engine setup walkthroughs.Current State: Claude is covered by the reference pages
engines.mdandauth.mdx. There is no equivalent of "Setting up your first Claude workflow end-to-end" — the kind of guide that would mirror the Quick Start but use Claude throughout.Why It's Problematic: Reference pages answer "what fields exist?" Guides answer "how do I actually do this?" A Claude user has no narrative walkthrough — they have to compose one from
engines.md+auth.mdx+ the generic Quick Start.Suggested Fix: Add
docs/src/content/docs/guides/using-claude.md(orusing-each-engine.md) with: get API key → store secret → write aengine: claudeworkflow → compile → run → observe ingh aw logs. Bonus: explain when to pick Claude (theengines.md:27paragraph is a good seed).Affected Files:
docs/src/content/docs/guides/(new file)💡 Minor Confusion Points (Score: 6/10)
docs/src/content/docs/introduction/architecture.mdx:188-191and the AWF section showCOPILOT["Copilot CLI"]as the agent node. The mechanism is engine-agnostic; the diagram should label it "Agent CLI" or list all engines.gh aw initambiguity for non-Copilot users —cli.md:134says it creates a "dispatcher agent file" without explaining whether/how this artifact applies to a Claude workflow.gh aw new --engine claudeis documented but not surfaced —cli.md:181showsgh aw new my-workflow --engine claude, but this isn't promoted as the "Claude-first" entry point anywhere prominent.engines.md:27says "If you are unsure, start with Copilot" — this is reasonable framing for the typical reader but adds friction for someone who has already decided on Claude. Consider symmetrically presenting trade-offs.crushandopencodeengines have zero code examples — They're listed in the support matrix but a reader has no example to start from.COPILOT_GITHUB_TOKENis required forcrushengine —engines.md:20says Crush usesCOPILOT_GITHUB_TOKEN. This is surprising and not explained — does "experimental Crush" actually require a Copilot subscription? If yes, that's a real blocker for those engines.Engine Comparison Analysis
Available Engines
engine:valuecopilotclaudecodexgeminicrushopencodeTool Availability Analysis
Engine-Agnostic Tools (work the same for Claude):
github:,bash:,edit:,web-fetch:,playwright:,cache-memory:,repo-memory:,qmd:,agentic-workflows:,cli-proxy:,mcp-servers:, all safe-outputs exceptassign-to-copilotEngine-Specific Tools / Features:
engine.agent(custom agent file) — Copilot-only (degrades to prompt-injection for other engines)engine.harness— Copilot-onlymax-continuations— Copilot-onlymax-turns— Claude-onlyassign-to-copilotsafe output — Copilot-only by definitionweb-search— Codex has native; others use third-party MCPUnclear / Undocumented:
agentic-workflows.agent.mdfile created bygh aw initbenefit Claude workflows in any way, or is it dead code for them?COPILOT_GITHUB_TOKENis genuinely unexplained.Authentication Requirements
Current Documentation Quality
auth.mdx:76-99— detailed instructions, troubleshooting, pre-filled PAT creation linkauth.mdx:103-125— Anthropic API key documented, custom endpoints,CLAUDE_CODE_OAUTH_TOKENexplicitly unsupported (good clarity)auth.mdx:129-167— bothCODEX_API_KEYandOPENAI_API_KEYdocumented, Azure example includedauth.mdx:171-185— straightforwardauth.mdxis good. The gap isn't auth.mdx itself — it's that Quick Start doesn't link to the Claude/Codex/Gemini auth sections with the same prominence as it links to Copilot.Missing for Claude Users
console.anthropic.com(vs the Copilot PAT pre-fill link, which makes Copilot setup feel friction-free)Example Workflow Analysis
Workflow Count by Engine (in
docs/src/content/docs/)Quality of Examples
Copilot Examples: Plentiful, varied, cover all major patterns (issue ops, multi-repo, scheduled, project ops, etc.).
Claude Examples: Present but mostly incidental — Claude appears in
engines.mdreference snippets,faq.mddiscussion, and a handful of patterns (research-plan-assign-ops,multi-repo-ops,examples/multi-repo.md). A Claude user looking for "show me a Claude workflow that does X" has thin pickings for most X.Gemini/Codex Examples: Token presence only — borderline undocumented from a usage perspective.
Recommended Actions
Priority 1: Critical Documentation Fixes
(No critical fixes — gh-aw works for Claude users today. The Priority 2 list is what would unlock smooth adoption.)
Priority 2: Major Improvements
README.mddocs/src/content/docs/setup/quick-start.mdxguides/using-claude.mdwalkthrough mirroring the Quick Start but Claude-throughout — File:docs/src/content/docs/guides/using-claude.md(new)docs/src/content/docs/introduction/architecture.mdxengine: claudeexamples underdocs/src/content/docs/examples/covering scheduled, issue-triggered, and PR-triggered patterns — File:docs/src/content/docs/examples/Priority 3: Nice-to-Have Enhancements
engine:explicit in every documentation example to remove silent-default ambiguityCOPILOT_GITHUB_TOKEN(or change that requirement)engines.mdbeyond the current one paragraphengine.agent, badge "Copilot only")Positive Findings
What Works Well
engines.mdhas an honest, well-structured feature parity table showing exactly what Copilot/Claude/Codex/Gemini support. This is exemplary technical writing — kudos.auth.mdxcovers all four primary engines with equal depth and includes troubleshooting per engine.add-wizardinteractive flow surfaces the engine choice explicitly and prompts for the right secret.gh aw new --engine claudedoes exist and injects the correct frontmatter —cli.md:181.engines.md:437-471,bypassPermissionsvsacceptEdits) is documented in serious detail — this is real Claude-specific engineering.engines.md:199-266shows Anthropic and Azure providers as first-class examples, not just Copilot.auth.mdx:121-123is explicit thatCLAUDE_CODE_OAUTH_TOKENis NOT supported. Being explicit about unsupported things is excellent docs hygiene.Conclusion
Can Claude Code Users Successfully Adopt gh-aw?
Answer: Yes, with moderate effort.
Reasoning: Nothing in the documentation or product prevents a Claude Code user from using gh-aw — Claude is a documented, supported engine with auth, examples (sparse but present), and a security model spelled out in depth. The friction is discovery and framing: a reader who arrives via the README has no signal that Claude is supported, the Quick Start has Copilot-only setup callouts, and the examples skew 6.6:1 toward Copilot. A motivated reader who walks the reference pages will succeed. A casual visitor who scans the README and Quick Start may conclude the tool is Copilot-only and bounce.
Overall Assessment Score: 6.5/10
Breakdown:
Next Steps
The highest-leverage fixes are textual, not structural:
README.mdandquick-start.mdxwould resolve most discovery problems.guides/using-claude.mdpage would close the narrative-walkthrough gap.engine: claudeexamples sprinkled intoexamples/would correct the 6.6:1 imbalance signal.The product is in good shape for non-Copilot users; the documentation surface just hasn't caught up to that fact yet.
Appendix: Files Reviewed
README.mddocs/src/content/docs/setup/quick-start.mdxdocs/src/content/docs/setup/cli.mddocs/src/content/docs/introduction/how-they-work.mdxdocs/src/content/docs/introduction/architecture.mdxdocs/src/content/docs/reference/tools.mddocs/src/content/docs/reference/engines.mddocs/src/content/docs/reference/auth.mdxdocs/src/content/docs/reference/copilot-custom-agents.mddocs/src/content/docs/**/*.{md,mdx}Workflow Run: §25672760581
Beta Was this translation helpful? Give feedback.
All reactions