@willjackson/claude-code-bridge 0.2.3 → 0.3.0

package/README.md

@@ -10,7 +10,6 @@ A bidirectional communication system that enables two separate Claude Code insta
 - [Quick Start](#quick-start)
 - [CLI Reference](#cli-reference)
 - [Configuration](#configuration)
-- [Environment Setup](#environment-setup)
 - [Programmatic Usage](#programmatic-usage)
 - [Troubleshooting](#troubleshooting)
 - [Development](#development)
@@ -18,7 +17,7 @@ A bidirectional communication system that enables two separate Claude Code insta
 
 ## Overview
 
-Claude Code Bridge connects a native macOS/Linux Claude Code instance with a Claude Code instance running inside a Docker-based development environment (Docksal, DDEV, Lando, or plain Docker).
+Claude Code Bridge connects two Claude Code instances running on different machines, containers, or networks via WebSocket.
 
 ### Architecture
 
@@ -47,9 +46,9 @@ Claude Code Bridge connects a native macOS/Linux Claude Code instance with a Cla
 ## Features
 
 - **WebSocket-based communication** with automatic reconnection
-- **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
 
@@ -99,33 +98,37 @@ claude-bridge start --port 8766
 claude-bridge start --port 8765 --connect ws://host.docker.internal:8766
 ```
 
-### Scenario 2: Auto-Detection Mode
+### Scenario 2: Peer-to-Peer Mode
 
-Let the bridge automatically detect your environment and configure itself:
+Both instances can initiate communication:
 
+**Terminal 1 (Mac):**
 ```bash
-# On Mac (auto-detects native environment, uses port 8766)
-claude-bridge start --auto
+claude-bridge start --port 8766
+```
 
-# In container (auto-detects Docker environment, uses port 8765)
-claude-bridge start --auto --connect ws://host.docker.internal:8766
+**Terminal 2 (Container):**
+```bash
+claude-bridge start --port 8765 --connect ws://host.docker.internal:8766
 ```
 
-### Scenario 3: Peer-to-Peer Mode
+Once connected, either side can send context or delegate tasks to the other.
 
-Both instances can initiate communication:
+### Scenario 3: Remote File Operations
 
-**Terminal 1 (Mac):**
+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):**
+**Terminal 2 (Container - with file handlers):**
 ```bash
-claude-bridge start --port 8765 --connect ws://host.docker.internal:8766
+claude-bridge start --with-handlers --connect ws://host.docker.internal:8766
 ```
 
-Once connected, either side can send context or delegate tasks to the other.
+Now you can read, write, and edit files on the remote container from your Mac.
 
 ## CLI Reference
 
@@ -149,11 +152,11 @@ Options:
 claude-bridge start [options]
 
 Options:
-  -p, --port <port>    Port to listen on (default: 8765 in container, 8766 native)
+  -p, --port <port>    Port to listen on (default: 8765)
   -h, --host <host>    Host to bind to (default: 0.0.0.0)
   -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 +173,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
@@ -210,27 +216,15 @@ claude-bridge connect ws://localhost:8765
 claude-bridge connect ws://host.docker.internal:8766
 ```
 
-#### `discover` - Discover Local Bridges
-
-```bash
-claude-bridge discover
-```
-
-Searches for:
-- Docker containers with `claude.bridge.enabled=true` label
-- Running Docksal projects
-- Running DDEV projects
-
-#### `info` - Show Environment Information
+#### `info` - Show System Information
 
 ```bash
 claude-bridge info
 ```
 
 Displays:
-- Detected environment (native, Docksal, DDEV, Lando, Docker)
-- Platform information
-- Network configuration
+- System information (Node version, OS, platform)
+- Network interfaces
 - Current configuration settings
 
 ## Configuration
@@ -299,95 +293,6 @@ interaction:
 | `interaction.notifyOnActivity` | boolean | true | Show notifications on activity |
 | `interaction.taskTimeout` | number | 300000 | Task timeout in ms |
 
-## Environment Setup
-
-### DDEV
-
-**Option 1: Using the DDEV Addon**
-
-Copy the addon files to your DDEV project:
-
-```bash
-cp -r addons/ddev/* .ddev/
-ddev restart
-```
-
-Then start the bridge:
-
-```bash
-ddev exec claude-bridge start --connect ws://host.docker.internal:8766
-```
-
-**Option 2: Add to docker-compose**
-
-Create `.ddev/docker-compose.claude-bridge.yaml`:
-
-```yaml
-services:
-  web:
-    labels:
-      - "claude.bridge.enabled=true"
-      - "claude.bridge.port=8765"
-```
-
-### Docksal
-
-**Option 1: Using the Docksal Addon**
-
-```bash
-# Copy addon to Docksal
-cp -r addons/docksal/* ~/.docksal/addons/claude-bridge/
-
-# Install in your project
-fin addon install claude-bridge
-
-# Start the bridge
-fin claude-bridge start
-```
-
-**Option 2: Manual Setup**
-
-Add to your project's `.docksal/docksal.yml`:
-
-```yaml
-services:
-  cli:
-    labels:
-      - "claude.bridge.enabled=true"
-      - "claude.bridge.port=8765"
-```
-
-### Lando
-
-Lando support is coming soon. For now, you can manually install the bridge in your Lando container:
-
-```bash
-lando ssh
-npm install -g claude-code-bridge
-claude-bridge start --connect ws://host.docker.internal:8766
-```
-
-### Plain Docker
-
-Add to your `docker-compose.yml`:
-
-```yaml
-services:
-  app:
-    labels:
-      - "claude.bridge.enabled=true"
-      - "claude.bridge.port=8765"
-    environment:
-      - NODE_ENV=development
-```
-
-Then inside the container:
-
-```bash
-npm install -g claude-code-bridge
-claude-bridge start --auto
-```
-
 ## Programmatic Usage
 
 ### Basic Usage
@@ -483,6 +388,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
@@ -544,18 +522,6 @@ for (const change of delta.changes) {
 2. Increase timeout settings in config
 3. Enable verbose logging: `claude-bridge start -v`
 
-### Environment Detection Issues
-
-**Problem:** Bridge doesn't detect my environment correctly
-
-**Solutions:**
-1. Run `claude-bridge info` to see detected environment
-2. Check environment variables are set correctly:
-   - Docksal: `DOCKSAL_STACK` should be set
-   - DDEV: `IS_DDEV_PROJECT=true` should be set
-   - Lando: `LANDO=ON` should be set
-3. Use explicit configuration instead of auto-detection
-
 ### Port Conflicts
 
 **Problem:** Port already in use
@@ -625,13 +591,7 @@ claude-code-bridge/
 │   │   └── context.ts     # Context manager
 │   ├── transport/
 │   │   ├── interface.ts   # Transport abstraction
-│   │   ├── websocket.ts   # WebSocket implementation
-│   │   └── discovery.ts   # Peer discovery
-│   ├── environment/
-│   │   ├── detect.ts      # Environment detection
-│   │   ├── docksal.ts     # Docksal helpers
-│   │   ├── ddev.ts        # DDEV helpers
-│   │   └── lando.ts       # Lando helpers
+│   │   └── websocket.ts   # WebSocket implementation
 │   ├── cli/
 │   │   ├── index.ts       # CLI entry point
 │   │   └── commands/      # CLI commands
@@ -643,10 +603,6 @@ claude-code-bridge/
 │   ├── unit/              # Unit tests
 │   ├── integration/       # Integration tests
 │   └── e2e/               # End-to-end tests
-└── addons/
-    ├── ddev/              # DDEV addon
-    ├── docksal/           # Docksal addon
-    └── lando/             # Lando plugin
 ```
 
 ### Running Tests