How ForkOff Works
A three-component system connecting your phone to Claude Code on your laptop. End-to-end encrypted, open source, and designed so the relay server never sees your data.
System Architecture
The relay forwards encrypted blobs between device UUIDs. It never decrypts, processes, or stores message content.
The Three Components
Each component has a single responsibility. Together they form a secure, real-time bridge between your phone and your AI coding sessions.
Mobile App
React Native / Expo
- ●Monitor sessions in real-time
- ●Approve or deny tool operations
- ●Manage projects and devices
- ●Runs on iOS and Android
CLI Tool
Node.js / npm package
- ●Bridges Claude Code to your phone
- ●Hooks into Claude Code's event system
- ●Streams messages, tools, and thinking
- ●Runs on your development machine
Backend Relay
NestJS / WebSocket
- ●Routes encrypted events between devices
- ●Stores nothing — stateless by design
- ●Relay-blind: can't read your data
- ●Handles device rooms and routing
Pairing Flow
Connect your phone to your development machine in under 30 seconds. One-time setup per device.
Install the CLI
npm i -g forkoff
One-time global install on your dev machine.
Run forkoff pair
Generates a QR code in your terminal
The QR encodes a one-time pairing token with device metadata.
Scan with the app
Open ForkOff and scan the QR code
The app reads the token and initiates a secure handshake.
E2EE key exchange
Automatic key negotiation
X25519 ECDH generates a shared secret. Ed25519 identity keys are signed and pinned (TOFU).
Encrypted channel established
Devices connected and ready
All future communication is encrypted with XSalsa20-Poly1305. The relay never sees plaintext.
Session Lifecycle
How a session works from start to finish — real-time streaming with full mobile control.
Start a session
Pick a device and directory from the app, or use a quick action from the Project Hub.
CLI hooks into Claude Code
The CLI detects the Claude Code process and attaches PreToolUse/PostToolUse hooks via the hook system.
Real-time streaming
Messages, tool uses, thinking blocks, and token usage are streamed to your phone as they happen.
Take over the session
Explicitly "Take Over" to send messages, approve operations, and control the session from mobile.
Session ends or is released
Hooks are cleaned up, resources released, and the session history is preserved.
Permission & Approval System
Every dangerous operation requires your explicit approval. Safe tools auto-approve based on your configurable rules.
Claude invokes a tool
Claude Code wants to run a Bash command, edit a file, or perform another operation.
PreToolUse hook fires
The CLI's hook script intercepts the call before it executes.
Check permission rules
Rules synced from mobile determine: auto-approve safe tools, escalate dangerous ones.
Prompt sent to mobile
For dangerous tools, the CLI sends an encrypted permission prompt to your phone.
You approve or deny
The PermissionQueue modal shows the tool, command, and context. Approve individually or batch.
Response flows back
Your decision is encrypted and sent back to the CLI. Claude proceeds or stops accordingly.
Data Flow & Encryption
Double encryption protects your data — TLS for transport, plus application-layer E2EE that the relay cannot decrypt.
What's encrypted
- ●Prompts and messages
- ●Source code and diffs
- ●Approval decisions
- ●File paths and directories
- ●Permission rules
- ●Tool arguments and output
What the relay sees
- ●Opaque device UUIDs
- ●Message counters (integers)
- ●Timestamps
- ●Encrypted blobs (ciphertext + nonce)
- ●Socket.io room names
- ●Connection metadata
For a deep dive into the cryptographic primitives and threat model, see the Security page.
Cloud vs Local Mode
Choose how your devices communicate. Both modes use identical end-to-end encryption.
Cloud Mode
Default- ●Relay at api.forkoff.app
- ●Multi-device support
- ●Works from anywhere — home, office, mobile data
- ●E2EE means relay can't read your data
Local Mode
--local- ●CLI becomes a P2P WebSocket server
- ●Zero internet required
- ●Same-network only (LAN / hotspot)
- ●Identical E2EE as cloud mode
Ready to Get Started?
ForkOff is open source. Explore the code, read the security whitepaper, or jump straight into the getting started guide.