hapi/docs/guide/how-it-works.md

How it Works

HAPI connects coding agents, a self-hosted hub, and web/native clients for remote control.

Architecture Overview

CLI + Agent  <---- Socket.IO /cli ---->  Hub + SQLite
Runner       <---- Socket.IO /cli ---->       |
  |                                          | REST + SSE
  +-- spawns CLI sessions                    |
                                     Web / PWA / Mini App
                                     Native iOS / Android

The hub can run on your local desktop or a remote host (VPS, cloud, etc.). Clients reach it directly or through an optional tunnel/reverse proxy. Use an HTTPS hub origin for native pairing; see Deployment.

Components

HAPI CLI

The CLI is a wrapper around AI coding agents. It supports multiple agent flavors out of the box — see Supported agents for the full list. It:

• Starts and manages coding sessions
• Registers sessions with the HAPI hub
• Relays messages and permission requests
• Provides MCP (Model Context Protocol) tools

Key Commands:

hapi              # Choose an agent interactively and start a session
hapi <agent>      # Start a supported agent directly (required in scripts)
hapi runner start # Run background service for remote session spawning
hapi ping-peer --list  # Shell peer shortlist (prefer MCP list_peers in-session)

MCP peer tools (same hub/namespace as the session): list_peers (discover), inspect_peer (read), ping_peer (message), spawn_peer (create with a required remit). These work from runner-spawned sessions even when the hub is on another host - see Installation → Split hub + remote runner. Never treat machine-spawn HTTP 200 as a working peer. In-session spawn_peer auto-stamps a durable Parent [title](/sessions/<uuid>) chip onto the remit (UUID is identity; titles are decoration). Runners that must keep agents out of other sessions' contexts can hide all four with HAPI_DISABLE_PEER_TOOLS=1 - see Installation → Disabling peer tools.

HAPI Hub

The hub is the central service 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 and native clients
• SQLite Database - Persistent storage for sessions and messages
• Telegram Bot - Notifications and Mini App integration

Web App

A React-based PWA usable in a browser, as an installed PWA, or as a Telegram Mini App:

• 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
• Terminal View - Run commands on the working machine from your browser
• Voice Assistant - Talk to your agent and approve permissions by voice (see Voice input and assistant)
• Session References - Copy a session reference or mention another conversation for context
• Remote Spawn - Start new sessions on any connected machine

Native apps

The iOS SwiftUI/UIKit and Android Kotlin Compose apps are independent clients of the hub. Both support sessions/chat, approvals and questions, new sessions, attachments, files/Git, Scratchlist, dictation and native push. Their interactive traffic uses the same REST + SSE client API; background notifications use FCM/APNs with the native push contract.

The apps have their own navigation and rendering. Protocol fixture conformance does not imply web UI parity: the terminal, Work Graph and realtime voice controls remain web features. See Native apps for current capabilities, platform differences and install/pairing instructions.

Data Flow

Starting a Session

1. User runs `hapi` and chooses an agent
         │
         ▼
2. CLI starts the selected agent
         │
         ▼
3. CLI connects to hub via Socket.IO
         │
         ▼
4. Hub creates session in database
         │
         ▼
5. Web/native 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 hub
         │
         ▼
3. Hub stores request and sends SSE + configured notifications
         │
         ▼
4. User receives notification on phone
         │
         ▼
5. User approves/denies in a native or web client
         │
         ▼
6. Hub relays decision to CLI via Socket.IO
         │
         ▼
7. CLI informs AI agent, execution continues

Message Flow

User (Phone)                 Hub                     CLI
     │                         │                       │
     │──── Send message ──────►│                       │
     │                         │─── Socket.IO emit ───►│
     │                         │                       │
     │                         │                       ├── AI processes
     │                         │                       │
     │                         │◄── Stream response ───│
     │◄─────── SSE ────────────│                       │
     │                         │                       │

Communication Protocols

CLI ↔ Hub: 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

Hub ↔ Web/native clients: 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:

• Built-in relay (hapi hub --relay) - Managed tunwg tunnel (WireGuard + TLS), no third-party account required
• Cloudflare Tunnel (recommended) - Free, secure, reliable
• Tailscale - Mesh VPN for private networks
• ngrok - Quick setup for testing

Seamless Handoff

HAPI's defining feature is the ability to seamlessly hand off control between local terminal and remote devices without losing session state.

Local Mode

When working in local mode, you have the full terminal experience — it is the native agent CLI (Claude Code, Codex, OpenCode, and more):

• Direct keyboard input with instant response
• Full terminal UI with syntax highlighting
• Best for focused, uninterrupted coding sessions
• Agent tools run on your machine; model requests use the provider configured in the agent

Remote Mode

Switch to remote mode when you need to step away:

• Control via Web/PWA/Telegram from any device
• Approve permissions on the go
• Monitor progress while away from your desk
• Session continues running on your local machine

How Switching Works

┌─────────────────┐                    ┌─────────────────┐
│   Local Mode    │◄──────────────────►│   Remote Mode   │
│   (Terminal)    │                    │   (Phone/Web)   │
└─────────────────┘                    └─────────────────┘
        │                                      │
        │  ┌────────────────────────────┐      │
        └─►│  Same Session, Same State  │◄─────┘
           └────────────────────────────┘

Local → Remote:

• Open the session on your phone/web and send a message
• HAPI keeps the conversation going on the same working machine

Remote → Local:

• Continue typing in the terminal
• If the terminal shows the remote-control screen, press double-space to return to local input

Some agents keep both interfaces available at once, so no switch is needed. For Codex terminal-exit and resume behavior, see Usage and limits.

Use Cases

1. Remote Control While Away - Start a session at your desk, continue from your phone during commute or coffee break

2. Permission Approval - AI requests file access, you get notified on phone, approve with one tap, session continues

3. Multi-Device Collaboration - View session progress on your phone while your desktop does the heavy lifting