@willjackson/claude-code-bridge 0.5.1 → 0.6.1

package/README.md

@@ -1,6 +1,6 @@
 # Claude Code Bridge
 
-A bidirectional communication system that enables two separate Claude Code instances to collaborate across different environments.
+Control and interact with remote environments from your local Claude Code instance via WebSocket.
 
 ## Table of Contents
 
@@ -17,40 +17,49 @@ A bidirectional communication system that enables two separate Claude Code insta
 
 ## Overview
 
-Claude Code Bridge connects two Claude Code instances running on different machines, containers, or networks via WebSocket.
+Claude Code Bridge enables your local Claude Code instance to read, write, and manage files on remote machines, containers, or servers. The **host** runs on your local machine with Claude Code, while the **client** runs on the remote machine and executes commands.
 
 ### Architecture
 
 ```
-┌─────────────────────────┐                    ┌─────────────────────────┐
-│      Local Mac          │                    │   Container (CLI/Web)   │
-│  ┌───────────────────┐  │                    │  ┌───────────────────┐  │
-│  │   Claude Code     │  │                    │  │   Claude Code     │  │
-│  │   (Desktop App)   │  │                    │  │   (Server App)    │  │
-│  └─────────┬─────────┘  │                    │  └─────────┬─────────┘  │
-│            │            │                    │            │            │
-│  ┌─────────┴─────────┐  │    WebSocket       │  ┌─────────┴─────────┐  │
-│  │   Bridge Plugin   │◄─┼────────────────────┼─►│   Bridge Plugin   │  │
-│  │   (port 8766)     │  │                    │  │   (port 8765)     │  │
-│  └───────────────────┘  │                    │  └───────────────────┘  │
-└─────────────────────────┘                    └─────────────────────────┘
+┌─────────────────────────────────────────┐
+│            HOST (Local Machine)          │
+│  ┌─────────────────────────────────┐    │
+│  │         Claude Code             │    │
+│  │    (with MCP tools enabled)     │    │
+│  └──────────────┬──────────────────┘    │
+│                 │ MCP                    │
+│  ┌──────────────┴──────────────────┐    │
+│  │      Bridge (host mode)         │    │
+│  │        port 8766                │    │
+│  └──────────────┬──────────────────┘    │
+└─────────────────┼───────────────────────┘
+                  │ WebSocket
+┌─────────────────┼───────────────────────┐
+│            CLIENT (Remote Machine)       │
+│  ┌──────────────┴──────────────────┐    │
+│  │    Bridge (client mode)         │    │
+│  │      --with-handlers            │    │
+│  │   Executes: read/write/delete   │    │
+│  └─────────────────────────────────┘    │
+└─────────────────────────────────────────┘
 ```
 
 ### Use Cases
 
-- **Cross-environment refactoring**: Coordinate changes between API client (desktop) and API server (container)
-- **Context sharing**: Share code snippets, project structure, and summaries between instances
-- **Task delegation**: Delegate tasks from one Claude Code instance to another
-- **Multi-project coordination**: Work on related projects in different environments simultaneously
+- **Remote file editing**: Read, write, and delete files on remote servers from your local Claude Code
+- **Cross-environment development**: Work on a Docker container or VM from your local machine
+- **Server management**: Manage configuration files on remote servers
+- **Multi-machine workflows**: Control multiple remote environments from one Claude Code instance
 
 ## Features
 
-- **WebSocket-based communication** with automatic reconnection
-- **Context synchronization** with configurable file patterns
-- **Task delegation** with timeout handling
-- **Remote file operations** - read, write, and delete files on connected peers
-- **Peer-to-peer mode** allowing bidirectional communication
-- **CLI and programmatic API** for flexible integration
+- **Host-Client architecture** - Control remote environments from your local machine
+- **Remote file operations** - read, write, delete, and list files on connected clients
+- **Real-time command logging** - See incoming commands on the client console
+- **WebSocket communication** with automatic reconnection
+- **MCP integration** - Use remote bridge tools directly in Claude Code
+- **Daemon mode** - Run the host bridge in the background
 
 ## Installation
 
