HAPI pairs a hub to your phone by QR code, and its CLI build target only typechecks

Three names travel with the project and only one of them installs

Three identifiers travel with this project, and only one of them is what you type. The repository is tiann/hapi, the root package.json names itself hapi and sets private to true, and the install commands reach for a scope that matches neither: @twsxtd/hapi. The site it points at is hapi.run. Once installed, the entry point is a hub, with `hapi server` kept as an alias for anyone who learned the older word.

npx @twsxtd/hapi hub --relay     # start hub with E2E encrypted relay
npx @twsxtd/hapi                 # choose an agent and start a session

A private root manifest next to a published package name is a normal split. It does mean the name in the repository URL, the name in the docs, and the name on the registry are three separate strings to keep straight when a resolve fails.

The CLI half of the build is a typecheck wearing a build name

The root `build` script reads like a pipeline and has one hollow step in it. It chains build:cli, build:web, an embedded asset generation inside the hub directory, and build:hub. But build:cli is `bun run typecheck:cli`, which resolves to `cd cli && bun run typecheck`: no bundler, no output directory, no artifact. The executable that users actually run comes from a different recipe entirely, where `cd cli && bun run build:exe:allinone` is what compiles. Two single-executable targets sit side by side, build:single-exe and build:single-exe:all, differing only in whether that last step ends in `:all`.

Four workspaces get typechecked and five get tested

Seven directories are declared as workspaces, and the two verification scripts disagree about which ones they cover. typecheck fans out over cli, web, hub and relay. test walks cli, hub, web, shared and relay. So shared is exercised by the test chain and has no typecheck entry among the scripts the manifest sets out, which leaves its types checked only as far as the tests happen to reach them. Two neighbours round out the object: an integration test target the plain test script never calls, and a dev mode that starts hub and web in parallel from the root.

The single binary recipe downloads the tunnel it later ships

Users and contributors run different toolchains, and only one of them has a network step in it. Nothing about starting a session asks for Bun, because the getting started block goes through npx. Building asks for Bun 1.4.4 exactly, matched by a pinned packageManager field, a bun.lock at the root and a bunfig.toml beside it.

bun install
bun run build:single-exe

That recipe opens with download:tunwg, which runs hub/scripts/download-tunwg.ts, and only then compiles. The relay is described as WireGuard plus TLS, so the piece fetched at build time is the tunnel the encrypted path depends on. A contributor assembling a binary takes that component from the network, which is worth knowing before treating a locally built single executable as fully self-contained.

Pairing is a URL and two QR codes, and approvals are one tap

The hub prints a URL and two QR codes. You open the web URL in a browser, or scan the companion code with a native app. It matters because what gets paired is a live terminal on the working machine, and the feature list turns the phone into an approver: approve AI requests with one tap while away from the desk. The native clients carry chat, approvals, session creation, files, dictation and push notifications, and the web build keeps a voice assistant for hands-free work. `--relay` is the option paired with WireGuard and TLS in the getting started block. Browsing files from the web stays off until you name a root, since `hapi runner start --workspace-root <path>` is what turns on scoped file trees and session starts in allowed subdirectories.

Shared Codex sessions pin a floor on somebody else's tool

HAPI wraps an agent instead of replacing it, and one of its features pins a version on a tool it does not ship. Shared Codex sessions, where the same run is reachable from a terminal and a phone at once, require Codex 0.154.0 or newer, with usage and limits kept on a separate guide page. The wrapper shape is why `hapi <agent> [options]` can hand you `hapi claude` or `hapi codex` and still drop you into the agent you already know, and why the supported list runs long: Claude Code, Codex, Cursor Agent, Grok Build, OpenCode, Kimi, Copilot, Antigravity, Pi and DeepSeek Harness. One scripting rule falls out of that design. Scripts must specify the agent explicitly, so the chooser a bare npx call opens cannot be driven from a shell script, a cron job or a CI step.

The Telegram Mini App is in the pitch and absent from the guide index

The pitch covers three clients and the documentation index names two of them. The opening line promises native iOS and Android apps, Web and PWA, and a Telegram Mini App, and the repository description repeats the Telegram part. The list that follows covers native apps, Web and PWA, how it works, supported agents, the voice assistant, why HAPI, and the FAQ. No Telegram page appears in that index, so the third client arrives announced rather than pointed at. Self-hosting gets the same short treatment: Cloudflare Tunnel and Tailscale are named in passing and live in the installation guide. The strongest claim in the file is deferred too. HAPI calls itself a local-first alternative to Happy, hands you a Why Not Happy? link for the key differences, and credits the original project under the transliteration `哈皮`.

Three releases in three days, and the branch is past them

The release cadence is bursty and the default branch is ahead of it. Three releases sit inside two days: v0.34.0 on 2026-11-02, v0.33.6 and v0.33.5 on 2026-11-01, while the last push to main is dated 2026-11-02. Between them the tree holds what a monorepo of this shape needs and nothing decorative: ios and android clients, e2e tests beside playwright.config.ts, a relay workspace, a shared one, cli, hub, web, docs and website, plus AGENTS.md, CONTRIBUTING.md and SECURITY.md at the root. The licence is AGPL-3.0, which is the part to read before you wrap any of it inside something you distribute.

Editorial conclusion

HAPI fits one specific habit: you leave an agent running on a machine you control and approve its requests from your phone. Before that, read the pairing path for your own deployment and decide what the hub URL is worth to anyone who ends up holding it, because the same approval flow is what runs commands in that terminal. Skip it if your automation has to pick an agent for itself, since the chooser is interactive only. Contributors should expect Bun 1.4.4, a build-time download of the tunnel component, and a CLI build target that typechecks without producing anything.

Frequently asked questions

Official sources

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