@willjackson/claude-code-bridge 0.2.3 → 0.2.4

package/README.md

@@ -50,6 +50,7 @@ Claude Code Bridge connects a native macOS/Linux Claude Code instance with a Cla
 - **Environment auto-detection** for Docksal, DDEV, Lando, and Docker
 - **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
 
@@ -127,6 +128,22 @@ claude-bridge start --port 8765 --connect ws://host.docker.internal:8766
 
 Once connected, either side can send context or delegate tasks to the other.
 
+### Scenario 4: Remote File Operations
+
+Enable file operations on the remote to allow reading, writing, and deleting files:
+
+**Terminal 1 (Mac - relay mode, no handlers):**
+```bash
+claude-bridge start --port 8766
+```
+
+**Terminal 2 (Container - with file handlers):**
+```bash
+claude-bridge start --with-handlers --connect ws://host.docker.internal:8766
+```
+
+Now you can read, write, and edit files on the remote container from your Mac.
+
 ## CLI Reference
 
 ### Global Options
@@ -154,6 +171,7 @@ Options:
   -c, --connect <url>  URL to connect to on startup (e.g., ws://localhost:8765)
   -a, --auto           Auto-detect environment and configure
   -d, --daemon         Run in background
+  --with-handlers      Enable file operations and task handling (read/write/delete files)
 ```
 
 **Examples:**
@@ -170,6 +188,9 @@ claude-bridge start --connect ws://192.168.1.100:8765
 
 # Start in daemon mode
 claude-bridge start --daemon
+
+# Start with file operation handlers enabled
+claude-bridge start --with-handlers --connect ws://host.docker.internal:8766
 ```
 
 #### `stop` - Stop the Running Bridge
@@ -483,6 +504,79 @@ bridge.onTaskReceived(async (task) => {
 });
 ```
 
+### Remote File Operations
+
+When connected to a peer running with `--with-handlers`, you can perform file operations:
+
+```typescript
+// Read a file from the remote peer
+const readResult = await bridge.delegateTask({
+  id: 'read-1',
+  description: 'Read config file',
+  scope: 'execute',
+  data: {
+    action: 'read_file',
+    path: 'config/settings.json',
+  },
+});
+
+if (readResult.success) {
+  console.log('File content:', readResult.data.content);
+}
+
+// Write a file to the remote peer
+const writeResult = await bridge.delegateTask({
+  id: 'write-1',
+  description: 'Create new file',
+  scope: 'execute',
+  data: {
+    action: 'write_file',
+    path: 'src/newfile.ts',
+    content: 'export const hello = "world";',
+  },
+});
+
+console.log('Bytes written:', writeResult.data.bytesWritten);
+
+// Delete a file on the remote peer
+const deleteResult = await bridge.delegateTask({
+  id: 'delete-1',
+  description: 'Remove temp file',
+  scope: 'execute',
+  data: {
+    action: 'delete_file',
+    path: 'temp/cache.json',
+  },
+});
+
+// Edit a file (read, modify, write back)
+const file = await bridge.delegateTask({
+  id: 'edit-read',
+  description: 'Read file for editing',
+  scope: 'execute',
+  data: { action: 'read_file', path: 'README.md' },
+});
+
+const newContent = file.data.content.replace('old text', 'new text');
+
+await bridge.delegateTask({
+  id: 'edit-write',
+  description: 'Write edited file',
+  scope: 'execute',
+  data: { action: 'write_file', path: 'README.md', content: newContent },
+});
+```
+
+**Available file operations:**
+
+| Action | Data Fields | Description |
+|--------|-------------|-------------|
+| `read_file` | `path` | Read file content from remote |
+| `write_file` | `path`, `content` | Create or overwrite a file |
+| `delete_file` | `path` | Delete a file |
+
+> **Security Note:** All file operations are restricted to the project directory where the bridge is running. Paths outside the project root are rejected.
+
 ### Environment Detection
 
 ```typescript

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@willjackson/claude-code-bridge",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "description": "Bidirectional communication system for Claude Code instances across environments",
   "type": "module",
   "main": "dist/index.js",