@willjackson/claude-code-bridge 0.2.4 → 0.4.1

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,7 +46,6 @@ 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
@@ -64,13 +62,15 @@ Claude Code Bridge connects a native macOS/Linux Claude Code instance with a Cla
 ### Global Installation (Recommended)
 
 ```bash
-npm install -g claude-code-bridge
+npm install -g @willjackson/claude-code-bridge
 ```
 
+After installation, the `claude-bridge` command will be available globally.
+
 ### Run Without Installing
 
 ```bash
-npx claude-code-bridge start
+npx @willjackson/claude-code-bridge start
 ```
 
 ### Install from Source
@@ -93,56 +93,44 @@ npm link  # Makes 'claude-bridge' available globally
 claude-bridge start --port 8766
 ```
 
-**Step 2: Start the bridge in your container and connect**
-
-```bash
-# Inside the container (Docksal, DDEV, or Docker)
-claude-bridge start --port 8765 --connect ws://host.docker.internal:8766
-```
-
-### Scenario 2: Auto-Detection Mode
-
-Let the bridge automatically detect your environment and configure itself:
+**Step 2: Start the bridge on the remote machine and connect**
 
 ```bash
-# On Mac (auto-detects native environment, uses port 8766)
-claude-bridge start --auto
-
-# In container (auto-detects Docker environment, uses port 8765)
-claude-bridge start --auto --connect ws://host.docker.internal:8766
+# On remote machine (replace MACHINE_A_IP with actual IP)
+claude-bridge start --port 8765 --connect ws://MACHINE_A_IP:8766
 ```
 
-### Scenario 3: Peer-to-Peer Mode
+### Scenario 2: Peer-to-Peer Mode
 
 Both instances can initiate communication:
 
-**Terminal 1 (Mac):**
+**Machine A:**
 ```bash
 claude-bridge start --port 8766
 ```
 
-**Terminal 2 (Container):**
+**Machine B:**
 ```bash
-claude-bridge start --port 8765 --connect ws://host.docker.internal:8766
+claude-bridge start --port 8765 --connect ws://MACHINE_A_IP:8766
 ```
 
 Once connected, either side can send context or delegate tasks to the other.
 
-### Scenario 4: Remote File Operations
+### Scenario 3: Remote File Operations
 
 Enable file operations on the remote to allow reading, writing, and deleting files:
 
-**Terminal 1 (Mac - relay mode, no handlers):**
+**Machine A (relay mode, no handlers):**
 ```bash
 claude-bridge start --port 8766
 ```
 
-**Terminal 2 (Container - with file handlers):**
+**Machine B (with file handlers):**
 ```bash
-claude-bridge start --with-handlers --connect ws://host.docker.internal:8766
+claude-bridge start --with-handlers --connect ws://MACHINE_A_IP:8766
 ```
 
-Now you can read, write, and edit files on the remote container from your Mac.
+Now you can read, write, and edit files on Machine B from Machine A.
 
 ## CLI Reference
 
@@ -166,10 +154,9 @@ 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)
 ```
@@ -190,9 +177,65 @@ claude-bridge start --connect ws://192.168.1.100:8765
 claude-bridge start --daemon
 
 # Start with file operation handlers enabled
-claude-bridge start --with-handlers --connect ws://host.docker.internal:8766
+claude-bridge start --with-handlers --connect ws://192.168.1.100:8766
+```
+
+### Daemon Mode
+
+Daemon mode runs the bridge as a background process, allowing you to close your terminal while the bridge continues running.
+
+#### Starting in Daemon Mode
+
+```bash
+# Start bridge in background
+claude-bridge start --daemon
+
+# Start with additional options
+claude-bridge start --daemon --port 8766 --with-handlers
+
+# Start daemon and connect to remote
+claude-bridge start --daemon --connect ws://192.168.1.100:8765
+```
+
+When started in daemon mode, the bridge:
+- Detaches from the terminal and runs in the background
+- Writes its PID and status to `~/.claude-bridge/status.json`
+- Continues running until explicitly stopped
+
+#### Checking Daemon Status
+
+```bash
+claude-bridge status
 ```
 
+This shows whether a daemon is running, its PID, listening port, and connected peers.
+
+#### Stopping the Daemon
+
+```bash
+claude-bridge stop
+```
+
+This reads the PID from the status file and gracefully shuts down the background process.
+
+#### Status File
+
+The daemon writes its status to `~/.claude-bridge/status.json`:
+
+```json
+{
+  "running": true,
+  "pid": 12345,
+  "port": 8766,
+  "host": "0.0.0.0",
+  "instanceName": "bridge-12345",
+  "startedAt": "2024-01-15T10:30:00.000Z",
+  "peers": []
+}
+```
+
+This file is automatically removed when the daemon stops cleanly.
+
 #### `stop` - Stop the Running Bridge
 
 ```bash
@@ -228,30 +271,18 @@ Arguments:
 
 ```bash
 claude-bridge connect ws://localhost:8765
-claude-bridge connect ws://host.docker.internal:8766
+claude-bridge connect ws://192.168.1.100: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
@@ -278,7 +309,6 @@ listen:
 # Connection to remote bridge
 connect:
   url: ws://localhost:8765
-  hostGateway: true  # Use host.docker.internal
 
 # Context sharing settings
 contextSharing:
@@ -310,7 +340,6 @@ interaction:
 | `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 |
-| `connect.hostGateway` | boolean | false | Use `host.docker.internal` |
 | `contextSharing.autoSync` | boolean | true | Automatically sync context |
 | `contextSharing.syncInterval` | number | 5000 | Sync interval in ms |
 | `contextSharing.maxChunkTokens` | number | 4000 | Max tokens per context chunk |
@@ -320,95 +349,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
@@ -577,20 +517,6 @@ await bridge.delegateTask({
 
 > **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
-import { detectEnvironment, getHostGateway } from 'claude-code-bridge';
-
-const env = detectEnvironment();
-console.log('Environment:', env.type);  // 'native', 'docksal', 'ddev', 'lando', 'docker'
-console.log('Is Container:', env.isContainer);
-console.log('Project Name:', env.projectName);
-
-const gateway = getHostGateway();
-console.log('Host Gateway:', gateway);  // 'host.docker.internal' or IP address
-```
-
 ### Context Manager
 
 ```typescript
@@ -623,13 +549,13 @@ for (const change of delta.changes) {
 
 ### Connection Issues
 
-**Problem:** Cannot connect to bridge from container
+**Problem:** Cannot connect to bridge from remote machine
 
 **Solutions:**
 1. Ensure the host bridge is running: `claude-bridge status`
 2. Check firewall settings allow the port
-3. Verify `host.docker.internal` resolves: `ping host.docker.internal`
-4. Try using the host IP directly: `claude-bridge connect ws://192.168.1.100:8766`
+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`
 
 **Problem:** Connection keeps dropping
 
@@ -638,18 +564,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
@@ -719,13 +633,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
@@ -737,10 +645,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
@@ -759,12 +663,6 @@ npm test -- tests/unit/bridge/protocol.test.ts
 npm test -- --grep "WebSocket"
 ```
 
-## Documentation
-
-- [CLAUDE.md](./CLAUDE.md) - Detailed project specification and architecture
-- [AGENTS.md](./AGENTS.md) - Guidelines for AI agents working on this codebase
-- [instructions.md](./instructions.md) - Development phases and testing strategy
-
 ## License
 
 MIT License - see [LICENSE](./LICENSE) for details.