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

[github-actions]

Executive Summary

As a Claude Code user reviewing the gh-aw documentation, I found that Claude users CAN successfully adopt gh-aw, but the documentation has a Copilot-first orientation that creates initial friction during onboarding. Once users understand that Claude is a first-class supported engine (which becomes clear in the Engines documentation), the experience is excellent.

Key Finding: The project supports Claude extremely well in practice (29+ Claude workflows, excellent auth docs, engine-agnostic tools), but the Quick Start and Prerequisites sections create a perception that Copilot is the primary/recommended option rather than presenting engines as equal choices.

Overall Assessment Score: 8.0/10 - Good support for Claude users with room for improvement in initial messaging.

---

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?

Answer: Yes, but with moderate initial friction.

The Quick Start guide (docs/src/content/docs/setup/quick-start.mdx) is well-structured and the gh aw add-wizard command does provide engine selection. However, a Claude user reading the documentation for the first time encounters these friction points:

Positive aspects:

• Prerequisites clearly state "GitHub Copilot subscription, or an Anthropic Claude or OpenAI Codex API key"
• The wizard command (gh aw add-wizard) prompts for engine selection interactively
• Step 4 references comprehensive engine documentation

Friction points:

1. Copilot mentioned first everywhere - In Prerequisites, Copilot is listed first, creating perception it's the primary option
2. "AI Account" wording is vague - Doesn't clearly communicate that all engines are equally supported
3. No upfront engine choice callout - Quick Start doesn't have a prominent "Choose your AI engine" section before diving into installation

Specific Issues Found:

• File: docs/src/content/docs/setup/quick-start.mdx:17-21
  • Current text: "AI Account - a GitHub Copilot subscription, or an Anthropic Claude or OpenAI Codex API key"
  • Issue: Copilot listed first creates hierarchy perception
  • Impact: Claude users may wonder if they're using a "secondary" option

Recommended Fixes:

1. Add a prominent callout at the top of Quick Start:

   > **Choose Your AI Engine**  
   > GitHub Agentic Workflows supports three equally-capable AI engines:
   > - **GitHub Copilot** - Integrated with your GitHub subscription
   > - **Claude by Anthropic** - API key-based access
   > - **OpenAI Codex** - API key-based access
   > 
   > All engines provide the same workflow capabilities. Select the one you prefer.

2. Reword Prerequisites to show equal prominence:

   - **AI Engine Access** (choose one):
     - GitHub Copilot subscription, **OR**
     - Anthropic Claude API key, **OR**  
     - OpenAI Codex API key

---

Question 2: Inaccessible Features for Non-Copilot Users

What features or steps don't work without Copilot?

Answer: Almost nothing! Engine parity is excellent.

After thorough review, I found that virtually all features work identically across engines. This is a major strength of gh-aw's architecture.

Features That Work Without Copilot:

• ✅ All workflow triggers (schedule, workflow_dispatch, pull_request, issues, etc.)
• ✅ All tools (GitHub, Playwright, MCP servers, bash, edit, web-fetch, web-search)
• ✅ All safe outputs (create-issue, create-pull-request, create-discussion, etc.)
• ✅ Network permissions and firewall configuration
• ✅ Imports and shared workflow components
• ✅ Strict mode and security features
• ✅ Compilation, testing, and deployment
• ✅ All CLI commands (compile, run, logs, audit, status, etc.)

Features Exclusive to Copilot Engine:

