Metadata-Version: 2.4
Name: gh-claude
Version: 0.11.1
Summary: A modern multi-repository GitHub TUI with Claude Code integration
Author: Masa
License-Expression: MIT
Project-URL: Homepage, https://github.com/masaaaaa725/ghc
Project-URL: Repository, https://github.com/masaaaaa725/ghc
Project-URL: Issues, https://github.com/masaaaaa725/ghc/issues
Keywords: github,gh,claude,textual,tui
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Version Control :: Git
Requires-Python: >=3.13
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: textual>=8.2.8
Dynamic: license-file

# gh-claude

A modern, keyboard-first TUI for managing GitHub issues and pull requests across
multiple repositories. It uses [Textual](https://textual.textualize.io/) for the
interface, GitHub CLI for data, and Claude Code for issue drafting and analysis.

License: [MIT](LICENSE)

PyPI: [`gh-claude`](https://pypi.org/project/gh-claude/)  
Repository: [`masaaaaa725/ghc`](https://github.com/masaaaaa725/ghc)

## Requirements

- Python 3.13+
- [uv](https://docs.astral.sh/uv/) or pip
- [GitHub CLI](https://cli.github.com/) (`gh auth login`)
- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) (`claude`)
- Git

## Install

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

Update an existing `uv tool` install:

```bash
uv tool upgrade gh-claude
```

## Publishing

Every push to `main` runs [`.github/workflows/publish.yml`](.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](https://pypi.org/manage/project/gh-claude/settings/publishing/)
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

```bash
gh-claude
# alias
ghc
```

From a local checkout:

```bash
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:

```bash
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`:

```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, and save the result
- `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.

Pressing `v` on a pull request saves the AI review to `~/.config/ghc/reviews.json`, keyed by
repository and PR number, so it survives restarts. Whenever a pull request has a saved
review — right after running `v`, or when you open its detail again later, even in a new
`ghc` session — the detail view splits into two columns: the PR's own content on the left,
and the AI review on the right. Press `v` again to re-review and refresh the saved copy.

## Project layout

```text
.
├── 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

```bash
uv run pytest
```
