ForkOff CLI

Control your AI coding sessions from your phone

Website • Installation • Quick Start • Commands • API • Security

---

ForkOff CLI connects Claude Code on your laptop to the ForkOff mobile app, giving you real-time monitoring, interactive approvals, and usage analytics from anywhere.

Open Source — MIT licensed. Contributions welcome!

Installation

npm install -g forkoff

Quick Start

1. Pair with your phone

forkoff pair

Scan the QR code with the ForkOff mobile app to link your device.

2. Stay connected

forkoff connect

Keep this running to stream sessions to your phone in real-time.

---

Features

• Real-time session monitoring — See Claude Code output on your phone as it happens
• Interactive approvals — Approve or deny tool use (file edits, bash commands) from mobile
• Configurable permission rules — Auto-approve safe tools, require approval for destructive ones
• End-to-end encryption — All session data encrypted between CLI and mobile
• Usage analytics — Track token usage, session counts, and streaks across devices
• Multi-device support — Connect multiple CLI instances, analytics aggregate automatically
• Auto-start — Optionally launch on login so your phone is always connected
• Local relay option — Run with --local for a direct P2P connection without cloud dependency

Commands

Command	Description
forkoff pair [--local]	Generate QR code to pair with mobile app
forkoff connect [--local]	Reconnect to ForkOff (for previously paired devices)
forkoff status	Check connection status
forkoff disconnect	Disconnect and unpair device
forkoff config	View/modify configuration
forkoff startup	Manage automatic startup on login
forkoff tools	Detect AI tools, install/uninstall hooks
forkoff logs	List, view, or clean debug logs

Configuration

forkoff config --show            # Show current config
forkoff config --name "My MBP"   # Set device name
forkoff config --port 8080       # Set relay server port
forkoff config --reset           # Reset to defaults

Tools

forkoff tools --detect           # Detect installed AI tools
forkoff tools --install-hooks    # Install ForkOff hooks for Claude Code
forkoff tools --uninstall-hooks  # Remove ForkOff hooks
forkoff tools --watch            # Watch tool status changes

Logs

forkoff logs                     # List debug log files
forkoff logs --latest            # Print path to most recent log
forkoff logs --clean             # Delete all log files

Global Options

Option	Description
-q, --quiet	Suppress all output (for background operation)
--debug	Enable debug logging to file (~/.forkoff-cli/logs/)

Automatic Startup

Startup is enabled by default — forkoff pair and forkoff connect register the CLI to launch on login.

• Windows: Registry key (HKCU\...\Run)
• macOS: launchd agent (~/Library/LaunchAgents/app.forkoff.cli.plist)

forkoff startup --disable   # Disable auto-start
forkoff startup --enable    # Re-enable
forkoff startup --status    # Check registration

---

Security

ForkOff uses end-to-end encryption (X25519 ECDH + XSalsa20-Poly1305) so the relay server never sees your code, prompts, or approvals — only opaque encrypted blobs routed between device UUIDs.

Layer	Implementation
Key exchange	X25519 ECDH with HKDF-SHA256 directional key derivation
Authentication	Ed25519 identity signatures on ephemeral keys (MITM protection)
Encryption	XSalsa20-Poly1305 authenticated encryption (NaCl secretbox)
Identity	TOFU (Trust On First Use) with key pinning
Replay protection	Per-peer monotonic message counters
Session expiry	Automatic re-key every 24 hours or 10,000 messages
Key storage	OS keychain (macOS Keychain, Windows Credential Manager, Linux libsecret)
Enforcement	24 sensitive event types encrypted; plaintext fallback only when E2EE unavailable

No additional setup required — E2EE is enabled automatically when you pair.

---

Programmatic Usage

Integrate ForkOff into your own AI coding tools:

import { createIntegration } from 'forkoff';

const forkoff = createIntegration();
await forkoff.connect();

// Request approval for code changes
const approval = await forkoff.requestApproval(
  sessionId, messageId, 'CODE_CHANGE',
  'Add auth middleware',
  { filePath: 'src/middleware/auth.ts', diff: '...' }
);

// Stream terminal output
forkoff.sendTerminalOutput(sessionId, '> npm install\nDone', 'stdout');

---

Configuration Files

Platform	Location
Windows	%APPDATA%\forkoff-cli\config.json
macOS	~/.config/forkoff-cli/config.json
Linux	~/.config/forkoff-cli/config.json

Development

git clone https://github.com/Forkoff-app/forkoff-cli.git
cd forkoff-cli
npm install
npm run dev       # Run with ts-node
npm run build     # Compile TypeScript
npm test          # Run tests

Requirements

• Node.js 18+
• ForkOff mobile app (iOS/Android)

License

MIT