@@ -85,72 +94,72 @@ npm link  # Makes 'claude-bridge' available globally
 
 ## Quick Start
 
-### Scenario 1: Start Bridge and Launch Claude Code
-
-The easiest way to get started - start the bridge and launch Claude Code in one command:
-
-**Step 1: Configure the MCP server (one-time setup)**
+### Step 1: Install
 
 ```bash
-claude mcp add remote-bridge -- npx @willjackson/claude-code-bridge mcp-server --connect ws://localhost:8766
+npm install -g @willjackson/claude-code-bridge
 ```
 
-**Step 2: Start bridge and launch Claude Code**
+### Step 2: Configure MCP (one-time setup on host)
 
 ```bash
-claude-bridge start --port 8766 --launch-claude
+claude mcp add remote-bridge -- npx @willjackson/claude-code-bridge mcp-server --connect ws://localhost:8766
 ```
 
-This starts the bridge daemon in the background and launches Claude Code with access to the remote bridge tools.
-
-### Scenario 2: Mac to Remote Server
+### Step 3: Start the Host and Launch Claude Code
 
-**Step 1: Start the bridge on your Mac**
+On your **local machine** (the host):
 
 ```bash
 claude-bridge start --port 8766 --launch-claude
 ```
 
-**Step 2: Start the bridge on the remote machine and connect**
+This starts the bridge daemon and launches Claude Code with access to the remote bridge MCP tools.
+
+**With Claude flags** (e.g., skip permissions):
 
 ```bash
-# On remote machine (replace YOUR_MAC_IP with actual IP)
-claude-bridge start --with-handlers --connect ws://YOUR_MAC_IP:8766
+claude-bridge start --port 8766 --launch-claude -- --dangerously-skip-permissions
 ```
 
-Now Claude Code on your Mac can read/write files on the remote machine.
+Any arguments after `--` are passed directly to the `claude` command.
 
-### Scenario 3: Peer-to-Peer Mode
+### Step 4: Start the Client on Remote Machine
 
-Both instances can initiate communication:
-
-**Machine A:**
-```bash
-claude-bridge start --port 8766
-```
+On the **remote machine** (server, container, VM):
 
-**Machine B:**
 ```bash
-claude-bridge start --port 8765 --connect ws://MACHINE_A_IP:8766
+# Replace HOST_IP with your local machine's IP address
+claude-bridge start --with-handlers --connect ws://HOST_IP:8766
 ```
 
-Once connected, either side can send context or delegate tasks to the other.
-
-### Scenario 3: Remote File Operations
-
-Enable file operations on the remote to allow reading, writing, and deleting files:
+The client will show incoming commands in the console:
 
-**Machine A (relay mode, no handlers):**
-```bash
-claude-bridge start --port 8766
 ```
+┌─────────────────────────────────────────────────────────────
+│ 📥 INCOMING TASK: Read config file
+│ ID: task-123
+│ Scope: execute
+│ Action: read_file
+│ Path: config/settings.json
+└─────────────────────────────────────────────────────────────
 
-**Machine B (with file handlers):**
-```bash
-claude-bridge start --with-handlers --connect ws://MACHINE_A_IP:8766
+  ✅ RESULT: Read 1234 chars from config/settings.json
 ```
 
-Now you can read, write, and edit files on Machine B from Machine A.
+### Available MCP Tools
+
+Once connected, Claude Code on your host has access to these tools:
+
+| Tool | Description |
+|------|-------------|
+| `bridge_read_file` | Read a file from the remote client |
+| `bridge_write_file` | Write/create a file on the remote client |
+| `bridge_delete_file` | Delete a file on the remote client |
+| `bridge_list_directory` | List directory contents on the remote client |
+| `bridge_delegate_task` | Delegate a custom task to the client |
+| `bridge_request_context` | Request files matching a query |
+| `bridge_status` | Check connection status |
 
 ## CLI Reference
 
