| > [!WARNING] |
| > **Beta.** openhop is being updated right now (November 15–16, 2026). This README is **not up to date** yet: some |
| > features, names and downloads it describes aren't released. Found a problem? Please [open an Issue](https://github.com/bernat-lol/openhop/issues). |
| > |
| > **Beta.** openhop se está actualizando ahora mismo (15–16 de noviembre de 2026). Este README **todavía no está |
| > actualizado**: algunas funciones, nombres y descargas que describe aún no están publicados. ¿Algo falla? [Abre un Issue](https://github.com/bernat-lol/openhop/issues). |
| |
| <p align="center"> |
| <picture> |
| <source media="(prefers-color-scheme: dark)" srcset="assets/brand/openhop-wordmark-dark.svg"> |
| <img src="assets/brand/openhop-wordmark.svg" alt="openhop" width="360"> |
| </picture> |
| </p> |
| |
| <p align="center"> |
| <b>Keep OpenCode working when you hit the free limit.</b><br> |
| openhop gives OpenCode a fresh connection the moment the limit appears and tells it to continue, so your chat keeps going. |
| </p> |
| |
| <p align="center"> |
| <a href="https://openhop.cfd"><img alt="Download" src="https://img.shields.io/badge/Download-Windows-f2b318?style=for-the-badge&labelColor=1f2125"></a> |
| <a href="https://openhop.cfd"><img alt="Website: openhop.cfd" src="https://img.shields.io/badge/Web-openhop.cfd-efede6?style=for-the-badge&labelColor=1f2125"></a> |
| <a href="LICENSE"><img alt="MIT License" src="https://img.shields.io/badge/License-MIT-efede6?style=for-the-badge&labelColor=1f2125"></a> |
| </p> |
| |
|  |
| |
| --- |
| |
| ## What it does |
| |
| [OpenCode](https://opencode.ai/) has a free tier with a usage limit. When you reach it, OpenCode stops answering and |
| shows a "free usage limit" message. |
| |
| openhop runs quietly next to OpenCode and: |
| |
| 1. **Watches** OpenCode for the limit message. |
| 2. **Hops** to a fresh internet address (through Cloudflare's free WARP app) in a few seconds. |
| 3. **Continues** your chat automatically. The limit banner goes away and openhop sends "continue" for you. |
| |
| Your chats and history are never touched. You just keep working. |
| |
| ## What you need |
| |
| | | | |
| |---|---| |
| | **Windows 10 or 11** | Linux works too (see [For advanced users](#for-advanced-users)). | |
| | **OpenCode** | The Desktop app or the `opencode` command. [Get OpenCode](https://opencode.ai/) | |
| | **Cloudflare WARP** (free) | The "1.1.1.1" app. openhop uses it to get fresh addresses. [Get WARP](https://one.one.one.one/) | |
| |
| You do **not** need Python or any coding knowledge. |
| |
| ## Install (2 minutes) |
| |
| 1. **Download** `openhop.exe` from **[openhop.cfd](https://openhop.cfd)** and double-click it. |
| It runs from anywhere, nothing to install. *(An installer, `openhop-setup.exe`, is coming.)* |
| 2. **Open openhop.** The first screen checks that WARP and OpenCode are installed and sets everything up. |
| 3. **Use OpenCode as usual.** That's it. |
| |
| > **"Windows protected your PC"?** openhop isn't signed with a paid certificate yet, so Windows may warn you the first |
| > time. Click **More info → Run anyway**. The code is all here in this repository if you want to check it. |
| |
| ## Everyday use |
| |
| openhop lives in the **tray** (the icons by the clock). The little dot on its icon tells you how things are: |
| |
| | Dot | Meaning | |
| |---|---| |
| | 🟢 Green | Everything is working. | |
| | 🟡 Amber | Working, but something should be turned on (or openhop is switching to a new address). | |
| | 🔴 Red | OpenCode can't work right now. Open openhop and press **Fix everything**. | |
| |
| **Right-click the icon** for quick actions: |
| |
| - **Get a new IP:** switch address right now, without waiting for the limit. |
| - **Fix everything:** checks every part of openhop and repairs what it can, then tells you in plain words what it did. |
| - **Open openhop / Quit openhop** |
| |
| Closing the window with **X** keeps openhop running in the tray. Use **Quit openhop** to close it completely. |
| openhop can start with Windows (on by default, you can turn it off in Settings). |
| |
| You'll get a small notification when something needs your attention, and when openhop switched to a new address for |
| you. Each kind can be turned off. |
| |
| ### Simple and Advanced view |
| |
| The app opens in **Simple** view: is it working, the fix button, launch OpenCode, get a new IP, protection on/off. |
| Switch to **Advanced** for everything else: connection types, logs, error history and expert settings. |
| |
| ### Connection type |
| |
| - **Only OpenCode** *(recommended)*: only OpenCode goes through Cloudflare. Your browser, games and calls stay on |
| your normal internet and are never interrupted when openhop switches address. |
| - **Whole PC**: everything on your computer goes through Cloudflare WARP. |
| - **Advanced options:** Tor, your own proxy list, or "clean endpoints" for networks where Cloudflare is slow or blocked. |
| |
| ## Something isn't working? |
| |
| Press **Fix everything** first. It solves most problems. If it doesn't, find your message below. |
| |
| <details> |
| <summary><b>OpenCode says "Unable to connect" / <code>ECONNREFUSED</code></b></summary> |
| |
| openhop's background service isn't running, so OpenCode can't connect. Open openhop and press **Fix everything** (or the |
| **Start it** button in the red box). It usually takes a couple of seconds. |
| </details> |
| |
| <details> |
| <summary><b>The "free usage limit" banner is still there</b></summary> |
| |
| Wait about 10 seconds. openhop needs a moment to switch address and unlock the chat. If it stays, press |
| **Get a new IP**, or press <kbd>Ctrl</kbd>+<kbd>R</kbd> inside OpenCode Desktop. |
| </details> |
| |
| <details> |
| <summary><b>WARP says "Network: unstable"</b></summary> |
| |
| That's normal. WARP says it whenever the connection is a bit slow. Nothing is broken. |
| </details> |
| |
| <details> |
| <summary><b>WARP keeps "Connecting…" or shows <code>CF_HAPPY_EYEBALLS_MITM_FAILURE</code></b></summary> |
| |
| Your network is blocking or slowing Cloudflare. Press **Fix everything**. If it keeps happening, go to **Advanced → |
| Connection type → Clean endpoints**, press **Test**, and apply the fastest one. In very restricted countries, try **Tor**. |
| </details> |
| |
| <details> |
| <summary><b>"Port already in use"</b></summary> |
| |
| An old copy of openhop (or of "Opencode Unlimited") is still holding it. Press **Fix everything**. Delete old `.exe` |
| versions you no longer use: an old version can replace the new background service with its older code. |
| </details> |
| |
| <details> |
| <summary><b>Still stuck?</b></summary> |
| |
| [Open an issue](https://github.com/bernat-lol/openhop/issues) and describe what you see. Screenshots help a lot. |
| </details> |
| |
| ## What openhop changes on your PC |
| |
| openhop has no servers and collects nothing. Everything runs on your computer. To do its job it: |
| |
| - switches Cloudflare WARP's settings (mode and protocol) when you pick a connection type; |
| - points OpenCode at openhop's local connection (`127.0.0.1:41987`) through OpenCode's own settings file; |
| - adds two background tasks that keep the connection healthy and watch for the limit, plus an optional "start with Windows" entry; |
| - clears OpenCode's "free limit" lock after switching address, without touching your chats. |
| |
| **Uninstall** from Windows Settings → Apps (or run `uninstall.bat` if you used the portable version). That removes |
| the background tasks and restores OpenCode's settings. |
| |
| --- |
| |
| ## For advanced users |
| |
| <details> |
| <summary><b>How it works</b></summary> |
| |
| OpenCode's free limit is counted per internet address (an IPv6 `/64` block). openhop routes OpenCode through a small |
| local proxy on `127.0.0.1:41987` and sends that traffic out through Cloudflare WARP. When the limit appears in |
| OpenCode's log, it asks WARP for a new address, removes OpenCode Desktop's local `free-limit` lock from |
| `drafts.sqlite` (history tables are never modified) and sends `continue`. |
| |
| ``` |
| OpenCode Desktop / CLI |
| │ HTTPS via 127.0.0.1:41987 (openhop proxy) |
| ▼ |
| ┌─ Only OpenCode (default) ─▶ WARP local SOCKS5 :40000 (MASQUE) ─▶ Cloudflare ─▶ fresh IPv6 /64 |
| ├─ Whole PC ───────────────▶ WARP system tunnel (WireGuard) |
| ├─ Clean endpoint ─────────▶ WARP pinned to an unthrottled Cloudflare IP |
| ├─ Tor ────────────────────▶ 127.0.0.1:9050 / 9150 ─▶ new circuit per hop |
| └─ Custom proxies ─────────▶ your SOCKS5/HTTP pool, round-robin |
| ``` |
| </details> |
| |
| <details> |
| <summary><b>Command line (Windows)</b></summary> |
| |
| `openhop.exe --doctor` runs a health check in the terminal, `openhop.exe --hop` gets a new address, and |
| `openhop.exe --tray` starts in the tray. After setup, the `opencode` command is routed through openhop automatically, |
| and these commands work in any new terminal: `openhop` (open the app), `openhop-hop` and `openhop-doctor`. |
| </details> |
| |
| <details> |
| <summary><b>Linux (desktop, server or VPS)</b></summary> |
| |
| ```bash |
| bash install.sh |
| ``` |
| |
| Works on Debian/Ubuntu, Fedora, Arch, openSUSE and NixOS. Installs two systemd services (keeper + guard), runs WARP |
| in local-proxy mode so your server's normal routing and SSH are never touched, and adds `-hop` and `-doctor` commands. |
| On a Linux desktop, install `xdotool` for automatic "continue". |
| </details> |
| |
| <details> |
| <summary><b>Run or build from source</b></summary> |
| |
| ```powershell |
| # get the code: the source zip on https://openhop.cfd, or |
| git clone https://github.com/bernat-lol/openhop.git |
| cd openhop |
| pip install -r requirements.txt |
| python src\openhop_app.py # run |
| powershell -ExecutionPolicy Bypass -File .\build.ps1 # build the .exe |
| ``` |
| |
| Want to help? Open an [Issue](https://github.com/bernat-lol/openhop/issues) first to talk about the change. |
| </details> |
| |
| --- |
| |
| ## Disclaimer |
| |
| openhop is an independent, unofficial project. It isn't affiliated with or endorsed by OpenCode or Cloudflare. Use it at |
| your own risk and follow the terms of the services you use. |
| |
| ## Credits |
| |
| **openhop** · [openhop.cfd](https://openhop.cfd) · based on the original |
| [Opencode Unlimited](https://github.com/ShadowySphinX/Opencode-Unlimited-Limit-Bypass-) by **Avatar (ShadowySphinX)**. |
| |
| ## License |
| |
| [MIT](LICENSE). Copyright (c) 2026 Avatar (ShadowySphinX). Modifications Copyright (c) 2026 openhop (https://openhop.cfd). |