HAPIR

App for Claude Code / Codex / Gemini / OpenCode, vibe coding anytime, anywhere.

Run AI coding sessions and control them remotely through Web / PWA / Telegram Mini App.

Note: This project is heavily based on hapi by @tiann. Most of the codebase originates from hapi, with modifications to certain features. Configurations and protocols are not compatible with the original project.

中文文档

Features

• Multi-agent support — Claude Code, Codex, Gemini, OpenCode
• Remote control — Web UI, PWA, Telegram Mini App
• Seamless switching — Switch between local and remote sessions freely
• Permission management — Approve or deny AI requests from your phone
• Terminal access — Remote PTY via WebSocket
• File browser — Browse files with git status and diff
• Voice assistant — ElevenLabs integration
• Push notifications — Web Push and Telegram bot
• Offline support — PWA with offline message buffering

Architecture

Rust workspace with six crates plus a root binary:

hapir/
├── src/main.rs              # CLI entry point
├── crates/
│   ├── hapir-shared/        # Protocol & shared types
│   ├── hapir-hub/           # Axum server
│   ├── hapir-cli/           # CLI client
│   ├── hapir-infra/         # Shared infrastructure (WS client, RPC, handlers)
│   ├── hapir-runner/        # Background runner process
│   └── hapir-acp/           # Agent protocol backends (ACP, Codex App Server)
└── web/                     # React + Vite + TypeScript frontend

• hapir-shared — WebSocket protocol, domain types, i18n
• hapir-hub — Central server with SyncEngine, SQLite persistence, SSE, WebSocket rooms
• hapir-cli — Agent orchestration, local/remote loop, session management
• hapir-infra — Shared infrastructure used by CLI and runner: WebSocket client with auto-reconnect, RPC handlers (bash, files, git, ripgrep, etc.), persistence, auth
• hapir-runner — Background runner process for machine registration, WS connection management, and git worktree management
• hapir-acp — Standalone agent protocol backends: ACP SDK, Codex App Server, JSON-RPC 2.0 stdio transport

The frontend is a React 19 + Vite + Tailwind CSS PWA. TypeScript types are auto-generated from Rust schemas via ts-rs.

Prerequisites

• Rust nightly (edition 2024, resolver 3)
• Bun (for frontend)
• Claude Code >= 2.1.47 (for Claude agent)

Build

cargo build                  # Debug build
cargo build --release        # Release build

In release builds, the frontend is compiled and embedded into the hub binary via rust-embed.

To build the frontend separately:

cd web && bun install && bun run build

Usage

Start the hub server:

hapir hub

Run an AI agent session (Claude is the default):

hapir              # Claude (default)
hapir claude
hapir codex
hapir gemini
hapir opencode

Other commands:

hapir auth login   # Save API token
hapir auth status  # Show current config
hapir runner start # Start background runner
hapir mcp          # Run MCP stdio bridge
hapir doctor       # Show diagnostics

Environment Variables

See docs/environment-variables.md for the full reference.

Hub:

Variable	Default	Description
HAPIR_HOME	~/.hapir	Data directory
DB_PATH	{HAPIR_HOME}/hapir.db	SQLite database path
HAPIR_LISTEN_HOST	127.0.0.1	Listen address
HAPIR_LISTEN_PORT	3006	Listen port
HAPIR_PUBLIC_URL	—	Public URL for external access
CORS_ORIGINS	derived from HAPIR_PUBLIC_URL	Comma-separated allowed origins
CLI_API_TOKEN	—	Static token for CLI authentication
TELEGRAM_BOT_TOKEN	—	Telegram bot token
TELEGRAM_NOTIFICATION	true	Set to false to disable Telegram notifications
VAPID_SUBJECT	mailto:admin@localhost	VAPID subject for web push
ELEVENLABS_API_KEY	—	ElevenLabs API key for voice
ELEVENLABS_AGENT_ID	—	ElevenLabs agent ID for voice

CLI / Runner:

Variable	Default	Description
HAPIR_API_URL	http://localhost:3006	Hub URL
CLI_API_TOKEN	—	Authentication token
HAPIR_HOME	~/.hapir	Data directory
HAPIR_EXPERIMENTAL	false	Enable experimental features (true/1/yes)
HAPIR_HOSTNAME	system hostname	Override machine hostname reported to hub
HAPIR_CLAUDE_PATH	claude	Claude Code executable (supports command strings, e.g. bash wrapper.sh)
HAPIR_CODEX_PATH	codex	Codex executable (supports command strings)
HAPIR_GEMINI_PATH	gemini	Gemini CLI executable (supports command strings)
HAPIR_OPENCODE_PATH	opencode	OpenCode executable (supports command strings)
HAPIR_HTTP_MCP_URL	—	HTTP backend URL for MCP stdio bridge
CLAUDE_CONFIG_DIR	~/.claude	Claude config directory (MCP, slash commands)
CODEX_HOME	~/.codex	Codex home directory

Logging is controlled via RUST_LOG (defaults to info).

Acknowledgments

This project is a derivative of hapi. Thanks to @tiann for the original work.

License

This project is licensed under AGPL-3.0, same as the original hapi.