mirror of
https://github.com/wu736139669/hapi.git
synced 2026-08-05 06:24:37 +00:00
weishu
460c393006
- Initialize VitePress documentation site with config, index, and guides - Add guides for quick-start, installation, PWA, how-it-works, FAQ, and why HAPI - Update .gitignore to exclude VitePress cache directory - Update logo.svg with actual icon from web/public/icon.svg - Simplify README.md with link to full installation guide - Remove redundant WHY_NOT_HAPPY.md (content migrated to why-hapi guide)
167 lines
7.6 KiB
Markdown
167 lines
7.6 KiB
Markdown
# How it Works
|
|
|
|
HAPI consists of three interconnected components that work together to provide remote AI agent control.
|
|
|
|
## Architecture Overview
|
|
|
|
```
|
|
┌────────────────────────────────────────────────────────────────────────────┐
|
|
│ Your Local Machine │
|
|
│ │
|
|
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
|
|
│ │ │ │ │ │ │ │
|
|
│ │ HAPI CLI │◄───────►│ HAPI Server │◄───────►│ Web App │ │
|
|
│ │ │ Socket │ │ SSE │ (embedded) │ │
|
|
│ │ + AI Agent │ .IO │ + SQLite │ │ │ │
|
|
│ │ │ │ + REST API │ │ │ │
|
|
│ └──────────────┘ └──────┬───────┘ └──────────────┘ │
|
|
│ │ │
|
|
│ │ localhost:3006 │
|
|
└───────────────────────────────────┼────────────────────────────────────────┘
|
|
│
|
|
┌─────────▼─────────┐
|
|
│ Tunnel (Optional)│
|
|
│ Cloudflare/ngrok │
|
|
└─────────┬─────────┘
|
|
│
|
|
┌───────────────────────────────────┼────────────────────────────────────────┐
|
|
│ Public Internet │
|
|
│ │ │
|
|
│ ┌─────────────────────────┼─────────────────────────┐ │
|
|
│ │ ▼ │ │
|
|
│ │ ┌──────────────┐ ┌──────────────┐ │ │
|
|
│ │ │ │ │ │ │ │
|
|
│ │ │ Telegram │ │ PWA / │ │ │
|
|
│ │ │ Mini App │ │ Browser │ │ │
|
|
│ │ │ │ │ │ │ │
|
|
│ │ └──────────────┘ └──────────────┘ │ │
|
|
│ │ │ │
|
|
│ └───────────────────────────────────────────────────┘ │
|
|
│ Your Phone │
|
|
└────────────────────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
## Components
|
|
|
|
### HAPI CLI
|
|
|
|
The CLI is a wrapper around AI coding agents (Claude Code, Codex, Gemini). It:
|
|
|
|
- Starts and manages coding sessions
|
|
- Registers sessions with the HAPI server
|
|
- Relays messages and permission requests
|
|
- Provides MCP (Model Context Protocol) tools
|
|
|
|
**Key Commands:**
|
|
```bash
|
|
hapi # Start Claude Code session
|
|
hapi codex # Start OpenAI Codex session
|
|
hapi gemini # Start Google Gemini session
|
|
hapi daemon start # Run background service for remote session spawning
|
|
```
|
|
|
|
### HAPI Server
|
|
|
|
The server is the central hub that connects everything:
|
|
|
|
- **HTTP API** - RESTful endpoints for sessions, messages, permissions
|
|
- **Socket.IO** - Real-time bidirectional communication with CLI
|
|
- **SSE (Server-Sent Events)** - Live updates pushed to web clients
|
|
- **SQLite Database** - Persistent storage for sessions and messages
|
|
- **Telegram Bot** - Notifications and Mini App integration
|
|
|
|
### Web App
|
|
|
|
A React-based PWA that provides the mobile interface:
|
|
|
|
- **Session List** - View all active and past sessions
|
|
- **Chat Interface** - Send messages and view agent responses
|
|
- **Permission Management** - Approve or deny tool access
|
|
- **File Browser** - Browse project files and view git diffs
|
|
- **Remote Spawn** - Start new sessions on any connected machine
|
|
|
|
## Data Flow
|
|
|
|
### Starting a Session
|
|
|
|
```
|
|
1. User runs `hapi` in terminal
|
|
│
|
|
▼
|
|
2. CLI starts Claude Code (or other agent)
|
|
│
|
|
▼
|
|
3. CLI connects to server via Socket.IO
|
|
│
|
|
▼
|
|
4. Server creates session in database
|
|
│
|
|
▼
|
|
5. Web clients receive SSE update
|
|
│
|
|
▼
|
|
6. Session appears in mobile app
|
|
```
|
|
|
|
### Permission Request Flow
|
|
|
|
```
|
|
1. AI agent requests tool permission (e.g., file edit)
|
|
│
|
|
▼
|
|
2. CLI sends permission request to server
|
|
│
|
|
▼
|
|
3. Server stores request and notifies via SSE + Telegram
|
|
│
|
|
▼
|
|
4. User receives notification on phone
|
|
│
|
|
▼
|
|
5. User approves/denies in web app or Telegram
|
|
│
|
|
▼
|
|
6. Server relays decision to CLI via Socket.IO
|
|
│
|
|
▼
|
|
7. CLI informs AI agent, execution continues
|
|
```
|
|
|
|
### Message Flow
|
|
|
|
```
|
|
User (Phone) Server CLI
|
|
│ │ │
|
|
│──── Send message ──────►│ │
|
|
│ │─── Socket.IO emit ───►│
|
|
│ │ │
|
|
│ │ ├── AI processes
|
|
│ │ │
|
|
│ │◄── Stream response ───│
|
|
│◄─────── SSE ────────────│ │
|
|
│ │ │
|
|
```
|
|
|
|
## Communication Protocols
|
|
|
|
### CLI ↔ Server: Socket.IO
|
|
|
|
Real-time bidirectional communication for:
|
|
- Session registration and heartbeat
|
|
- Message relay (user input → agent)
|
|
- Permission requests and responses
|
|
- Metadata and state updates
|
|
- RPC method invocation
|
|
|
|
### Server ↔ Web: REST + SSE
|
|
|
|
- **REST API** for actions (send message, approve permission)
|
|
- **SSE stream** for real-time updates (new messages, status changes)
|
|
|
|
### External Access: Tunnel
|
|
|
|
For remote access outside your local network:
|
|
- **Cloudflare Tunnel** (recommended) - Free, secure, reliable
|
|
- **Tailscale** - Mesh VPN for private networks
|
|
- **ngrok** - Quick setup for testing
|