@willjackson/claude-code-bridge 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Will Jackson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,690 @@
+# Claude Code Bridge
+
+A bidirectional communication system that enables two separate Claude Code instances to collaborate across different environments.
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Features](#features)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [CLI Reference](#cli-reference)
+- [Configuration](#configuration)
+- [Environment Setup](#environment-setup)
+- [Programmatic Usage](#programmatic-usage)
+- [Troubleshooting](#troubleshooting)
+- [Development](#development)
+- [License](#license)
+
+## 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).
+
+### Architecture
+
+```
+┌─────────────────────────┐                    ┌─────────────────────────┐
+│      Local Mac          │                    │   Container (CLI/Web)   │
+│  ┌───────────────────┐  │                    │  ┌───────────────────┐  │
+│  │   Claude Code     │  │                    │  │   Claude Code     │  │
+│  │   (Desktop App)   │  │                    │  │   (Server App)    │  │
+│  └─────────┬─────────┘  │                    │  └─────────┬─────────┘  │
+│            │            │                    │            │            │
+│  ┌─────────┴─────────┐  │    WebSocket       │  ┌─────────┴─────────┐  │
+│  │   Bridge Plugin   │◄─┼────────────────────┼─►│   Bridge Plugin   │  │
+│  │   (port 8766)     │  │                    │  │   (port 8765)     │  │
+│  └───────────────────┘  │                    │  └───────────────────┘  │
+└─────────────────────────┘                    └─────────────────────────┘
+```
+
+### 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
+
+## 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
+- **Peer-to-peer mode** allowing bidirectional communication
+- **CLI and programmatic API** for flexible integration
+
+## Installation
+
+### Prerequisites
+
+- Node.js 20 or higher
+- npm or pnpm
+
+### Global Installation (Recommended)
+
+```bash
+npm install -g claude-code-bridge
+```
+
+### Run Without Installing
+
+```bash
+npx claude-code-bridge start
+```
+
+### Install from Source
+
+```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
+```
+
+## Quick Start
+
+### Scenario 1: Mac to Docker Container
+
+**Step 1: Start the bridge on your Mac**
+
+```bash
+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:
+
+```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
+```
+
+### Scenario 3: Peer-to-Peer Mode
+
+Both instances can initiate communication:
+
+**Terminal 1 (Mac):**
+```bash
+claude-bridge start --port 8766
+```
+
+**Terminal 2 (Container):**
+```bash
+claude-bridge start --port 8765 --connect ws://host.docker.internal:8766
+```
+
+Once connected, either side can send context or delegate tasks to the other.
+
+## 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]
+
+Options:
+  -p, --port <port>    Port to listen on (default: 8765 in container, 8766 native)
+  -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
+```
+
+**Examples:**
+
+```bash
+# 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 in daemon mode
+claude-bridge start --daemon
+```
+
+#### `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]
+
+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)
+```
+
+**Examples:**
+
+```bash
+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
+
+```bash
+claude-bridge info
+```
+
+Displays:
+- Detected environment (native, Docksal, DDEV, Lando, Docker)
+- Platform information
+- Network configuration
+- 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
+
+```yaml
+# Instance identification
+instanceName: my-mac-desktop
+mode: peer  # host, client, or peer
+
+# Server settings
+listen:
+  port: 8766
+  host: 0.0.0.0
+
+# Connection to remote bridge
+connect:
+  url: ws://localhost:8765
+  hostGateway: true  # Use host.docker.internal
+
+# 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`, `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 |
+| `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 |
+| `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 |
+
+## 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
+
+```typescript
+import { Bridge, BridgeConfig } from 'claude-code-bridge';
+
+// Create 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,
+  },
+};
+
+// Create and start bridge
+const bridge = new Bridge(config);
+await bridge.start();
+
+// Get connected peers
+const peers = bridge.getPeers();
+console.log('Connected peers:', peers);
+```
+
+### 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' },
+    ],
+  };
+});
+```
+
+### 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
+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}`);
+}
+```
+
+## Troubleshooting
+
+### Connection Issues
+
+**Problem:** Cannot connect to bridge from container
+
+**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`
+
+**Problem:** Connection keeps dropping
+
+**Solutions:**
+1. Check network stability
+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
+
+**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
+
+- 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
+│   │   └── discovery.ts   # Peer discovery
+│   ├── environment/
+│   │   ├── detect.ts      # Environment detection
+│   │   ├── docksal.ts     # Docksal helpers
+│   │   ├── ddev.ts        # DDEV helpers
+│   │   └── lando.ts       # Lando helpers
+│   ├── 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
+└── addons/
+    ├── ddev/              # DDEV addon
+    ├── docksal/           # Docksal addon
+    └── lando/             # Lando plugin
+```
+
+### 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"
+```
+
+## 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.
+
+## 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
+
+## Support
+
+- GitHub Issues: [Report a bug or request a feature](https://github.com/willjackson/claude-code-bridge/issues)