gh-claude

A modern, keyboard-first TUI for managing GitHub issues and pull requests across multiple repositories. It uses Textual for the interface, GitHub CLI for data, and Claude Code for issue drafting and analysis.

License: MIT

PyPI: gh-claude
Repository: masaaaaa725/ghc

Requirements

• Python 3.13+
• uv or pip
• GitHub CLI (gh auth login)
• Claude Code (claude)
• Git

Install

pip install gh-claude
# or
uv tool install gh-claude

Update an existing uv tool install:

uv tool upgrade gh-claude

Publishing

Every push to main runs .github/workflows/publish.yml, which bumps the patch version in pyproject.toml, publishes that version to PyPI, and commits the bump back to main (with [skip ci] to avoid a loop).

One-time setup on PyPI (Trusted Publishing):

1. Open PyPI publishing settings for gh-claude
2. Add a GitHub publisher:
   • Owner: masaaaaa725
   • Repository: ghc
   • Workflow: publish.yml
   • Environment: pypi
3. In GitHub, create an Environment named pypi (Settings → Environments)

After that, merges to main publish automatically. Users can then run uv tool upgrade gh-claude.

Run

gh-claude
# alias
ghc

From a local checkout:

uv sync
uv run gh-claude

The app detects the GitHub repository in the current directory. Press r or Ctrl+P to switch to any repository returned by gh repo list.

Choosing a Claude model

By default, ghc uses whatever model the claude CLI defaults to. Set a starting model with the --model flag:

ghc --model claude-opus-4-6

To avoid passing the flag every time, set the GHC_MODEL environment variable, or persist a default in ~/.config/ghc/config.toml:

model = "claude-sonnet-4-6"

Precedence: --model flag > GHC_MODEL environment variable > config file > the claude CLI's own default.

Press m at any time inside ghc to switch models without restarting — pick a preset or type any model ID. The active model is shown in the footer, and the choice is saved to ~/.config/ghc/config.toml so it's used again the next time you start ghc (unless overridden by --model or GHC_MODEL). Picking "Claude Code default" clears the saved override.

Keyboard shortcuts

• ↑ / ↓: move the selection in the Issues, Pull Requests, GitHub Actions, or Secrets list
• ← / → / Tab / Shift+Tab: cycle between the Issues, Pull Requests, GitHub Actions, and Secrets tabs
• f: cycle the status filter (OPEN → CLOSED → ALL for Issues; includes MERGED / DRAFT for PRs; SUCCESS / FAILURE / IN_PROGRESS / QUEUED / CANCELLED for GitHub Actions; ALL / REPOSITORY / ENVIRONMENT for Secrets)
• /: filter the active list by title, label, or author; Enter applies, Esc cancels
• r / Ctrl+P: searchable repository picker (↑/↓ to move, Enter to select, Esc to cancel)
• c: turn rough notes into a reviewed GitHub issue with Claude
• s: summarize the selected issue, pull request, or workflow run with Claude
• o: check out the selected pull request as a local branch
• v: review the selected pull request diff with Claude
• e: view, edit, and save a custom AI review prompt (Ctrl+D resets to the default)
• a: draft, preview, and post an AI-polished comment (issues and pull requests only)
• Ctrl+E: create an Issue branch and let Claude implement the selected Issue
• i / p / w / k: switch to Issues / Pull Requests / GitHub Actions / Secrets
• Ctrl+R / F5: refresh Issues, Pull Requests, GitHub Actions, and Secrets for the current repository
• Ctrl+C: quit

GitHub Actions lists recent workflow runs for the current repository (status, workflow, branch, event, and last update time). Press g to open the run on GitHub, or s to have Claude summarize a failed run. Re-running jobs from within ghc is not yet supported.

Secrets lists the names of repository-level GitHub Secrets and per-environment secrets (scope, visibility, and last update time). Per GitHub's security model, secret values are never exposed by the API or CLI, so only names and metadata are shown. Press g to open GitHub's settings page for the selected secret.

Press e to customize the instructions Claude follows for AI review (v). The prompt is saved to ~/.config/ghc/review_prompt.md and reused across sessions; press Ctrl+D inside the editor to clear it and fall back to the built-in default.

Project layout

.
├── pyproject.toml
├── uv.lock
├── src/                # Import package `ghc` (PyPI name: `gh-claude`)
│   ├── __init__.py
│   ├── __main__.py
│   ├── app.py          # Main Textual app and interactions
│   ├── app.tcss        # Dark UI theme
│   ├── clients.py      # Async gh / claude / git wrappers
│   ├── models.py       # Domain models
│   └── screens.py      # Repository and issue workflow modals
└── tests/
    ├── test_app.py
    ├── test_clients.py
    ├── test_models.py
    └── test_screens.py

All external commands are executed without a shell via asyncio.create_subprocess_exec. GitHub read operations request JSON explicitly; commands such as gh pr diff, gh pr checkout, gh issue create, and gh issue comment are exceptions because those GitHub CLI commands do not support --json.

Ctrl+E is intentionally limited to the repository currently checked out on disk. After confirmation, it creates issue-<number>-<slug> with git checkout -b, then runs Claude Code in print mode. Claude is instructed not to commit, push, or modify unrelated files; always review the working tree after it finishes.

Test

uv run pytest