🌐 gh-browse-or-reload

gh-browse-or-reload is a smart, SEO-optimized GitHub CLI (gh) extension and browser tab management tool. Instead of repeatedly opening brand-new browser tabs and cluttering your workspace, this lightweight Python script intelligently searches your currently open tabs. If the target GitHub repository, issue, or pull request page is already open, the tool seamlessly reloads and focuses that exact tab. If not, it falls back to the default gh browse behavior to open a new tab. Perfect for developers looking to optimize their command-line to browser workflow!

📖 For Users

🛠️ Prerequisites

• 🐍 Python 3.7+
• 🐙 GitHub CLI (gh) installed and authenticated.

1️⃣ Install the CLI Package

Install the CLI tool globally using pip:

pip install gh-browse-or-reload

2️⃣ Load the Browser Bridge Extension

Because standard shell scripts cannot natively snoop on your browser tabs due to security restrictions, a companion browser extension is required to act as a "bridge".

1. 🌐 Open Chrome/Edge and navigate to chrome://extensions/ (or edge://extensions/).
2. ⚙️ Toggle the Developer mode switch in the top-right corner.
3. 📂 Click Load unpacked in the top-left corner.
4. 📁 Select the extension/ directory (containing manifest.json and background.js) from this repository.
5. 📋 Copy the Extension ID generated by the browser (a long string of random lowercase letters).

3️⃣ Configure the Extension ID

The first time you run gh-browse-or-reload, the tool will detect that it needs an extension ID and interactively prompt you for it:

--- First Run Setup ---
To enable seamless tab reloading on Windows/Linux, you need the companion browser extension installed.
Please enter your Chrome/Edge Extension ID (or press Enter to skip and fallback to default 'gh browse'):
> 

Once entered, it will be securely saved to ~/.config/gh-browse-or-reload/config.json and you will never be asked again! 🛑

(Advanced users: You can still override this on the fly by exporting GH_BROWSER_EXTENSION_ID in your shell).

4️⃣ (Optional) Create a Shell Alias

For an optimal and lightning-fast workflow, alias gh-browse to use this script automatically:

alias gh-browse="gh-browse-or-reload"

🎯 Usage Examples

The tool accepts all flags native to the official GitHub CLI Browse Command.

# 🔄 Open or refresh current repository
gh-browse-or-reload

# 🐛 Target specific sub-panels like issues or pull requests
gh-browse-or-reload --issues
gh-browse-or-reload --settings

# 🌍 Target a completely different repository path
gh-browse-or-reload cli/cli

💻 For Developers

If you want to contribute to the project or run it locally from source.

🏗️ Local Development Setup

1. Clone the repository:

   git clone https://github.com/ishandutta2007/gh-browse-or-reload.git
   cd gh-browse-or-reload
   

2. Install the package in editable mode:

   pip install -e .
   

   This will link the CLI command gh-browse-or-reload to your live source files in the src/ directory. You can now modify src/gh_browse_or_reload/cli.py and see the changes immediately when you run the command.

🏛️ Architecture

• CLI (src/gh_browse_or_reload/cli.py): Intercepts gh browse, determines the target URL using gh browse --no-browser, and delegates the task to the browser using a clever local HTTP server bridge.
• MacOS Fallback: On macOS, the script falls back to an automated AppleScript bridge that loops through open Google Chrome windows/tabs to reload them natively.
• Extension Bridge (extension/): Used on Windows/Linux environments to securely bridge the communication gap between the OS and the browser without background daemons.

🚀 For Package Publishers (Automated CI/CD)

This repository is configured with a GitHub Actions workflow that automatically builds and publishes the package to PyPI whenever a new version tag is pushed.

1️⃣ Initial Repository Setup

To enable automated publishing, you must add your PyPI API token to your GitHub repository secrets:

1. 🔑 Go to your PyPI account and generate an API Token.
2. ⚙️ Go to your GitHub Repository -> Settings -> Secrets and variables -> Actions.
3. ➕ Click New repository secret.
4. 🏷️ Name it PYPI_API_TOKEN and paste your PyPI token as the value.

2️⃣ How to Publish a New Release

Whenever you are ready to publish a new version to PyPI, simply follow these steps:

1. Update the Version: Open pyproject.toml and bump the version field (e.g., from "0.1.0" to "0.1.1"). Commit and push this change to your main branch:

   git add pyproject.toml
   git commit -m "Bump version to 0.1.1"
   git push origin main
   

2. Create and Push a Tag: Create a git tag matching your new version (must start with v) and push it to GitHub:

   git tag v0.1.1
   git push origin v0.1.1
   

That's it! 🎉 Pushing the v* tag will automatically trigger the GitHub Actions workflow. The system will build the .tar.gz and .whl distributions and securely upload them directly to PyPI. You can watch the progress in the Actions tab of your GitHub repository.

⭐ Star History