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

​
Overview

Start coding sessions on your computer and monitor/control them from your phone. Switch between local terminal mode and remote control as your workflow requires.

Local Mode

Full terminal experience with instant response. Best for focused, uninterrupted coding.

Remote Mode

Control via Web/PWA/Telegram. Approve permissions and monitor progress on the go.

​
Session Modes

​
Local Mode

When working in local mode, you have the full terminal experience — it is native Claude Code, Codex, or OpenCode:
  • Direct keyboard input with instant response
  • Full terminal UI with syntax highlighting
  • Best for focused work - uninterrupted coding sessions
  • All processing local - AI runs on your machine

​
Remote Mode

Switch to remote mode when you need to step away:
  • Control from anywhere - 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

​
Switching Between Modes

HAPI makes it trivial to switch control between your terminal and remote devices.

​
Local → Remote

Your session automatically switches to remote mode when:
  1. You receive a message from phone/web
  2. Terminal shows “Remote mode - waiting for input”
  3. Control transfers to your remote device
No manual action required — HAPI detects remote input and switches automatically.

​
Remote → Local

To regain local control from your terminal:
  1. Press spacebar twice (double-space) in the terminal
  2. Terminal instantly switches back to local mode
  3. Continue typing as if you never left
The session state is preserved across mode switches — your conversation history, context, and agent state remain intact.

​
Real-Time Updates

When in remote mode, all changes sync in real-time:
  • Message streaming - See agent responses as they’re generated
  • Permission requests - Get notified instantly on your phone
  • Status changes - Active/inactive session state
  • Tool usage - Watch as the agent uses tools

​
Communication Flow

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

​
Session Control Features

​
From Web/PWA

When controlling remotely, you have access to:

Send Messages

Type instructions and questions to your AI agent

Permission Control

Approve or deny file edits, bash commands, and tool usage

Mode Switching

Change permission modes (default, acceptEdits, YOLO, plan)

Session Management

Abort sessions, switch machines, or spawn new sessions

​
Session Actions

Available actions in the web interface:
ActionDescription
Send MessageGive instructions to the AI agent
Approve/DenyHandle permission requests
Change ModeSwitch permission mode (YOLO, safe, plan)
Abort SessionStop the current session
Switch to RemoteForce session into remote mode
Resume SessionRestart an inactive session

​
Use Cases

​
Remote Control While Away

Start a session at your desk, continue from your phone:
  1. Morning: Start coding session on desktop
  2. Commute: Check progress on phone, approve file edits
  3. Coffee break: Send new instructions via Telegram
  4. Back at desk: Double-space to regain local control

​
Permission Approval

Approve permissions without returning to your desk:
  1. AI requests file access
  2. Get notification on phone (push or Telegram)
  3. Review the permission request
  4. Approve with one tap
  5. Session continues automatically

​
Multi-Device Collaboration

View session progress on multiple devices:
  • Desktop terminal: Primary development interface
  • Phone/tablet: Monitor progress and approve permissions
  • Another computer: Access via web browser
All devices see the same session state in real-time. You can have multiple devices viewing the same session simultaneously.

​
Architecture

The seamless handoff is powered by HAPI’s architecture: 
┌─────────────────┐                    ┌─────────────────┐
│   Local Mode    │◄──────────────────►│   Remote Mode   │
│   (Terminal)    │                    │   (Phone/Web)   │
└─────────────────┘                    └─────────────────┘
        │                                      │
        │  ┌────────────────────────────┐      │
        └─►│  Same Session, Same State  │◄─────┘
           └────────────────────────────┘
  • CLI wraps the AI agent and maintains local state
  • Hub coordinates communication via Socket.IO and SSE
  • Web app provides remote interface with real-time updates
  • SQLite persists session history and messages

​
Best Practices

  • Writing code with frequent iterations
  • Reading long agent responses
  • Need immediate keyboard response
  • Working with sensitive information
  • Away from your desk
  • Need to approve permissions
  • Monitoring long-running tasks
  • Want notifications on your phone
  • Switch freely — there’s no penalty
  • Use remote mode for approval workflows
  • Return to local mode for intensive coding
  • Keep the terminal open to maintain session

PWA

Install HAPI as a native-like app

Telegram

Get notifications via Telegram

Permissions

Control agent access to tools

Build docs developers (and LLMs) love

Get started for freeTalk to us