@willjackson/claude-code-bridge 0.6.1 → 0.7.0

package/README.md

@@ -1,739 +1,160 @@
 # Claude Code Bridge
 
-Control and interact with remote environments from your local Claude Code instance via WebSocket.
+**Extend Claude Code's reach to remote machines, containers, and servers.**
 
-## Table of Contents
+Control files and execute tasks on any connected environment—all from your local Claude Code session.
 
-- [Overview](#overview)
-- [Features](#features)
-- [Installation](#installation)
-- [Quick Start](#quick-start)
-- [CLI Reference](#cli-reference)
-- [Configuration](#configuration)
-- [Programmatic Usage](#programmatic-usage)
-- [Troubleshooting](#troubleshooting)
-- [Development](#development)
-- [License](#license)
+## The Problem
 
-## Overview
+You're running Claude Code locally, but your project lives on:
+- A remote development server
+- A Docker container
+- A cloud VM or EC2 instance
+- A different machine on your network
 
-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.
+Without Bridge, you'd need separate Claude Code sessions, copy files back and forth, or SSH in manually.
 
-### Architecture
+## The Solution
 
-```
-┌─────────────────────────────────────────┐
-│            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
-
-- **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
-
-- **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
-
-### Prerequisites
-
-- Node.js 20 or higher
-- npm or pnpm
-
-### Global Installation (Recommended)
+Claude Code Bridge connects your local Claude Code to remote environments via WebSocket. Your local Claude gains the ability to **read, write, list, and delete files** on any connected machine—as if they were local.
 
-```bash
-npm install -g @willjackson/claude-code-bridge
 ```
-
-After installation, the `claude-bridge` command will be available globally.
-
-### Run Without Installing
-
-```bash
-npx @willjackson/claude-code-bridge start
+LOCAL MACHINE                      REMOTE MACHINE
+┌──────────────────────┐           ┌──────────────────────┐
+│                      │           │                      │
+│    Claude Code       │           │    Bridge Client     │
+│         +            │ WebSocket │   --with-handlers    │
+│    Bridge Host  ────────────────────►                   │
+│    (port 8766)       │           │  Executes commands   │
+│                      │           │  on your files       │
+└──────────────────────┘           └──────────────────────┘
 ```
 
-### Install from Source
+## Use Cases
 
-```bash
-git clone https://github.com/willjackson/claude-code-bridge.git
-cd claude-code-bridge
-npm install
-npm run build
-npm link  # Makes 'claude-bridge' available globally
-```
+- **Remote Development** — Edit files on a dev server without leaving your local Claude Code
+- **Container Workflows** — Modify code inside Docker containers from outside
+- **Multi-Machine Projects** — Manage microservices across different hosts
+- **Cloud Development** — Work on EC2/cloud VMs from your laptop
+- **CI/CD Debugging** — Inspect and fix files on build servers
 
 ## Quick Start
 
-### Step 1: Install
+### 1. Install
 
 ```bash
 npm install -g @willjackson/claude-code-bridge
 ```
 
-### Step 2: Configure MCP (one-time setup on host)
+### 2. Setup MCP (one-time)
 
 ```bash
-claude mcp add remote-bridge -- npx @willjackson/claude-code-bridge mcp-server --connect ws://localhost:8766
+claude mcp add bridge -- npx @willjackson/claude-code-bridge mcp-server
 ```
 
-### Step 3: Start the Host and Launch Claude Code
+### 3. Start Host + Claude Code
 
-On your **local machine** (the host):
+On your **local machine**:
 
 ```bash
-claude-bridge start --port 8766 --launch-claude
+claude-bridge start --launch-claude
 ```
 
-This starts the bridge daemon and launches Claude Code with access to the remote bridge MCP tools.
-
-**With Claude flags** (e.g., skip permissions):
+Need to skip permissions? Add flags after `--`:
 
 ```bash
-claude-bridge start --port 8766 --launch-claude -- --dangerously-skip-permissions
+claude-bridge start --launch-claude -- --dangerously-skip-permissions
 ```
 
-Any arguments after `--` are passed directly to the `claude` command.
-
-### Step 4: Start the Client on Remote Machine
+### 4. Connect Remote Machine
 
 On the **remote machine** (server, container, VM):
 
 ```bash
-# Replace HOST_IP with your local machine's IP address
-claude-bridge start --with-handlers --connect ws://HOST_IP:8766
+claude-bridge start --with-handlers --connect ws://HOST_IP:8765
 ```
 
-The client will show incoming commands in the console:
+Replace `HOST_IP` with your local machine's IP address.
 
-```
-┌─────────────────────────────────────────────────────────────
-│ 📥 INCOMING TASK: Read config file
-│ ID: task-123
-│ Scope: execute
-│ Action: read_file
-│ Path: config/settings.json
-└─────────────────────────────────────────────────────────────
-
-  ✅ RESULT: Read 1234 chars from config/settings.json
-```
+That's it! Claude Code now has access to files on the remote machine.
 
-### Available MCP Tools
+## What You Can Do
 
-Once connected, Claude Code on your host has access to these tools:
+Once connected, Claude Code gains these MCP 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_read_file` | Read any file on the remote |
+| `bridge_write_file` | Create or modify files |
+| `bridge_delete_file` | Remove files |
+| `bridge_list_directory` | Browse directories |
 | `bridge_status` | Check connection status |
 
-## CLI Reference
-
-### Global Options
-
-```
-Usage: claude-bridge [options] [command]
-
-Options:
-  -V, --version     Output the version number
-  -v, --verbose     Enable verbose logging
-  --config <path>   Path to config file
-  -h, --help        Display help for command
-```
-
-### Commands
-
-#### `start` - Start the Bridge Server
-
-```bash
-claude-bridge start [options] [-- claude-args...]
+## Client Console
 
-Options:
-  -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)
-  -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:**
-
-```bash
-# 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 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/client machines)
-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
-claude-bridge stop
-```
-
-Stops the bridge daemon if running in background mode.
-
-#### `status` - Show Bridge Status
-
-```bash
-claude-bridge status [options]
+The remote client shows all incoming commands in real-time:
 
-Options:
-  --port <port>  Check status on specific port
 ```
-
-Shows:
-- Bridge running state
-- Listening port
-- Connected peers
-
-#### `connect` - Connect to Remote Bridge
-
-```bash
-claude-bridge connect <url>
-
-Arguments:
-  url  WebSocket URL (e.g., ws://localhost:8765)
+┌─────────────────────────────────────────────────────
+│ 📥 INCOMING TASK: Read config file
+│ Action: read_file
+│ Path: src/config.json
+└─────────────────────────────────────────────────────
+  ✅ RESULT: Read 2048 chars from src/config.json
 ```
 
-**Examples:**
+## CLI Reference
 
 ```bash
-claude-bridge connect ws://localhost:8765
-claude-bridge connect ws://192.168.1.100:8766
-```
+# Host mode (local machine)
+claude-bridge start [--port 8765] [--launch-claude] [-- claude-args]
 
-#### `info` - Show System Information
+# Client mode (remote machine)
+claude-bridge start --with-handlers --connect ws://HOST:PORT
 
-```bash
-claude-bridge info
+# Utilities
+claude-bridge status    # Check if bridge is running
+claude-bridge stop      # Stop the bridge daemon
+claude-bridge info      # Show system info
 ```
 
-Displays:
-- System information (Node version, OS, platform)
-- Network interfaces
-- Current configuration settings
-
 ## Configuration
 
-### Configuration File
-
-Create a configuration file at one of these locations:
-
-1. `.claude-bridge.yml` (project root)
-2. `~/.claude-bridge/config.yml` (user home)
-
-### Configuration Options
+Create `~/.claude-bridge/config.yml` for persistent settings:
 
 ```yaml
-# Instance identification
-instanceName: my-mac-desktop
-mode: host  # 'host' for local machine, 'client' for remote
-
-# Server settings (host mode)
+instanceName: my-bridge
 listen:
-  port: 8766
+  port: 8765
   host: 0.0.0.0
-
-# Connection to host (client mode)
-connect:
-  url: ws://192.168.1.100:8766
-
-# Context sharing settings
-contextSharing:
-  autoSync: true
-  syncInterval: 5000  # milliseconds
-  maxChunkTokens: 4000
-  includePatterns:
-    - "src/**/*.ts"
-    - "src/**/*.tsx"
-    - "*.json"
-  excludePatterns:
-    - "node_modules/**"
-    - "dist/**"
-    - ".git/**"
-
-# Interaction settings
 interaction:
-  requireConfirmation: false
-  notifyOnActivity: true
-  taskTimeout: 300000  # 5 minutes in milliseconds
-```
-
-### Configuration Reference
-
-| Setting | Type | Default | Description |
-|---------|------|---------|-------------|
-| `instanceName` | string | - | Unique name for this bridge instance |
-| `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 |
-| `contextSharing.includePatterns` | array | [...] | Glob patterns for included files |
-| `contextSharing.excludePatterns` | array | [...] | Glob patterns for excluded files |
-| `interaction.requireConfirmation` | boolean | false | Require user confirmation for tasks |
-| `interaction.notifyOnActivity` | boolean | true | Show notifications on activity |
-| `interaction.taskTimeout` | number | 300000 | Task timeout in ms |
-
-## Programmatic Usage
-
-### Basic Usage (Host)
-
-```typescript
-import { Bridge, BridgeConfig } from 'claude-code-bridge';
-
-// Create host bridge configuration
-const config: BridgeConfig = {
-  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 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
-
-```typescript
-// Send context to connected peers
-await bridge.syncContext({
-  files: [
-    { path: 'src/api.ts', content: 'export const api = {...}' },
-    { path: 'src/types.ts', content: 'export interface User {...}' },
-  ],
-  summary: 'API client implementation files',
-});
-
-// Handle incoming context
-bridge.onContextReceived((context) => {
-  console.log('Received context:', context.summary);
-  for (const file of context.files || []) {
-    console.log(`  - ${file.path}`);
-  }
-});
-
-// Request specific context from peer
-const chunks = await bridge.requestContext('authentication logic');
-```
-
-### Task Delegation
-
-```typescript
-// Delegate a task to the connected peer
-const result = await bridge.delegateTask({
-  id: 'task-001',
-  description: 'Refactor the UserService to use dependency injection',
-  scope: 'execute',  // 'execute', 'analyze', or 'suggest'
-  constraints: ['Maintain backward compatibility', 'Add unit tests'],
-  timeout: 60000,  // 1 minute
-});
-
-if (result.success) {
-  console.log('Task completed:', result.data);
-  for (const artifact of result.artifacts || []) {
-    console.log(`  ${artifact.action}: ${artifact.path}`);
-  }
-}
-
-// Handle incoming tasks
-bridge.onTaskReceived(async (task) => {
-  console.log('Received task:', task.description);
-
-  // Process the task...
-
-  return {
-    success: true,
-    data: { message: 'Task completed successfully' },
-    artifacts: [
-      { path: 'src/UserService.ts', action: 'modified' },
-    ],
-  };
-});
-```
-
-### 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.
-
-### Context Manager
-
-```typescript
-import { ContextManager } from 'claude-code-bridge';
-
-const contextManager = new ContextManager({
-  rootPath: '/path/to/project',
-  includePatterns: ['src/**/*.ts', '*.json'],
-  excludePatterns: ['node_modules/**', 'dist/**'],
-});
-
-// Generate a project snapshot
-const snapshot = await contextManager.generateSnapshot();
-console.log('Project files:', snapshot.keyFiles);
-
-// Get relevant context for a task
-const chunks = await contextManager.getRelevantContext(
-  'user authentication',
-  4000  // max tokens
-);
-
-// Get changes since last sync
-const delta = await contextManager.getDelta(previousSnapshotId);
-for (const change of delta.changes) {
-  console.log(`${change.action}: ${change.path}`);
-}
+  taskTimeout: 300000
 ```
 
 ## Troubleshooting
 
-### Connection Issues
+**Can't connect?**
+- Verify the host is running: `claude-bridge status`
+- Check firewall allows port 8765
+- Confirm IP is reachable: `ping HOST_IP`
 
-**Problem:** Client cannot connect to host
+**Commands not executing?**
+- Ensure client uses `--with-handlers`
+- Check client console for errors
 
-**Solutions:**
-1. Ensure the host bridge is running: `claude-bridge status`
-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`
+**Need more detail?**
+- Run with verbose logging: `claude-bridge start -v`
 
-**Problem:** Connection keeps dropping
-
-**Solutions:**
-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
-
-**Solutions:**
-1. Use a different port: `claude-bridge start --port 9000`
-2. Find and stop the process using the port:
-   ```bash
-   lsof -i :8765
-   kill <PID>
-   ```
-
-### Debugging
-
-Enable verbose logging for detailed output:
-
-```bash
-claude-bridge start -v
-```
-
-Or set the log level via environment variable:
-
-```bash
-LOG_LEVEL=debug claude-bridge start
-```
-
-## Development
-
-### Prerequisites
+## Requirements
 
 - Node.js 20+
-- npm or pnpm
-
-### Setup
-
-```bash
-# Clone the repository
-git clone https://github.com/willjackson/claude-code-bridge.git
-cd claude-code-bridge
-
-# Install dependencies
-npm install
-
-# Build
-npm run build
-
-# Run tests
-npm test
-
-# Run tests in watch mode
-npm run test:watch
-
-# Type checking
-npm run lint
-```
-
-### Project Structure
-
-```
-claude-code-bridge/
-├── src/
-│   ├── index.ts           # Main exports
-│   ├── bridge/
-│   │   ├── core.ts        # Bridge class
-│   │   ├── protocol.ts    # Message types & validation
-│   │   ├── messages.ts    # Message builders
-│   │   └── context.ts     # Context manager
-│   ├── transport/
-│   │   ├── interface.ts   # Transport abstraction
-│   │   └── websocket.ts   # WebSocket implementation
-│   ├── cli/
-│   │   ├── index.ts       # CLI entry point
-│   │   └── commands/      # CLI commands
-│   └── utils/
-│       ├── logger.ts      # Logging utility
-│       ├── config.ts      # Configuration loading
-│       └── tokens.ts      # Token estimation
-├── tests/
-│   ├── unit/              # Unit tests
-│   ├── integration/       # Integration tests
-│   └── e2e/               # End-to-end tests
-```
-
-### Running Tests
-
-```bash
-# Run all tests
-npm test
-
-# Run with coverage
-npm run test:coverage
-
-# Run specific test file
-npm test -- tests/unit/bridge/protocol.test.ts
-
-# Run tests matching pattern
-npm test -- --grep "WebSocket"
-```
+- Claude Code with MCP support
 
 ## License
 
-MIT License - see [LICENSE](./LICENSE) for details.
-
-## Contributing
-
-1. Fork the repository
-2. Create a feature branch: `git checkout -b feature/my-feature`
-3. Make your changes
-4. Run tests: `npm test`
-5. Commit: `git commit -m 'Add my feature'`
-6. Push: `git push origin feature/my-feature`
-7. Open a Pull Request
+MIT
 
-## Support
+## Links
 
-- GitHub Issues: [Report a bug or request a feature](https://github.com/willjackson/claude-code-bridge/issues)
+- [npm package](https://www.npmjs.com/package/@willjackson/claude-code-bridge)
+- [Report issues](https://github.com/willjackson/claude-code-bridge/issues)