openhop

srcSource code

Source code

Every file of openhop's latest version, exactly as published. Read anything, or download it all as a zip.

Commit
c8cfb4c
Date
16 Nov 2026
Files
62 files
Download the source (zip)

zip · 758 KB · SHA-256 6ce65b028777bf92…

README.md

226 lines · 9.9 KB · Markdown

> [!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>
![openhop](assets/ui-preview.png)
---
## 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).