weishu fa63529d04 fix: persist CLI_API_TOKEN from env var to settings when not already saved
When CLI_API_TOKEN is provided via environment variable, persist it to settings.json
if not already saved. This prevents token regeneration if the env var fails to load
on subsequent startups, ensuring token consistency across server restarts.
2025-12-25 15:48:45 +08:00
2025-12-25 15:18:03 +08:00
2025-12-25 15:18:03 +08:00
2025-12-16 15:03:50 +08:00

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.

Quickstart

  1. Start the server on a machine you control:
hapi server
# or: npx @twsxtd/hapi server
  1. If the server has no public IP, expose it over HTTPS:

  2. 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
  1. Open the UI in a browser at the server URL and log in with CLI_API_TOKEN.

Telegram Mini App (optional)

To use Telegram for notifications and the Mini App:

  1. Create a bot with @BotFather and get the token.

  2. Expose your server over HTTPS (Cloudflare Tunnel, Tailscale, etc.).

  3. Add environment variables:

WEBAPP_URL="https://your-domain.example"
TELEGRAM_BOT_TOKEN="..."
  1. Start the server and send /start to the bot to get your chat ID.

  2. Add your chat ID and restart:

ALLOWED_CHAT_IDS="12345678"
  1. Run /app in 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 (claude on 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 Happy
  • cli/README.md - CLI usage and config
  • server/README.md - Server setup and architecture
  • web/README.md - Web app behavior and dev workflow

License

  • cli: MIT
  • others: LGPLv2
S
Description
GitHub 镜像: wu736139669/hapi(每日自动同步)
Readme AGPL-3.0
141 MiB
Languages
TypeScript 99.5%
CSS 0.2%
JavaScript 0.2%