# GHpeek - the easy Github repository viewer

![GHpeek screenshot](https://github.com/kimusan/ghpeek/blob/main/assets/screenshot.png)

GHpeek is a friendly terminal UI for keeping tabs on your GitHub repositories. Add the repos you care about and get a clean, readable list of open issues and pull requests with unread items highlighted. Each repo also shows a quick summary of stars, forks, and open counts so you can spot activity at a glance.

## Dependencies

- textual
- PyGithub
- rich
- markdown
- python-dotenv

## Installation

GHpeek can be installed via pip. Simply run the following command:

```bash
pip install ghpeek
```

Or, even better with pipx:

```bash
pipx install ghpeek
```

## Usage

To start GHpeek, simply run the following command:

```bash
ghpeek
```

Press `a` to add a repository. If a GitHub token is configured, you can choose from your own repositories, filter forks, organizations, and public/private repos, or enter a repo manually in `owner/repo` format. Without a token, manual entry still works.

Once added, repositories appear on the left. Use the arrow keys to switch between them, and you will see a summary of stars, forks, and open counts. The main panel lists issues and pull requests; press `Enter` to open a preview, then `Enter` again to open it in your browser.
The preview includes the issue or PR description plus the latest comments, with a "Load older" option when more are available.

Quick keys:
- `i` / `p`: jump between Issues and Pull Requests
- `c`: show or hide closed issues/PRs
- `r`: refresh the selected repo
- `q`: quit

## GitHub token

To enable repository picking and higher API limits, set a personal access token in `GITHUB_TOKEN` (recommended via a `.env` file in `~/.config/ghpeek/.env`). For private repositories, the token needs the `repo` scope. For public repos only, `public_repo` (or no scopes) is sufficient.

# License

The project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.

# Contributing

I would love to see contributions to GHpeek! If you have any ideas for new features or improvements, please feel free to open an issue or submit a pull request.

# Acknowledgements

This project uses the following open source libraries:
 - [Textual](https://github.com/Textualize/textual)
 - [PyGithub](https://github.com/PyGithub/PyGithub)
 - [Rich](https://github.com/Textualize/rich)
 - [Markdown](https://python-markdown.github.io/)
 - [python-dotenv](https://github.com/theskumar/python-dotenv)

GHpeek was inspired by other terminal-based tools and was originally written by [Kim Schulz](https://Schulz.dk).

# Roadmap

 - Add search and filtering by label, author, and assignee
 - Add notifications or a background refresh mode
 - Add quick actions (close/reopen, comment) directly from the TUI
