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.

Keyboard shortcuts

• ↑ / ↓: move the selection in the Issues, Pull Requests, or GitHub Actions list
• ← / →: cycle between the Issues, Pull Requests, and GitHub Actions 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)
• 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: switch to Issues / Pull Requests / GitHub Actions
• Ctrl+R / F5: refresh Issues, Pull Requests, and GitHub Actions 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.

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