weishu
0be023b23b
Adds support for hosting the web UI separately from the hapi server on static hosts (GitHub Pages, Cloudflare Pages). Users can now set a custom server origin via a dialog on the login screen, with the ability to return to same-origin behavior. Changes include: - New useServerUrl hook for managing server URL configuration and storage - Updated API client to support baseUrl parameter for all requests - Enhanced login UI with server picker dialog (top-right button) - Auth system now keys tokens per baseUrl to support multiple servers - SSE connection updated to use configured baseUrl - Documentation updates for standalone hosting setup
hapi
HAPI means "哈皮," a Chinese transliteration of Happy. Great credit to the original project.
Run Claude Code / Codex / Gemini sessions locally and control them remotely through a Web / PWA / Telegram Mini App.
Why HAPI? HAPI is a local-first alternative to Happy. See Why Not Happy? for the key differences.
Features
- Start AI coding sessions from any machine.
- Monitor and control sessions from your phone or browser.
- Approve or deny tool permissions remotely.
- Browse files and view git diffs.
- Track session progress with todo lists.
- Supports multiple AI backends: Claude Code, Codex, and Gemini.
Installation
Homebrew (macOS/Linux)
brew install tiann/tap/hapi
npm/npx
npx @twsxtd/hapi
Or install globally:
npm install -g @twsxtd/hapi
Prebuilt binary
Download from Releases.
macOS users: Remove the quarantine attribute before running:
xattr -d com.apple.quarantine ./hapi
Quickstart
- Start the server on a machine you control:
hapi server
# or: npx @twsxtd/hapi server
-
If the server has no public IP, expose it over HTTPS:
- Cloudflare Tunnel: https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/
- Tailscale: https://tailscale.com/kb/
-
Run the CLI on the machine where you want sessions:
# If the server is not on localhost:3006
export HAPI_SERVER_URL="https://your-domain.example"
hapi
# or: npx @twsxtd/hapi
- Open the UI in a browser at the server URL and log in with
CLI_API_TOKEN.
Finding Your Access Token
On first run, an Access Token is automatically generated and saved to ~/.hapi/settings.json.
View your token:
cat ~/.hapi/settings.json | grep cliApiToken
Or set your own via environment variable (takes priority over generated token):
export CLI_API_TOKEN="your-secret-token"
Telegram Mini App (optional)
To use Telegram for notifications and the Mini App:
-
Create a bot with @BotFather and get the token.
-
Expose your server over HTTPS (Cloudflare Tunnel, Tailscale, etc.).
-
Add environment variables:
WEBAPP_URL="https://your-domain.example"
TELEGRAM_BOT_TOKEN="..."
-
Start the server and send
/startto the bot to get your chat ID. -
Add your chat ID and restart:
ALLOWED_CHAT_IDS="12345678"
- Run
/appin the bot chat to open the Mini App.
Multi-agent support
hapi- Start a Claude Code session.hapi codex- Start an OpenAI Codex session.hapi gemini- Start a Google Gemini session.
CLI config file
You can store the token in ~/.hapi/settings.json instead of an env var.
Environment variables take priority over the file.
Requirements
- Claude CLI installed and logged in (
claudeon PATH) for Claude Code sessions. - Bun if building from source.
Build from source
bun install
bun run build
Build a single binary with embedded web assets:
bun run build:single-exe
Docs
docs/WHY_NOT_HAPPY.md- Why HAPI exists: architectural differences from Happycli/README.md- CLI usage and configserver/README.md- Server setup and architectureweb/README.md- Web app behavior and dev workflow
License
- cli: MIT
- others: LGPLv2