GitHub CLI + Claude Code Integration

A practical guide to installing, authenticating, and using the GitHub CLI (gh) with Claude Code — so the AI agent can interact with your GitHub repositories directly from the terminal.

---

Why This Matters

Claude Code can use gh as a native tool. Once authenticated, you can ask Claude to:

• Create and review pull requests
• Open, close, or comment on issues
• Clone repositories
• Check CI/CD workflow status
• Manage releases and gists

All from natural language, without leaving your editor or terminal.

---

Prerequisites

• Windows 10/11, macOS, or Linux
• Claude Code installed and running
• A GitHub account

---

Step 1 — Install GitHub CLI

Windows

winget install --id GitHub.cli

Or with Scoop:

scoop install gh

Or with Chocolatey:

choco install gh

macOS

brew install gh

Linux (Debian/Ubuntu)

sudo apt install gh

After installation, close and reopen your terminal to refresh the PATH.

---

Step 2 — Authenticate

gh auth login

Follow the interactive prompts:

1. Select GitHub.com
2. Select HTTPS as the protocol
3. Choose Login with a web browser
4. Copy the one-time code shown in the terminal
5. Press Enter — your browser opens automatically
6. Paste the code on GitHub and authorize the app

Verify authentication

gh auth status

Expected output:

github.com
  ✓ Logged in to github.com account YOUR_USERNAME (keyring)
  - Active account: true
  - Git operations protocol: https
  - Token scopes: 'gist', 'read:org', 'repo', 'workflow'

---

Step 3 — Use with Claude Code

Once gh is authenticated, Claude Code detects it automatically. You can give natural language instructions like:

What you say	What Claude does
"Create a PR for this branch"	gh pr create ...
"Show open issues"	gh issue list
"Check the CI status"	gh run list
"Create a new repo called my-project"	gh repo create my-project ...
"Clone my repo XYZ"	gh repo clone USERNAME/XYZ

Claude uses gh internally via Bash/PowerShell tool calls — you can see the exact commands it runs before approving them.

---

Step 4 — Reduce Permission Prompts (Optional)

If Claude frequently asks for permission to run gh commands, you can pre-authorize them in your project settings.

In Claude Code, run:

/update-config

Or manually add to .claude/settings.json:

{
  "permissions": {
    "allow": [
      "Bash(gh *)"
    ]
  }
}

This allows all gh subcommands without prompting.

---

Common Commands Reference

# Authentication
gh auth login          # authenticate
gh auth status         # check current auth status
gh auth logout         # remove credentials

# Repositories
gh repo create         # create a new repository
gh repo clone USER/REPO  # clone a repository
gh repo view           # view repo info in browser

# Pull Requests
gh pr create           # create a pull request
gh pr list             # list open PRs
gh pr view             # view a PR
gh pr merge            # merge a PR

# Issues
gh issue create        # open a new issue
gh issue list          # list issues
gh issue close NUMBER  # close an issue

# Workflows / CI
gh run list            # list recent workflow runs
gh run view            # view a specific run
gh run watch           # watch a run in real time

---

Troubleshooting

gh: command not found after installation Close and reopen the terminal. On Windows, restart PowerShell or VS Code.

Authentication token expired Run gh auth refresh to renew without re-doing the full login.

Claude asks for permission every time Add Bash(gh *) to the allow list in .claude/settings.json (see Step 4).

Wrong account logged in Run gh auth logout, then gh auth login again with the correct account.

---

Resources

• GitHub CLI official docs
• Claude Code documentation
• Claude Code settings & permissions

---

Guide tested on Windows 11 with Claude Code (claude-sonnet-4-6) and gh v2.x.