@@ -171,7 +180,7 @@ Options:
 #### `start` - Start the Bridge Server
 
 ```bash
-claude-bridge start [options]
+claude-bridge start [options] [-- claude-args...]
 
 Options:
   -p, --port <port>    Port to listen on (default: 8765)
@@ -180,6 +189,8 @@ Options:
   -d, --daemon         Run in background
   --with-handlers      Enable file operations and task handling (read/write/delete files)
   --launch-claude      Start bridge daemon and launch Claude Code
+
+Arguments after -- are passed to the claude command when using --launch-claude.
 ```
 
 **Examples:**
@@ -188,19 +199,22 @@ Options:
 # Start bridge and launch Claude Code (recommended for local use)
 claude-bridge start --port 8766 --launch-claude
 
+# Start bridge and launch Claude with --dangerously-skip-permissions
+claude-bridge start --port 8766 --launch-claude -- --dangerously-skip-permissions
+
 # Start with default settings
 claude-bridge start
 
 # Start on specific port
 claude-bridge start --port 9000
 
-# Start and connect to remote bridge
-claude-bridge start --connect ws://192.168.1.100:8765
+# Start and connect to host (client mode)
+claude-bridge start --connect ws://192.168.1.100:8766
 
 # Start in daemon mode
 claude-bridge start --daemon
 
-# Start with file operation handlers enabled (for remote machines)
+# Start with file operation handlers enabled (for remote/client machines)
 claude-bridge start --with-handlers --connect ws://192.168.1.100:8766
 ```
 
@@ -323,16 +337,16 @@ Create a configuration file at one of these locations:
 ```yaml
 # Instance identification
 instanceName: my-mac-desktop
-mode: peer  # host, client, or peer
+mode: host  # 'host' for local machine, 'client' for remote
 
-# Server settings
+# Server settings (host mode)
 listen:
   port: 8766
   host: 0.0.0.0
 
-# Connection to remote bridge
+# Connection to host (client mode)
 connect:
-  url: ws://localhost:8765
+  url: ws://192.168.1.100:8766
 
 # Context sharing settings
 contextSharing:
@@ -360,10 +374,10 @@ interaction:
 | Setting | Type | Default | Description |
 |---------|------|---------|-------------|
 | `instanceName` | string | - | Unique name for this bridge instance |
-| `mode` | string | - | Operation mode: `host`, `client`, or `peer` |
-| `listen.port` | number | 8765 | Port to listen on |
-| `listen.host` | string | 0.0.0.0 | Host to bind to |
-| `connect.url` | string | - | WebSocket URL of remote bridge |
+| `mode` | string | - | Operation mode: `host` or `client` |
+| `listen.port` | number | 8765 | Port to listen on (host mode) |
+| `listen.host` | string | 0.0.0.0 | Host to bind to (host mode) |
+| `connect.url` | string | - | WebSocket URL of host (client mode) |
 | `contextSharing.autoSync` | boolean | true | Automatically sync context |
 | `contextSharing.syncInterval` | number | 5000 | Sync interval in ms |
 | `contextSharing.maxChunkTokens` | number | 4000 | Max tokens per context chunk |
@@ -375,38 +389,50 @@ interaction:
 
 ## Programmatic Usage
 
