Turn Your Phone into a Claude Code Remote with Just Two Commands

I was hesitant to use the popular Happy project because it stores encrypted data, API keys, and environment variables on its servers, which felt unsafe. Discovering tiann’s hapi —named after the pinyin of “Happy”—changed my mind, as it runs a local agent and uses the phone only as a remote controller.

Data sovereignty is the core claim: unlike Happy, which relies on a shared backend with PostgreSQL and Redis, hapi runs a per‑user hub binary that forwards traffic without storing anything. Transmission encryption is provided by WireGuard + TLS, so the relay sees only ciphertext.

Installation is straightforward. The hub and CLI are bundled, and you can install via npm, Homebrew, or run directly with npx. The two commands to start the system are:

npx @twsxtd/hapi hub --relay    # start hub with end‑to‑end encrypted relay
npx @twsxtd/hapi                # launch Claude Code

Running these commands prints a URL and QR code; scanning the QR code or opening the URL on a phone connects the mobile web UI to the local hub. All traffic between the phone and the hub is encrypted end‑to‑end.

If you prefer your own tunnel (e.g., Cloudflare Tunnel or Tailscale), you can bypass hapi’s relay and self‑host the hub, as documented in the GitHub guide.

Key features include:

Seamless session transfer: start Claude Code on a desktop, then pick up the same session on your phone without losing context.

Local/remote mode switching, which Happy lacks, providing faster local responses and occasional remote checks.

AFK batch operations: prompts that would normally require desktop interaction can be approved or denied from the phone.

Built‑in voice assistant for hands‑free operation, though recognition degrades in noisy environments.

Full terminal access from the mobile web UI, allowing log inspection and service restarts without VPN.

Workspace restriction via the --workspace-root flag, limiting the phone’s file‑tree view to selected project directories.

Slash‑command completion (e.g., /deploy, /test) for quick script execution without memorizing full commands.

hapi also fixes several issues present in Happy, such as rendering bugs in AskUserQuestion and session history restoration. The project has over 4.4k stars on GitHub, is written in TypeScript, and is licensed under AGPL‑3.0, making it suitable for auditing or forking.

To compile from source:

git clone https://github.com/tiann/hapi.git
cd hapi
bun install
bun run build:single-exe

The resulting single‑file binary can be placed in PATH for easy use.

After a week of use, the author finds the primary benefit to be that no data leaves the local machine—code, keys, and environment variables stay on the host, while the phone acts merely as a remote controller. The main drawback is that if the relay goes down, the remote channel breaks, requiring self‑hosting knowledge. Voice control is considered optional.

Overall, for developers who rely on Claude Code or Codex and need mobile access without compromising data sovereignty, hapi offers a lightweight, secure solution that can be set up with just two commands.

https://github.com/tiann/hapi