forkoff 1.0.18 → 1.1.0

package/LICENSE

@@ -1,12 +1,16 @@
-Copyright (c) 2026 ForkOff. All rights reserved.
+MIT License
 
-This software and associated documentation files (the "Software") are the
-proprietary property of ForkOff. The Software is provided for viewing and
-reference purposes only.
+Copyright (c) 2026 ForkOff
 
-No part of the Software may be copied, modified, merged, published,
-distributed, sublicensed, sold, or otherwise used without the prior written
-permission of ForkOff.
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
 
 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,

package/README.md

@@ -5,37 +5,31 @@
 <h1 align="center">ForkOff CLI</h1>
 
 <p align="center">
-  <strong>Bridge your AI coding tools to your mobile device</strong>
+  <strong>Control your AI coding sessions from your phone</strong>
 </p>
 
-> ## 🚀 **OPEN BETA**
->
-> ForkOff is now in **open beta**! Download the mobile app and get started:
->
-> 📱 **[Join the TestFlight Beta](https://testflight.apple.com/join/dhh5FrN7)**
-
----
+<p align="center">
+  <a href="https://www.npmjs.com/package/forkoff"><img src="https://img.shields.io/npm/v/forkoff.svg" alt="npm version"></a>
+  <a href="https://github.com/Forkoff-app/forkoff-cli/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/forkoff.svg" alt="MIT License"></a>
+  <a href="https://www.npmjs.com/package/forkoff"><img src="https://img.shields.io/npm/dm/forkoff.svg" alt="npm downloads"></a>
+</p>
 
 <p align="center">
-  <a href="https://forkoff.app">Website</a> •
-  <a href="#installation">Installation</a> •
-  <a href="#quick-start">Quick Start</a> •
-  <a href="#commands">Commands</a> •
-  <a href="#programmatic-usage">API</a> •
-  <a href="#configuration">Configuration</a>
+  <a href="https://forkoff.app">Website</a> &bull;
+  <a href="#installation">Installation</a> &bull;
+  <a href="#quick-start">Quick Start</a> &bull;
+  <a href="#commands">Commands</a> &bull;
+  <a href="#programmatic-usage">API</a> &bull;
+  <a href="#security">Security</a>
 </p>
 
 ---
 
-## Overview
+ForkOff CLI connects [Claude Code](https://claude.ai/code) on your laptop to the ForkOff mobile app, giving you real-time monitoring, interactive approvals, and usage analytics from anywhere.
 
-ForkOff CLI connects your development machine to the ForkOff mobile app, enabling you to:
-
-- **Control AI coding sessions** from your phone
-- **Approve code changes** on the go
-- **Send prompts** to Claude, Cursor, and other AI tools
-- **Monitor progress** in real-time
-- **Get notifications** for permission requests
+> **Open Source** &mdash; ForkOff CLI is now MIT licensed. Contributions welcome!
+>
+> **Open Beta** &mdash; [Join the iOS TestFlight](https://testflight.apple.com/join/dhh5FrN7)
 
 ## Installation
 
@@ -45,24 +39,35 @@ npm install -g forkoff
 
 ## Quick Start
 
-### 1. Pair with Mobile App
+### 1. Pair with your phone
 
 ```bash
 forkoff pair
 ```
 
-Scan the QR code with your ForkOff mobile app to link your device.
+Scan the QR code with the ForkOff mobile app to link your device.
 
-### 2. Stay Connected
+### 2. Stay connected
 
 ```bash
 forkoff connect
 ```
 
-Keep this running to receive commands from your mobile app.
+Keep this running to stream sessions to your phone in real-time.
 
 ---
 
+## Features
+
+- **Real-time session monitoring** &mdash; See Claude Code output on your phone as it happens
+- **Interactive approvals** &mdash; Approve or deny tool use (file edits, bash commands) from mobile
+- **Configurable permission rules** &mdash; Auto-approve safe tools, require approval for destructive ones
+- **End-to-end encryption** &mdash; All session data encrypted between CLI and mobile
+- **Usage analytics** &mdash; Track token usage, session counts, and streaks across devices
+- **Multi-device support** &mdash; Connect multiple CLI instances, analytics aggregate automatically
+- **Auto-start** &mdash; Optionally launch on login so your phone is always connected
+- **Direct P2P connection** &mdash; Embedded relay server, no cloud dependency for session data
+
 ## Commands
 
 | Command | Description |
@@ -70,31 +75,18 @@ Keep this running to receive commands from your mobile app.
 | `forkoff pair` | Generate QR code to pair with mobile app |
 | `forkoff connect` | Connect and listen for commands |
 | `forkoff status` | Check connection status |
-| `forkoff disconnect` | Disconnect from server |
+| `forkoff disconnect` | Disconnect and unpair device |
 | `forkoff config` | View/modify configuration |
 | `forkoff startup` | Manage automatic startup on login |
-| `forkoff startup --enable` | Enable automatic startup |
-| `forkoff startup --disable` | Disable automatic startup |
-| `forkoff startup --status` | Show startup registration status |
-| `forkoff help` | Show available commands and usage |
+| `forkoff tools` | Detect AI coding tools on your machine |
+| `forkoff logs` | List debug log files for troubleshooting |
 
-### Configuration Options
+### Configuration
 
 ```bash
-# Show current configuration
-forkoff config --show
-
-# Set custom API URL
-forkoff config --api https://your-server.com/api
-
-# Set custom WebSocket URL
-forkoff config --ws wss://your-server.com
-
-# Set device name
-forkoff config --name "My MacBook Pro"
-
-# Reset all configuration
-forkoff config --reset
+forkoff config --show            # Show current config
+forkoff config --name "My MBP"   # Set device name
+forkoff config --reset           # Reset to defaults
 ```
 
 ### Global Options
@@ -102,93 +94,66 @@ forkoff config --reset
 | Option | Description |
 |--------|-------------|
 | `-q, --quiet` | Suppress all output (for background operation) |
-
-### Background Operation
-
-Run ForkOff silently in the background with no console output:
-
-```bash
-forkoff connect --quiet
-```
-
-This is used by the automatic startup feature and is useful for running ForkOff as a background service.
+| `--debug` | Enable debug logging to file (`~/.forkoff-cli/logs/`) |
 
 ### Automatic Startup
 
-ForkOff automatically starts on login so your device stays connected without manual intervention. Startup is **enabled by default** — when you run `forkoff pair` or `forkoff connect`, it registers itself to launch `forkoff connect --quiet` on login.
+Startup is enabled by default &mdash; `forkoff pair` and `forkoff connect` register the CLI to launch on login.
 
-- **Windows**: Adds a `ForkOffCLI` entry to the `HKCU\...\Run` registry key (no admin required)
-- **macOS**: Installs a launchd agent (`~/Library/LaunchAgents/app.forkoff.cli.plist`) with the explicit node binary path for nvm/fnm compatibility
-
-To disable automatic startup:
+- **Windows**: Registry key (`HKCU\...\Run`)
+- **macOS**: launchd agent (`~/Library/LaunchAgents/app.forkoff.cli.plist`)
 
 ```bash
-forkoff startup --disable
+forkoff startup --disable   # Disable auto-start
+forkoff startup --enable    # Re-enable
+forkoff startup --status    # Check registration
 ```
 
-Once disabled, `pair` and `connect` will not re-register startup. To re-enable:
+---
+
+## Security
 
-```bash
-forkoff startup --enable
-```
+ForkOff uses end-to-end encryption (X25519 ECDH + XSalsa20-Poly1305) so the relay server never sees your code, prompts, or approvals &mdash; 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 |
 
-Running `forkoff disconnect` also removes the startup registration.
+No additional setup required &mdash; E2EE is enabled automatically when you pair. See [SECURITY.md](https://github.com/Forkoff-app/forkoff-cli/blob/main/docs/SECURITY.md) for the full whitepaper.
 
 ---
 
 ## Programmatic Usage
 
-Integrate ForkOff into your AI coding tools:
+Integrate ForkOff into your own AI coding tools:
 
 ```typescript
 import { createIntegration } from 'forkoff';
 
 const forkoff = createIntegration();
-
-// Connect to ForkOff server
 await forkoff.connect();
 
-// Handle incoming messages from mobile app
-forkoff.onMessageReceived((sessionId, content, requestedBy) => {
-  console.log(`Message from ${requestedBy}: ${content}`);
-
-  // Send a response
-  forkoff.sendMessage(sessionId, 'Processing your request...');
-});
-
-// Stream responses in real-time
-const stream = forkoff.startStreaming(sessionId);
-stream.write('Here is ');
-stream.write('a streaming ');
-stream.write('response.');
-stream.end();
-
 // Request approval for code changes
 const approval = await forkoff.requestApproval(
-  sessionId,
-  messageId,
-  'CODE_CHANGE',
-  'Add authentication middleware',
+  sessionId, messageId, 'CODE_CHANGE',
+  'Add auth middleware',
   { filePath: 'src/middleware/auth.ts', diff: '...' }
 );
 
-if (approval.status === 'approved') {
-  // Apply the changes
-}
-
-// Send terminal output
-forkoff.sendTerminalOutput(sessionId, '> npm install\n Done', 'stdout');
-forkoff.sendTerminalExit(sessionId, 0);
-
-// Update device status
-forkoff.setStatus('busy');
+// Stream terminal output
+forkoff.sendTerminalOutput(sessionId, '> npm install\nDone', 'stdout');
 ```
 
 ---
 
-## Configuration
-
-Configuration files are stored at:
+## Configuration Files
 
 | Platform | Location |
 |----------|----------|
@@ -196,26 +161,22 @@ Configuration files are stored at:
 | **macOS** | `~/Library/Preferences/forkoff-cli/config.json` |
 | **Linux** | `~/.config/forkoff-cli/config.json` |
 
----
-
-## Security
-
-Your data stays yours. All communication between the ForkOff CLI and your mobile device is protected with **end-to-end encryption (E2EE)**:
-
-- Messages, code, and commands are encrypted on-device before leaving your machine
-- The ForkOff server never sees your plaintext data — it only relays encrypted payloads
-- Each device pair establishes a unique encrypted channel using ephemeral key exchange
-- Session keys are derived per-connection, so even if one session is compromised, others remain secure
+## Development
 
-No additional setup required — E2EE is enabled automatically when you pair your device.
+```bash
+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
+- [ForkOff mobile app](https://testflight.apple.com/join/dhh5FrN7) (iOS)
 
----
+## License
 
-<p align="center">
-  Made with ❤️ by the ForkOff team
-</p>
+[MIT](LICENSE)

package/dist/cloud-client.d.ts

@@ -0,0 +1,30 @@
+import { EventEmitter } from 'events';
+export interface CloudRelayOptions {
+    url: string;
+    deviceId: string;
+    deviceName: string;
+    relayToken?: string | null;
+}
+export declare class CloudRelayClient extends EventEmitter {
+    private socket;
+    private url;
+    private deviceId;
+    private deviceName;
+    private relayToken;
+    /** The pairing code the CLI generated — sent to relay for registration */
+    private currentPairingCode;
+    constructor(options: CloudRelayOptions);
+    /** Set the pairing code — will be registered with the relay on connect */
+    setPairingCode(code: string): void;
+    /** Connect to the cloud relay as a CLI client */
+    start(): Promise<void>;
+    /** Emit an event to the mobile client via the relay */
+    emitToMobile(event: string, data: any): void;
+    /** Check if mobile is connected (based on relay notifications) */
+    hasMobileConnection(): boolean;
+    /** Get the connected mobile device ID (set after pairing or mobile_connected) */
+    getMobileDeviceId(): string | null;
+    /** Graceful shutdown */
+    stop(): Promise<void>;
+}
+//# sourceMappingURL=cloud-client.d.ts.map

package/dist/cloud-client.js

@@ -0,0 +1,165 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CloudRelayClient = void 0;
+/**
+ * Cloud relay client — CLI connects as a Socket.io CLIENT to the relay server
+ * (e.g., wss://api.forkoff.app). The relay routes events to/from the paired mobile.
+ * Same interface as EmbeddedRelayServer so WebSocketClient can use either.
+ */
+const socket_io_client_1 = require("socket.io-client");
+const events_1 = require("events");
+const config_1 = require("./config");
+/** Events the cloud relay forwards from mobile → CLI (same set as EmbeddedRelayServer) */
+const MOBILE_EVENTS = [
+    'terminal_command', 'terminal_create', 'user_message',
+    'claude_start_session', 'claude_resume_session', 'claude_sessions_request',
+    'directory_list', 'read_file', 'transcript_fetch', 'transcript_subscribe',
+    'transcript_unsubscribe', 'approval_response', 'claude_approval_response',
+    'permission_response', 'permission_rules_sync', 'claude_abort', 'tab_complete',
+    'subscribe_device', 'unsubscribe_device',
+    'sdk_session_history', 'usage_stats_request', 'session_settings_update',
+    'transcript_subscribe_sdk',
+    // E2EE key exchange and encrypted messages from mobile
+    'encrypted_key_exchange_init', 'encrypted_key_exchange_ack', 'encrypted_message',
+];
+class CloudRelayClient extends events_1.EventEmitter {
+    constructor(options) {
+        super();
+        this.socket = null;
+        /** The pairing code the CLI generated — sent to relay for registration */
+        this.currentPairingCode = null;
+        this.url = options.url;
+        this.deviceId = options.deviceId;
+        this.deviceName = options.deviceName;
+        this.relayToken = options.relayToken ?? null;
+    }
+    /** Set the pairing code — will be registered with the relay on connect */
+    setPairingCode(code) {
+        this.currentPairingCode = code;
+        // If already connected, register immediately
+        if (this.socket?.connected) {
+            this.socket.emit('register_pairing_code', {
+                code,
+                deviceId: this.deviceId,
+                deviceName: this.deviceName,
+                platform: process.platform,
+            });
+        }
+    }
+    /** Connect to the cloud relay as a CLI client */
+    start() {
+        return new Promise((resolve, reject) => {
+            this.socket = (0, socket_io_client_1.io)(this.url, {
+                auth: {
+                    clientType: 'cli',
+                    deviceId: this.deviceId,
+                    deviceName: this.deviceName,
+                    platform: process.platform,
+                    hostname: require('os').hostname(),
+                    relayToken: this.relayToken,
+                    userId: config_1.config.userId,
+                },
+                transports: ['websocket'],
+                reconnection: true,
+                reconnectionAttempts: Infinity,
+                reconnectionDelay: 1000,
+                reconnectionDelayMax: 15000,
+                timeout: 10000,
+            });
+            let resolved = false;
+            this.socket.on('connect', () => {
+                console.log(`[CloudRelay] Connected to ${this.url}`);
+                // Register pairing code if we have one
+                if (this.currentPairingCode) {
+                    this.socket.emit('register_pairing_code', {
+                        code: this.currentPairingCode,
+                        deviceId: this.deviceId,
+                        deviceName: this.deviceName,
+                        platform: process.platform,
+                    });
+                }
+                if (!resolved) {
+                    resolved = true;
+                    resolve();
+                }
+            });
+            this.socket.on('connect_error', (err) => {
+                console.error(`[CloudRelay] Connection error: ${err.message}`);
+                if (!resolved) {
+                    resolved = true;
+                    reject(new Error(`Failed to connect to cloud relay at ${this.url}: ${err.message}`));
+                }
+            });
+            this.socket.on('disconnect', (reason) => {
+                console.log(`[CloudRelay] Disconnected: ${reason}`);
+            });
+            // Handle cloud pairing flow: relay sends pair_device when mobile enters our code
+            this.socket.on('pair_device', (data) => {
+                console.log(`[CloudRelay] Pairing request received from mobile`);
+                // Emit internally so WebSocketClient can handle it
+                this.emit('pair_device', { mobileDeviceId: data.mobileDeviceId });
+                // Send ack back through relay — relay will forward to mobile with mobileRelayToken
+                this.socket.emit('pair_device_ack', {
+                    deviceId: this.deviceId,
+                    deviceName: this.deviceName,
+                    platform: process.platform,
+                    mobileDeviceId: data.mobileDeviceId,
+                    pairId: data.pairId,
+                    cliRelayToken: data.cliRelayToken,
+                });
+                // Store relay credentials locally
+                if (data.cliRelayToken) {
+                    config_1.config.relayToken = data.cliRelayToken;
+                    this.relayToken = data.cliRelayToken;
+                }
+                if (data.pairId) {
+                    config_1.config.pairId = data.pairId;
+                }
+            });
+            // Handle mobile connected notification from relay
+            this.socket.on('mobile_connected', (data) => {
+                console.log(`[CloudRelay] Mobile connected: ${data.deviceId || 'unknown'}`);
+                this.emit('mobile_connected', { deviceId: data.deviceId || data.mobileDeviceId });
+            });
+            // Handle mobile disconnected notification from relay
+            this.socket.on('mobile_disconnected', (data) => {
+                console.log(`[CloudRelay] Mobile disconnected`);
+                this.emit('mobile_disconnected', { deviceId: data.deviceId, reason: data.reason || 'disconnected' });
+            });
+            // Forward all mobile events → internal EventEmitter (same as EmbeddedRelayServer)
+            for (const event of MOBILE_EVENTS) {
+                this.socket.on(event, (data) => {
+                    this.emit(event, data);
+                });
+            }
+        });
+    }
+    /** Emit an event to the mobile client via the relay */
+    emitToMobile(event, data) {
+        if (this.socket?.connected) {
+            // Relay will route this to the paired mobile client
+            this.socket.emit(event, data);
+        }
+    }
+    /** Check if mobile is connected (based on relay notifications) */
+    hasMobileConnection() {
+        return this.socket?.connected ?? false;
+    }
+    /** Get the connected mobile device ID (set after pairing or mobile_connected) */
+    getMobileDeviceId() {
+        // The relay manages this — we don't track directly in cloud mode
+        return null;
+    }
+    /** Graceful shutdown */
+    stop() {
+        return new Promise((resolve) => {
+            if (this.socket) {
+                this.socket.disconnect();
+                this.socket = null;
+            }
+            resolve();
+        });
+    }
+}
+exports.CloudRelayClient = CloudRelayClient;
+//# sourceMappingURL=cloud-client.js.map

package/dist/config.d.ts

@@ -25,6 +25,12 @@ declare class Config {
     set startupBinaryPath(value: string | null);
     get relayPort(): number;
     set relayPort(value: number);
+    get relayMode(): 'cloud' | 'local';
+    set relayMode(value: 'cloud' | 'local');
+    get relayToken(): string | null;
+    set relayToken(value: string | null);
+    get pairId(): string | null;
+    set pairId(value: string | null);
     get isPaired(): boolean;
     ensureDeviceId(): string;
     getMachineId(): string;

package/dist/config.js

@@ -87,6 +87,9 @@ const defaultConfig = {
     userId: null,
     startupEnabled: true,
     startupBinaryPath: null,
+    relayMode: 'cloud',
+    relayToken: null,
+    pairId: null,
 };
 class Config {
     constructor() {
@@ -221,6 +224,27 @@ class Config {
         this.data.relayPort = value;
         this.save();
     }
+    get relayMode() {
+        return this.data.relayMode;
+    }
+    set relayMode(value) {
+        this.data.relayMode = value;
+        this.save();
+    }
+    get relayToken() {
+        return this.data.relayToken;
+    }
+    set relayToken(value) {
+        this.data.relayToken = value;
+        this.save();
+    }
+    get pairId() {
+        return this.data.pairId;
+    }
+    set pairId(value) {
+        this.data.pairId = value;
+        this.save();
+    }
     get isPaired() {
         return !!this.deviceId && !!this.pairedAt;
     }

package/dist/crypto/e2eeManager.d.ts

@@ -5,6 +5,8 @@ export declare class E2EEManager {
     private signingKeyPair;
     private initialized;
     private sessions;
+    private static readonly SESSION_MAX_AGE_MS;
+    private static readonly SESSION_MAX_MESSAGES;
     private static readonly MAX_PENDING_EXCHANGES;
     private static readonly PENDING_EXCHANGE_TTL_MS;
     private pendingExchanges;
@@ -19,6 +21,11 @@ export declare class E2EEManager {
     getSigningPublicKey(): string | null;
     /** Check if manager is initialized */
     isInitialized(): boolean;
+    /**
+     * Check if a session has expired (age or message count).
+     * Returns true if the session should be torn down and re-keyed.
+     */
+    isSessionExpired(deviceId: string): boolean;
     /**
      * Sign a key exchange payload with our Ed25519 identity key.
      * The signed message is: "prefix:senderDeviceId:ephemeralPublicKey[:recipientDeviceId]"
@@ -52,6 +59,7 @@ export declare class E2EEManager {
     handleKeyExchangeAck(ack: KeyExchangeAck): void;
     /**
      * Attempts to restore a persisted session after reconnection.
+     * If the session has expired, it is deleted from persistence and not restored.
      */
     restorePersistedSession(targetDeviceId: string): Promise<boolean>;
     /** Lists all devices with persisted sessions */