[FEATURE] GitHub CLI Support for iOS Claude Code

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

Problem Statement

Claude Code on iOS cannot effectively troubleshoot GitHub Actions workflow failures due to lack of GitHub CLI (gh) access. This limitation has resulted in multiple failed diagnostic sessions where critical issues (such as billing/payment problems) could not be identified.

Real-World Impact

Incident: 2025-12-15 - All GitHub Actions workflows failing
Root Cause: Billing/payment issue preventing job execution
Sessions Failed: Multiple (iOS, Web) - Could not diagnose
Session Succeeded: Linux with gh CLI - Diagnosed in 30 minutes

Key Finding: The error message was only accessible via:

gh api repos/{owner}/{repo}/check-runs/{id}/annotations

Without this capability, the issue was invisible to iOS/Web sessions.

---

Current Limitations

iOS Claude Code Cannot:

1. Access GitHub API - No programmatic access to GitHub data
2. View workflow runs - Cannot list or inspect workflow execution history
3. Read workflow logs - Cannot view job output or error messages
4. Query check-run annotations - Cannot access detailed error information
5. Diagnose billing issues - Cannot detect account/quota problems
6. Manage PRs/issues - Cannot create, update, or close via CLI
7. Check workflow status - Must rely on user manually checking web UI

What iOS Can Do:

• Read local workflow files (.github/workflows/*.yml)
• Use git commands
• Provide GitHub web URLs for manual operations

---

---

Proposed Solution

Proposed Solution

Option 1: Bundle GitHub CLI in iOS App (Preferred)

Implementation:

• Include gh binary in iOS app bundle
• Pre-authenticate using app's credentials
• Expose gh commands to Claude's bash tool
• Installation path: ~/Documents/.claude/bin/gh or similar

Benefits:

• Full GitHub API access
• No user setup required
• Consistent experience across platforms
• Can troubleshoot private repositories

Technical Considerations:

• Binary size: ~15-20 MB (manageable)
• Requires GitHub app token for API access
• May need iOS-specific build of gh CLI
• Should respect iOS sandbox restrictions

Alternative Solutions

Option 2: Add GitHub API Tool to Claude Code

Implementation:

• Create dedicated GitHub API tool (similar to WebFetch)
• Expose common operations: list runs, get logs, query annotations
• Use user's GitHub token or app credentials
• iOS-native implementation

Benefits:

• Lighter weight than full gh CLI
• Can be optimized for mobile
• Purpose-built for Claude's needs

Drawbacks:

• Requires developing/maintaining custom tool
• May not have feature parity with gh CLI
• Less flexible than full CLI access

Option 3: Web-Based GitHub Integration

Implementation:

• OAuth integration with GitHub
• Fetch workflow data via web API calls
• Display in Claude's interface
• User must authenticate via GitHub OAuth

Benefits:

• No binary bundling required
• Standard OAuth flow
• Works on all platforms

Drawbacks:

• Requires user authentication setup
• May have rate limiting issues
• More complex error handling

Priority

Medium - Would be very helpful

Feature Category

CLI commands and flags

Use Case Example

Use Cases

1. Troubleshooting Workflow Failures

Scenario: User reports "all my GitHub Actions are failing"

Current iOS Experience:

Claude: I can see your workflow files, but I cannot view the actual
failures or logs. Please:
1. Go to github.com/your-repo/actions
2. Click on a failed run
3. Copy/paste the error message to me

User: [frustrated, has to do manual work]

With GitHub CLI:

Claude: Let me check the workflow runs...
[Runs: gh run list --limit 10]
[Checks: gh run view 123456 --log]
[Analyzes: gh api repos/.../check-runs/.../annotations]

Claude: Found the issue! Your workflows are failing due to a billing
problem. Here's the error message and how to fix it...

User: [problem solved quickly]

2. PR Management During Development

Current iOS Experience:

Claude: I've committed your changes to branch 'fix-123'.
To create a PR, go to:
https://github.com/owner/repo/pull/new/fix-123

[User must switch to browser, create PR manually]

With GitHub CLI:

Claude: I've committed your changes and created PR #45:
[Runs: gh pr create --title "..." --body "..."]

The PR is ready for review at: [URL]

3. Monitoring CI/CD Pipeline

Current iOS Experience:

User: Did my workflow pass?
Claude: I don't have access to check. Please visit the Actions tab
on GitHub.

With GitHub CLI:

User: Did my workflow pass?
Claude: Let me check...
[Runs: gh run list --branch main --limit 1]

Yes! Your latest workflow "Tests" passed successfully 2 minutes ago.
All checks are green.

4. Diagnosing Billing/Quota Issues

Current iOS Experience:

Claude: Your workflows are failing but I cannot determine why.
The error logs are not accessible from here.

[Multiple sessions fail to diagnose]
[User wastes hours troubleshooting]

With GitHub CLI:

Claude: Let me check the annotations...
[Runs: gh api repos/.../check-runs/.../annotations]

Found it! You have a billing issue:
"The job was not started because recent account payments have failed..."

Fix this at: github.com/settings/billing

---

Benefits

For Users

1. Faster Problem Resolution - Diagnose issues in minutes, not hours
2. Less Context Switching - No need to leave Claude to check GitHub
3. Better Experience - Claude can be truly helpful with CI/CD issues
4. Complete Workflows - Can handle entire dev workflow within Claude

For Claude Code Product

1. Feature Parity - iOS matches Linux/Desktop capabilities
2. Better Reviews - Users praise comprehensive GitHub integration
3. Reduced Frustration - No more "I can't help with that" responses
4. Competitive Advantage - Full GitHub integration is a selling point

For Development Velocity

1. Eliminates Diagnostic Blind Spots - Can see what's actually happening
2. Enables Proactive Help - Claude can check status without being asked
3. Supports DevOps Workflows - Critical for modern development practices

---

Success Metrics

After implementation, we should see:

1. Diagnostic Success Rate ↑ - More issues resolved without escalation
2. Session Length ↓ - Faster problem resolution
3. User Satisfaction ↑ - Based on feedback/ratings
4. "I can't do that" Responses ↓ - Fewer capability limitations
5. Context Switches ↓ - Less leaving Claude to check GitHub

---

Implementation Phases

Phase 1: MVP (Critical Operations)

Priority Commands:

• gh run list - List workflow runs
• gh run view <id> --log - View workflow logs
• gh api repos/.../check-runs/.../annotations - Get error details
• gh pr list - List pull requests
• gh pr view <id> - View PR details

Estimated Effort: 2-4 weeks
Impact: Solves 80% of current pain points

Phase 2: PR/Issue Management

Additional Commands:

• gh pr create - Create pull requests
• gh pr review - Review PRs
• gh issue create - Create issues
• gh issue list - List issues

Estimated Effort: 2-3 weeks
Impact: Complete PR workflow within Claude

Phase 3: Advanced Features

Additional Commands:

• gh workflow run - Trigger workflows manually
• gh release create - Create releases
• gh repo view - View repository info
• Full gh CLI feature set

Estimated Effort: 3-4 weeks
Impact: Full GitHub integration parity

---

Technical Requirements

iOS App Requirements

• Include gh CLI binary (or build custom GitHub API tool)
• Manage GitHub authentication/tokens
• Respect iOS sandbox restrictions
• Handle network requests appropriately
• Cache API responses to avoid rate limits

Security Requirements

• Secure token storage
• Respect user's GitHub permissions
• Handle private repository access appropriately
• Comply with GitHub API terms of service
• Rate limit management

UX Requirements

• Transparent to user (works automatically)
• Clear error messages if auth fails
• Option to disable if desired
• Show API usage/rate limit status

---

Related Issues

• Inability to diagnose GitHub Actions failures on iOS
• Cannot create PRs programmatically
• Cannot check CI/CD status
• Cannot manage issues from Claude
• Limited automation capabilities

---

References

• GitHub CLI: https://cli.github.com/
• GitHub API: https://docs.github.com/en/rest

---

Priority Justification

1. Common Use Case - GitHub integration is essential for modern development
2. Current Gap - iOS users have significantly degraded experience
3. Clear Solution - GitHub CLI is mature, well-documented, available
4. High Impact - Solves entire class of problems (not just one edge case)
5. Competitive Necessity - Other AI coding tools have GitHub integration
6. User Frustration - Multiple failed sessions due to this limitation

Additional Context

Alternative Workarounds (Current State)

While waiting for this feature, iOS users can:

1. Use Linux/Desktop Claude Code for GitHub troubleshooting
2. Manually check GitHub web UI and paste errors to Claude
3. Ask Claude to provide GitHub URLs to click instead of automating
4. Accept limited diagnostics for workflow issues

None of these are satisfactory for a premium developer tool.

---