HAQI

Run official Claude Code / Codex / Gemini / OpenCode sessions locally and control them remotely through a Web / PWA / Telegram Mini App.

Why HAQI? HAQI is a local-first alternative to Happy. See Why Not Happy? for the key differences.

Features

• Seamless Handoff - Work locally, switch to remote when needed, switch back anytime. No context loss, no session restart.
• Native First - HAQI wraps your AI agent instead of replacing it. Same terminal, same experience, same muscle memory.
• AFK Without Stopping - Step away from your desk? Approve AI requests from your phone with one tap.
• Your AI, Your Choice - Claude Code, Codex, Gemini, OpenCode—different models, one unified workflow.
• Terminal Anywhere - Run commands from your phone or browser, directly connected to the working machine.
• Voice Control - Talk to your AI agent hands-free using the built-in voice assistant.

Branch-only features（本分支独有功能）

This branch includes a focused set of web UX upgrades. Based on the commit history, the optimizations are grouped as follows:

1) Session Sidebar / 项目会话侧边栏

• Project-level quick create (+)
  Add a new session directly under an existing project entry.
• Density switch (comfortable / compact)
  Sidebar list can switch between two densities.
• Desktop resizable sidebar
  VSCode-like drag-to-resize splitter behavior.
• Responsive sidebar behavior
  • Desktop supports show/hide.
  • Mobile uses drawer-style interaction with improved controls.
• Project reorder by drag-and-drop (persisted)
  • No dedicated handle button required.
  • Desktop direct drag; mobile long-press drag.
  • Order is persisted locally.
• Virtualized session list Better performance and smoother rendering with many items.

2) Chat History Loading / 聊天历史加载体验

• Stabilized auto-load scroll retention Loading older messages keeps viewport position stable.
• Reduced jump-to-top behavior across batches Improved continuity while scrolling through long history.
• History loading feedback + behavior tuning Better loading-state handling during top-triggered history fetch.

3) Quality & Test Coverage / 质量与测试

• Added targeted tests for:
  • history scroll retention logic
  • project group reorder helpers

Demo

hapi-demo.mp4

Getting Started

npx @jasonczc/haqi hub --relay   # start hub with E2E encrypted relay
npx @jasonczc/haqi               # run claude code

haqi server remains supported as an alias.

The terminal will display a URL and QR code. Scan the QR code with your phone or open the URL to access.

The relay uses WireGuard + TLS for end-to-end encryption. Your data is encrypted from your device to your machine.

For self-hosted options (Cloudflare Tunnel, Tailscale), see Installation

Docs

• App
• How it Works
• Voice Assistant
• Why HAQI
• FAQ

Build from source

bun install
bun run build:single-exe

Release (tag + GitHub Actions + npm OIDC)

This repo publishes @jasonczc/haqi and platform packages from the Release workflow.

1. Bump cli/package.json version (must match the tag).
2. Push a tag like v0.15.3.
3. GitHub Actions will:
   • build all binaries,
   • publish platform npm packages + main package,
   • create a GitHub Release.

npm must be configured with Trusted Publishing (OIDC) for: @jasonczc/haqi, @jasonczc/haqi-darwin-arm64, @jasonczc/haqi-darwin-x64, @jasonczc/haqi-linux-arm64, @jasonczc/haqi-linux-x64, @jasonczc/haqi-win32-x64.

Development workflow: rebuild + deploy locally

Use this when validating frontend/CLI changes on your local running hub.

Recommended: split stable runtime vs source dev runtime. Do not share one HAPI_HOME between them.

# Stable runtime (installed binary)
export HAPI_HOME="$HOME/.hapi-stable"
export HAPI_LISTEN_PORT=3006
haqi runner start
haqi hub

# Source dev runtime (repo)
export HAPI_HOME="$HOME/.hapi-dev"
export HAPI_LISTEN_PORT=3016
export HAPI_PUBLIC_URL="http://localhost:3016"
bun run dev

If you switch branches often, use branch-specific dev homes:

export HAPI_HOME="$HOME/.hapi-dev-$(git rev-parse --abbrev-ref HEAD | tr '/' '-')"

# 1) Build all-in-one binary (web + hub + cli)
bun run build:single-exe

# 2) Deploy binary to current user install path (Linux example)
cp -a ~/.local/bin/haqi ~/.local/bin/haqi.bak.$(date +%Y%m%d-%H%M%S)
install -m 755 ./cli/dist-exe/bun-linux-x64/hapi ~/.local/bin/haqi

# 3) Restart runtime processes
haqi runner stop || true
haqi runner start

Or use the helper script:

./scripts/deploy-local-binary.sh

Optional status check:

./scripts/hapi-local.sh status

Credits

HAQI means "哈皮" a Chinese transliteration of Happy. Great credit to the original project.