• ❌ create-agent-session safe output (requires Copilot)
• ❌ Assigning copilot as issue assignee (requires Copilot)
• ❌ Copilot Custom Agents (.github/agents/*.agent.md files)
• ❌ assign-to-agent safe output (Copilot-specific bot assignment)

Documentation Status:

• ✅ Well-documented: The Tokens documentation clearly marks COPILOT_GITHUB_TOKEN as "for Copilot operations including the Copilot engine, agent sessions, and bot assignments"
• ✅ Clear boundaries: Safe Outputs documentation explicitly states which outputs require Copilot
• ✅ No false promises: Documentation doesn't suggest Claude/Codex can do Copilot-specific features

Missing Documentation:
None identified. The boundaries between engine-agnostic and Copilot-specific features are clearly documented.

---

Question 3: Documentation Gaps and Assumptions

Where does the documentation assume Copilot usage?

Answer: Primarily in Quick Start and How It Works introductory sections.

Copilot-Centric Language Found In:

1. File: docs/src/content/docs/introduction/how-they-work.mdx:21

   • Text: "Workflows support GitHub Copilot (default), Claude by Anthropic, and Codex"
   • Issue: States "default" without explaining users can override it
   • Impact: Creates perception that Copilot is the intended/recommended engine
   • Fix: "Workflows support GitHub Copilot, Claude by Anthropic, and Codex. Copilot is used when no engine is specified."

2. File: README.md

   • Issue: Main README doesn't mention engine choice at all
   • Impact: Users reading GitHub repo README don't know they have options
   • Fix: Add to Overview section: "Choose from GitHub Copilot, Claude, or Codex as your AI engine."

3. File: docs/src/content/docs/setup/quick-start.mdx (Prerequisites)

   • Already documented above in Question 1

4. File: docs/src/content/docs/index.mdx:40

   • Text: "Use GitHub Copilot, Claude by Anthropic or OpenAI Codex..."
   • Issue: Good! This one actually does it right - equal prominence
   • No fix needed

Missing Alternative Instructions:

I found NO critical missing alternative instructions - this is excellent! Once you get past the Quick Start, the documentation is thoroughly engine-agnostic:

• ✅ Engines documentation has dedicated sections for each engine with equal detail
• ✅ Tokens documentation covers ANTHROPIC_API_KEY with same thoroughness as COPILOT_GITHUB_TOKEN
• ✅ Tools documentation is completely engine-agnostic
• ✅ Safe Outputs documentation is engine-agnostic (except for explicitly Copilot-only features)
• ✅ Network, permissions, imports - all engine-agnostic

---

Severity-Categorized Findings

🚫 Critical Blockers (Score: 0/10)

None found!

This is excellent news. There are zero critical blockers preventing Claude Code users from successfully adopting gh-aw.

⚠️ Major Obstacles (Score: 2/10)

Obstacle 1: Copilot-First Quick Start Guide

Impact: Creates initial confusion and perception that Claude is a "secondary" option

Current State:
The Quick Start guide (docs/src/content/docs/setup/quick-start.mdx) uses the gh aw add-wizard command which does prompt for engine selection, but the surrounding text doesn't clearly state upfront that Claude is a fully supported, first-class alternative.

Why It's Problematic:
A Claude Code user reading the Quick Start doesn't see an explicit "Choose your AI engine" step. They have to infer from the Prerequisites that Claude is an option, and there's no messaging that all engines have equal capabilities.

Suggested Fix:
Add a prominent callout section after the introduction and before Step 1:

## Choose Your AI Engine

GitHub Agentic Workflows works with three AI engines - **all with equal capabilities**:

- **GitHub Copilot** - Uses your GitHub Copilot subscription
- **Claude by Anthropic** - Requires Anthropic API key ([get one here](https://console.anthropic.com/api-keys))
- **OpenAI Codex** - Requires OpenAI API key ([get one here]((platform.openai.com/redacted)

The `gh aw add-wizard` command (Step 2 below) will guide you through engine selection and secret setup.

Affected Files: docs/src/content/docs/setup/quick-start.mdx (lines 1-30)

Obstacle 2: Prerequisites Don't Show Equal Prominence

Impact: Creates perception hierarchy where Copilot appears to be the recommended option

Current State:
Prerequisites section states: "AI Account - a GitHub Copilot subscription, or an Anthropic Claude or OpenAI Codex API key"

Why It's Problematic:
The phrasing "A, or B or C" creates a grammatical hierarchy. In English, this structure typically means "ideally A, but alternatively B or C." This is likely unintentional, but it subtly suggests Copilot is the primary option.

Suggested Fix:
Rephrase to show equal footing:

- **AI Engine Access** (choose one of the following):
  - GitHub Copilot subscription, **OR**
  - Anthropic Claude API key ([create key](https://console.anthropic.com/api-keys)), **OR**
  - OpenAI Codex API key ([create key]((platform.openai.com/redacted)

Affected Files: docs/src/content/docs/setup/quick-start.mdx (lines 17-21)

💡 Minor Confusion Points (Score: 3/10)

• Issue 1: "Default engine" mentioned in How It Works without explaining override - File: docs/src/content/docs/introduction/how-they-work.mdx:21
• Issue 2: README doesn't mention engine choice availability - File: README.md (lines 15-30)
• Issue 3: Creating Workflows guide focuses on Copilot terminology ("coding agent" used interchangeably without defining for non-Copilot users first) - File: docs/src/content/docs/setup/creating-workflows.mdx

---

Engine Comparison Analysis

Available Engines

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

Engine	Documentation Quality	Setup Complexity	Example Workflows	Notes
GitHub Copilot	⭐⭐⭐⭐⭐ Excellent	Medium (needs fine-grained PAT)	71+ workflows	Default engine, most examples
Claude by Anthropic	⭐⭐⭐⭐⭐ Excellent	Easy (just API key)	29+ workflows	Well-supported, clear docs
OpenAI Codex	⭐⭐⭐⭐ Good	Easy (just API key)	9 workflows	Less examples but documented

Documentation Quality by Engine

Engine	Setup Docs	Examples	Auth Docs	Overall Score
Copilot	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐ (5.0/5)
Claude	⭐⭐⭐⭐⭐	⭐⭐⭐⭐	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐ (4.7/5)
Codex	⭐⭐⭐⭐	⭐⭐⭐	⭐⭐⭐⭐	⭐⭐⭐⭐ (3.7/5)

Key Observations:

• Claude has excellent setup and auth documentation - equivalent to Copilot
• Claude has good but fewer workflow examples - 29 vs 71 for Copilot
• All engines appear to have full feature parity except for Copilot-specific bot features
• No Claude-specific limitations found in any tools or safe outputs

---

Tool Availability Analysis

Tools Review

Analyzed all tools documented in docs/src/content/docs/reference/tools.md:

Engine-Agnostic Tools (Work with Any Engine):

• ✅ edit: - File editing in workspace
• ✅ bash: - Shell command execution
• ✅ web-fetch: - Web content fetching
• ✅ web-search: - Web search capabilities
• ✅ github: - GitHub API operations (all toolsets)
• ✅ playwright: - Browser automation
• ✅ agentic-workflows: - Workflow introspection
• ✅ cache-memory: - Persistent memory storage
• ✅ repo-memory: - Repository memory storage
• ✅ mcp-servers: - Custom MCP integrations

Engine-Specific Tools:

• ❌ None found for Claude limitations
• ℹ️ create-agent-session safe output is Copilot-only (documented clearly)

Unclear/Undocumented:

• None found

Verdict: Tool availability is 100% engine-agnostic with the exception of explicitly Copilot-specific bot interaction features (which are clearly documented as such).

---

Authentication Requirements

Current Documentation

Quick Start guide covers authentication for:

• ✅ Copilot: Detailed instructions with video walkthrough for fine-grained PAT creation
• ✅ Claude: Found in Engines documentation with clear API key instructions
• ✅ Codex: Found in Engines documentation with clear API key instructions

Claude Authentication Documentation Quality

Engines Documentation (docs/src/content/docs/reference/engines.md):

## Using Claude by Anthropic (Claude Code)

1. Request the use of the Claude by Anthropic engine in your workflow frontmatter:

   ```yaml
   engine: claude
   ```

2. Configuring `ANTHROPIC_API_KEY`

   Create an Anthropic API key at (https://console.anthropic.com/api-keys) and add it to your repository:

   ```bash
   gh aw secrets set ANTHROPIC_API_KEY --value "(your-anthropic-api-key)"
   ```
```

**Assessment:** ⭐⭐⭐⭐⭐ **Excellent** - Clear, concise, actionable

**Tokens Documentation** (`docs/src/content/docs/reference/tokens.md`):
- Doesn't have a dedicated section for `ANTHROPIC_API_KEY` (unlike `COPILOT_GITHUB_TOKEN`, `GH_AW_GITHUB_TOKEN`, etc.)
- But this is fine - Anthropic token is simpler and doesn't need the same level of detail

### Secret Names

| Engine | Secret Name | Documented | Setup Instructions |
|--------|------------|------------|-------------------|
| Copilot | `COPILOT_GITHUB_TOKEN` | ✅ Comprehensive | Video + detailed steps for fine-grained PAT |
| Claude | `ANTHROPIC_API_KEY` | ✅ Clear | Simple API key creation + CLI command |
| Codex | `OPENAI_API_KEY` | ✅ Clear | Simple API key creation + CLI command |

### Missing for Claude Users

**Nothing critical is missing.** The authentication documentation for Claude is actually simpler and clearer than Copilot's (because it's just an API key, not a complex fine-grained PAT setup).

**One minor enhancement opportunity:**
- Could add `ANTHROPIC_API_KEY` to the Tokens reference page for completeness (even if it just points to the Engines page)

---

## Example Workflow Analysis

### Workflow Count by Engine

```
Engine: copilot - 71 workflows found (explicitly set)
Engine: claude  - 29 workflows found (explicitly set)
Engine: codex   - 9 workflows found (explicitly set)
Default (implicitly Copilot) - 22 workflows found

Total workflows analyzed: ~130+

Quality of Examples

Copilot Examples:

• ⭐⭐⭐⭐⭐ Excellent variety covering all use cases
• Examples include: issue triage, CI coaching, code simplification, documentation, metrics, security scanning
• Well-distributed across simple and complex workflows

Claude Examples:

• ⭐⭐⭐⭐ Good coverage of major use cases
• Notable examples:
  • audit-workflows.md - Workflow analysis
  • claude-code-user-docs-review.md - Documentation review (this very workflow!)
  • smoke-claude.md - Integration testing
  • daily-doc-updater.md - Documentation maintenance
  • blog-auditor.md - Content review
• Shows Claude is actively used for production workflows, not just "also supported"

Codex Examples:

• ⭐⭐⭐ Adequate but fewer examples
• Examples include: smoke tests, GitHub remote MCP tests, performance summaries
• Sufficient to demonstrate usage patterns

Assessment

The 29 Claude workflows demonstrate that Claude is a first-class, actively-used engine in this project. The ratio (71 Copilot : 29 Claude : 9 Codex) suggests:

1. Copilot is the most common choice (likely due to GitHub integration)
2. Claude is well-adopted and trusted for production use
3. All engines are used for similar workflow patterns (no engine-specific limitations visible)

---

Recommended Actions

Priority 1: Critical Documentation Fixes

1. Add "Choose Your AI Engine" callout to Quick Start - Estimated effort: 15 minutes

   • Why it's critical: First impression for new users
   • File: docs/src/content/docs/setup/quick-start.mdx
   • Impact: Immediately clarifies that all engines are equal options

2. Update Prerequisites to show equal prominence - Estimated effort: 5 minutes

   • Why it's critical: Sets expectations correctly from the start
   • File: docs/src/content/docs/setup/quick-start.mdx
   • Impact: Eliminates perception that Copilot is "recommended"

Priority 2: Major Improvements

1. Clarify "default engine" language in How It Works - Estimated effort: 10 minutes

   • Why it matters: Reduces confusion about what "default" means
   • File: docs/src/content/docs/introduction/how-they-work.mdx
   • Impact: Makes engine selection feel more intentional

2. Add engine choice mention to README - Estimated effort: 5 minutes

   • Why it matters: GitHub repo visitors see it first
   • File: README.md
   • Impact: Increases awareness that gh-aw is engine-agnostic

3. Create "Choosing an AI Engine" comparison page - Estimated effort: 30 minutes

   • Why it matters: Helps users make informed decisions
   • Location: New file docs/src/content/docs/guides/choosing-an-engine.md
   • Content: Feature comparison, cost comparison, when to use each
   • Impact: Reduces decision paralysis, increases confidence

Priority 3: Nice-to-Have Enhancements

1. Add more Claude workflow examples - Estimated effort: Ongoing

   • Why it would help: Demonstrates Claude capabilities more broadly
   • Current gap: 29 Claude vs 71 Copilot workflows is fine, but more variety in Claude examples would help

2. Add video walkthrough for Claude setup - Estimated effort: 20 minutes

   • Why it would help: Matches the excellent Copilot video walkthroughs
   • Current state: Copilot has video guides, Claude has text-only
   • Impact: Visual learners would benefit

3. Add ANTHROPIC_API_KEY section to Tokens page - Estimated effort: 10 minutes

   • Why it would help: Completeness and discoverability
   • Current state: Covered in Engines page but not in Tokens reference
   • Impact: Minor - helps users cross-referencing documentation

---

Positive Findings

What Works Well for Claude Code Users

• ✅ Excellent engine parity - Virtually all features work identically across engines
• ✅ Clear, actionable Claude setup docs - The Engines page is excellent
• ✅ Simple authentication - Just an API key, no complex PAT configuration
• ✅ Active Claude usage - 29+ workflows show this is production-ready, not experimental
• ✅ Engine-agnostic architecture - Tools, safe outputs, network, permissions all work the same
• ✅ Interactive CLI - gh aw init and gh aw add-wizard prompt for engine selection
• ✅ Good examples - The smoke-claude.md and claude-code-user-docs-review.md workflows show real usage
• ✅ Transparent boundaries - Copilot-only features are clearly documented as such
• ✅ No hidden Copilot dependencies - Nothing requires Copilot except explicitly Copilot-specific features
• ✅ Cost transparency - FAQ clearly explains billing per engine type
• ✅ Easy switching - Changing engine: claude in frontmatter is all you need

---

Conclusion

Can Claude Code Users Successfully Adopt gh-aw?

Answer: Yes, absolutely!

Reasoning:

After comprehensive review of documentation, workflows, tools, and architecture, I can confidently state that Claude Code users can successfully adopt GitHub Agentic Workflows. The project demonstrates excellent engine parity, with virtually all features working identically across Copilot, Claude, and Codex engines.

The only friction is in the initial onboarding documentation, where a Copilot-first orientation creates a perception that Claude is a "secondary" option. This is purely a documentation issue, not a technical limitation. Once users understand that Claude is fully supported (which becomes clear in the Engines documentation), the experience is excellent.

Evidence supporting this conclusion:

1. 29 production Claude workflows demonstrate active usage and trust
2. 100% tool compatibility - All tools work with Claude (except explicitly Copilot-only bot features)
3. Excellent Claude-specific documentation in the Engines and Tokens pages
4. Simple authentication - Just an API key, easier than Copilot's fine-grained PAT setup
5. Engine-agnostic architecture - No hidden dependencies on Copilot
6. Clear boundaries - Copilot-only features are explicitly documented

The recommended documentation fixes (Priority 1 and 2) would eliminate the initial friction and make the onboarding experience as smooth for Claude users as it currently is for Copilot users.

Overall Assessment Score: 8.0/10

Breakdown:

• Clarity for non-Copilot users: 7/10 (loses points for Copilot-first Quick Start)
• Claude engine documentation: 8/10 (excellent setup docs, could use more examples)
• Alternative approaches provided: 9/10 (all features work, clear boundaries)
• Engine parity: 8/10 (full parity except for explicitly Copilot-only features)

Next Steps

For gh-aw maintainers:

1. Implement Priority 1 fixes (Quick Start and Prerequisites) - highest impact, low effort
2. Consider Priority 2 improvements (How It Works, README, comparison guide)
3. Continue building Claude workflow examples to demonstrate capabilities

For Claude Code users considering gh-aw:

1. ✅ Go ahead and adopt it - you're fully supported!
2. Start with gh aw init and select "Claude" when prompted
3. Follow the Engines documentation for ANTHROPIC_API_KEY setup
4. Reference the 29 existing Claude workflows for patterns and examples
5. All features work identically to Copilot (except bot-specific features you don't need)

---

Appendix: Files Reviewed

Complete List of Documentation Files Analyzed

Core Documentation:

• README.md - Project overview and introduction
• docs/src/content/docs/index.mdx - Documentation homepage
• docs/src/content/docs/setup/quick-start.mdx - Getting started guide
• docs/src/content/docs/setup/creating-workflows.mdx - Workflow creation guide
• docs/src/content/docs/setup/cli.md - CLI command reference
• docs/src/content/docs/introduction/how-they-work.mdx - Conceptual overview
• docs/src/content/docs/introduction/architecture.mdx - Security architecture (33.6KB)
• docs/src/content/docs/reference/tools.md - Tools configuration
• docs/src/content/docs/reference/engines.md - AI engines documentation
• docs/src/content/docs/reference/tokens.md - Authentication and tokens
• docs/src/content/docs/reference/faq.md - Frequently asked questions (partial)

Example Workflows Analyzed:

• .github/workflows/smoke-claude.md - Claude smoke test
• .github/workflows/claude-code-user-docs-review.md - This very workflow!
• Statistics from 130+ workflows across .github/workflows/*.md

Workflow Statistics:

• Total workflows: ~130+
• Copilot workflows: 71 (explicit engine: copilot)
• Claude workflows: 29 (explicit engine: claude)
• Codex workflows: 9 (explicit engine: codex)
• Default (no engine specified): 22 (implicitly Copilot)

---

Report Generated: 2026-02-12
Workflow Run ID: 21956832993
Workflow: claude-code-user-docs-review
Engine Used: claude (eating our own dog food! 🐕)
Review Focus: Quality, security, documentation from Claude Code user perspective

---

Note: This was intended to be a discussion, but discussions could not be created due to permissions issues. This issue was created as a fallback.

AI generated by Claude Code User Documentation Review

• expires on Feb 19, 2026, 5:24 PM UTC