-### Basic Usage
+### Basic Usage (Host)
 
 ```typescript
 import { Bridge, BridgeConfig } from 'claude-code-bridge';
 
-// Create bridge configuration
+// Create host bridge configuration
 const config: BridgeConfig = {
-  mode: 'peer',
-  instanceName: 'my-bridge',
-  listen: { port: 8765, host: '0.0.0.0' },
-  connect: { url: 'ws://localhost:8766' },
-  contextSharing: {
-    autoSync: true,
-    syncInterval: 5000,
-    maxChunkTokens: 4000,
-    includePatterns: ['src/**/*.ts'],
-    excludePatterns: ['node_modules/**'],
-  },
-  interaction: {
-    requireConfirmation: false,
-    notifyOnActivity: true,
-    taskTimeout: 300000,
-  },
+  mode: 'host',
+  instanceName: 'my-host',
+  listen: { port: 8766, host: '0.0.0.0' },
+  taskTimeout: 300000,
 };
 
 // Create and start bridge
 const bridge = new Bridge(config);
 await bridge.start();
 
-// Get connected peers
-const peers = bridge.getPeers();
-console.log('Connected peers:', peers);
+// Get connected clients
+const clients = bridge.getPeers();
+console.log('Connected clients:', clients);
+```
+
+### Basic Usage (Client)
+
+```typescript
+import { Bridge, BridgeConfig } from 'claude-code-bridge';
+
+// Create client bridge configuration
+const config: BridgeConfig = {
+  mode: 'client',
+  instanceName: 'my-client',
+  connect: { url: 'ws://192.168.1.100:8766' },
+};
+
+// Create and start bridge
+const bridge = new Bridge(config);
+await bridge.start();
+
+// Register task handler for file operations
+bridge.onTaskReceived(async (task, peerId) => {
+  console.log('Received task:', task.description);
+  // Handle the task...
+  return { success: true, data: { message: 'Done' } };
+});
 ```
 
 ### Context Synchronization
@@ -573,21 +599,28 @@ for (const change of delta.changes) {
 
 ### Connection Issues
 
-**Problem:** Cannot connect to bridge from remote machine
+**Problem:** Client cannot connect to host
 
 **Solutions:**
 1. Ensure the host bridge is running: `claude-bridge status`
-2. Check firewall settings allow the port
-3. Verify the IP address is correct and reachable: `ping MACHINE_IP`
-4. Try using the full URL: `claude-bridge connect ws://192.168.1.100:8766`
+2. Check firewall settings allow the port (default: 8766)
+3. Verify the IP address is correct and reachable: `ping HOST_IP`
+4. Ensure you're using the correct WebSocket URL format: `ws://HOST_IP:8766`
 
 **Problem:** Connection keeps dropping
 
 **Solutions:**
-1. Check network stability
+1. Check network stability between host and client
 2. Increase timeout settings in config
 3. Enable verbose logging: `claude-bridge start -v`
 
+**Problem:** Commands not showing on client
+
+**Solutions:**
+1. Ensure client is started with `--with-handlers` flag
+2. Check the client console for connection status
+3. Verify the host shows the client as connected: `claude-bridge status`
+
 ### Port Conflicts
 
 **Problem:** Port already in use

package/dist/{chunk-MHUQYPTB.js → chunk-XOAR3DQB.js}

@@ -688,15 +688,11 @@ var Bridge = class {
     if (mode === "client" && !connect) {
       throw new Error("'client' mode requires 'connect' configuration");
     }
-    if (mode === "peer" && !listen && !connect) {
-      throw new Error("'peer' mode requires either 'listen' or 'connect' configuration (or both)");
-    }
   }
   /**
    * Start the bridge based on configured mode
-   * - 'host': Starts WebSocket server
-   * - 'client': Connects to remote bridge
-   * - 'peer': Both starts server and connects to remote
+   * - 'host': Starts WebSocket server, sends commands via MCP
+   * - 'client': Connects to host, receives and executes commands
    */
   async start() {
     if (this.started) {
@@ -705,10 +701,10 @@ var Bridge = class {
     const { mode } = this.config;
     logger2.info({ mode }, "Starting bridge");
     try {
-      if ((mode === "host" || mode === "peer") && this.config.listen) {
+      if (mode === "host" && this.config.listen) {
         await this.startServer();
       }
-      if ((mode === "client" || mode === "peer") && this.config.connect) {
+      if (mode === "client" && this.config.connect) {
         await this.connectToRemote();
       }
       this.started = true;
@@ -2151,4 +2147,4 @@ export {
   BridgeMcpServer,
   startMcpServer
 };
-//# sourceMappingURL=chunk-MHUQYPTB.js.map
+//# sourceMappingURL=chunk-XOAR3DQB.js.map