tiann/hapi: control Claude Code and Codex sessions from your phone

What HAPI adds to an agent session you already run

The README frames HAPI as an app for Claude Code, Codex, Gemini and OpenCode users who want to keep coding away from the desk. The mechanism it describes is a wrapper, not a replacement: the README's feature list says HAPI "wraps your AI agent instead of replacing it", so the terminal session you started stays the terminal session you are in. What changes is that a web client, a PWA or a Telegram Mini App can reach it.

The target user is specific. You already have Claude Code, Codex, Cursor Agent, Grok Build, OpenCode, Kimi, Copilot, Antigravity, Pi or DeepSeek Harness installed and working locally. You lose nothing by staying in the terminal, and the remote surface exists for the moments you step away. The README's own framing of that case is approving AI requests from a phone with one tap. If you have never run one of these agents, HAPI has nothing to wrap.

The README positions HAPI against Happy, calling itself "a local-first alternative to Happy" and pointing to docs/guide/why-hapi.md for the differences. That document is the place to look for the actual comparison; the README only states the claim.

Hub, relay and the handoff between local and remote

The repository layout shows the split clearly: top-level directories for cli, hub, web, relay, shared, and separate ios and android trees, with a bun workspaces list in package.json covering cli, shared, hub, web, website, docs and relay. The hub is the process that holds sessions and serves the web interface. The relay is the piece that makes those sessions reachable from outside your network.

The README describes the relay as using WireGuard plus TLS, with the claim that data is "encrypted from your device to your machine". That is an end-to-end arrangement rather than a plain reverse proxy, which matters because the whole point of the tool is that your prompts and your agent's output leave the local machine. The README also points to docs/guide/installation.md for self-hosted options using Cloudflare Tunnel or Tailscale, so the relay is one path rather than the only path.

The handoff itself is the feature the README leads with. It describes working locally, switching to remote, and switching back with no context loss and no session restart. That is the design constraint that explains the wrapper approach: because HAPI does not own the agent process, moving between surfaces does not mean serialising and restoring a conversation. The README does not document what happens to an in-flight tool call if the hub process is killed, and it does not describe a rollback path for a session that has already been driven from two clients.

Installing HAPI and starting your first remote session

The README's Getting Started section gives two commands. The first starts the hub with the end-to-end encrypted relay enabled, and the second starts Claude Code under HAPI. Both run through npx against the published package name.

npx @twsxtd/hapi hub --relay     # start hub with E2E encrypted relay
npx @twsxtd/hapi                 # run claude code

The README notes that `hapi server` remains supported as an alias for the hub command, so older instructions you find elsewhere are not necessarily wrong.

After the hub starts, the README says the terminal displays a URL and a QR code. Scan the QR code with your phone, or open the URL in a browser, and you reach the web client. That QR code is also how the in-development native clients pair, according to the README's native apps section, which says they follow the same protocol and points at docs/api/client-contract/index.md.

If you want to build the single executable yourself rather than run the published package, the README states Bun 1.4.0 is required and gives two commands.

bun install
bun run build:single-exe

The package.json confirms the toolchain: packageManager is pinned to [email protected], and build:single-exe runs download:tunwg, then build:web, then generates embedded web assets inside hub, then builds the all-in-one executable from cli. The download:tunwg step fetches a WireGuard component, which is consistent with the relay description in the README. There is no documented npm or pnpm path for building from source.

The workspace browser is opt-in, and that is deliberate

One feature in the README is gated behind an explicit flag rather than enabled by default. The workspace browser lets you browse scoped file trees from the web and start sessions in allowed subdirectories, and it is turned on with one or more `hapi runner start --workspace-root <path>` flags.

That design choice is worth reading as a security decision. A tool that lets a phone drive a shell on your working machine is a large surface, and file browsing widens it. Requiring a flag per allowed root means the default state does not expose your filesystem, and the scope is whatever paths you name. The README does not describe what happens when two workspace roots overlap, or whether a session started inside an allowed subdirectory can reach above it.

This is also where HAPI's usefulness and its risk sit in the same place. Terminal Anywhere, as the README calls it, means commands you issue from a phone run on the working machine directly. Voice Control means the same commands can be spoken. The README does not document an approval step for terminal commands the way it describes one-tap approval for AI requests, so the two features do not have the same gate.

Native clients are not ready, and the web app is the real client

The README is explicit that the iOS and Android apps are in development. It says fully native SwiftUI and Kotlin Compose clients live under ios/ and android/, that they pair by scanning the same terminal QR code as the web app, and that they follow the same protocol. The repository layout confirms both directories exist, but the README does not claim they are released, and it does not give install instructions for either.

So the practical client today is the web app and the PWA, plus the Telegram Mini App. That is a real constraint if you were hoping for a store-distributed app with background notifications handled by the OS. The PWA documentation is at docs/guide/pwa.md, and that is where the behaviour of the web client is described.

This is the case where HAPI is the wrong tool. If your requirement is a finished mobile application with platform integration, the README points you at something that does not exist yet. If your requirement is reaching a session from a browser on a phone, the web client is the supported answer.

How HAPI differs from Happy, and from just using SSH

The README names Happy as the project HAPI positions against, describing itself as a local-first alternative and crediting Happy as the original project. The name HAPI is, per the README's credits, a Chinese transliteration of Happy. The stated difference is local-first operation, with the details deferred to docs/guide/why-hapi.md. If you are choosing between the two, that document is the comparison the project itself offers, and the README alone does not enumerate the differences.

The other alternative is not a product but a habit: SSH into the machine and run the agent there. HAPI's answer to that is the handoff and the phone-shaped interface. With SSH you get a terminal on a small screen, which is workable for reading and awkward for approving a request while walking. HAPI's web client and Telegram Mini App exist to make that specific interaction cheap. What SSH gives you that HAPI does not is the absence of a relay, a hub process and a web server in the path. If you already have a working remote setup you trust, HAPI adds components you would have to reason about.

Licence and the cost of keeping up

HAPI is licensed AGPL-3.0. The practical consequence for most readers is the network clause: if you modify HAPI and let users interact with it over a network, the licence's terms reach that deployment in a way permissive licences do not. Running the published package for your own sessions is not the case that raises questions. Forking it into something you host for other people is. That is a description of the licence, not legal advice, and the LICENSE file in the repository is the text that governs.

The upgrade picture is active. The last push to main was on 2026-08-19, and the most recent releases listed are v0.29.0 on the same day, v0.28.0 on 2026-08-17 and v0.27.3 on 2026-08-12. Three releases inside eight days is a fast cadence, which cuts both ways: fixes arrive quickly, and a tool that wraps other fast-moving agents has to keep moving to stay compatible. The README lists ten agents, and each one can change its interface independently.

One upgrade cost is visible in the build scripts. Because build:single-exe runs download:tunwg before building, a from-source build depends on a network fetch of a WireGuard component at build time. That is an external dependency in your build, not just in your runtime.

Editorial conclusion

Adopt HAPI if you already run Claude Code, Codex, Cursor Agent, Grok Build or OpenCode in a terminal and want to approve requests or run commands from a phone without restarting the session. Skip it if you need a supported native iOS or Android client today, since the README states the SwiftUI and Kotlin clients are still in development, or if AGPL-3.0 obligations are a problem for how you distribute software. Before committing, verify three things yourself: that the relay option fits your threat model by reading docs/guide/installation.md for the Cloudflare Tunnel and Tailscale alternatives, that the agents you actually use appear in docs/guide/agents.md, and that your machine has Bun 1.4.0 if you intend to build from source rather than run the published package.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes