@willjackson/claude-code-bridge 0.3.0 → 0.5.0

package/README.md

@@ -62,13 +62,15 @@ Claude Code Bridge connects two Claude Code instances running on different machi
 ### 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
@@ -83,33 +85,53 @@ npm link  # Makes 'claude-bridge' available globally
 
 ## Quick Start
 
-### Scenario 1: Mac to Docker Container
+### Scenario 1: Start Bridge and Launch Claude Code
+
+The easiest way to get started - start the bridge and launch Claude Code in one command:
+
+**Step 1: Configure the MCP server (one-time setup)**
+
+```bash
+claude mcp add remote-bridge -- npx @willjackson/claude-code-bridge mcp-server --connect ws://localhost:8766
+```
+
+**Step 2: Start bridge and launch Claude Code**
+
+```bash
+claude-bridge start --port 8766 --launch-claude
+```
+
+This starts the bridge daemon in the background and launches Claude Code with access to the remote bridge tools.
+
+### Scenario 2: Mac to Remote Server
 
 **Step 1: Start the bridge on your Mac**
 
 ```bash
-claude-bridge start --port 8766
+claude-bridge start --port 8766 --launch-claude
 ```
 
-**Step 2: Start the bridge in your container and connect**
+**Step 2: Start the bridge on the remote machine and connect**
 
 ```bash
-# Inside the container (Docksal, DDEV, or Docker)
-claude-bridge start --port 8765 --connect ws://host.docker.internal:8766
+# On remote machine (replace YOUR_MAC_IP with actual IP)
+claude-bridge start --with-handlers --connect ws://YOUR_MAC_IP:8766
 ```
 
-### Scenario 2: Peer-to-Peer Mode
+Now Claude Code on your Mac can read/write files on the remote machine.
+
+### Scenario 3: 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.
@@ -118,17 +140,17 @@ Once connected, either side can send context or delegate tasks to the other.
 
 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
 
@@ -157,11 +179,15 @@ Options:
   -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
 ```
 
 **Examples:**
 
 ```bash
+# Start bridge and launch Claude Code (recommended for local use)
+claude-bridge start --port 8766 --launch-claude
+
 # Start with default settings
 claude-bridge start
 
@@ -174,10 +200,66 @@ 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
+# Start with file operation handlers enabled (for remote 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
@@ -213,7 +295,7 @@ 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
 ```
 
 #### `info` - Show System Information
@@ -251,7 +333,6 @@ listen:
 # Connection to remote bridge
 connect:
   url: ws://localhost:8765
-  hostGateway: true  # Use host.docker.internal
 
 # Context sharing settings
 contextSharing:
@@ -283,7 +364,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 |
@@ -461,20 +541,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
@@ -507,13 +573,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
 
@@ -621,12 +687,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.

package/dist/{chunk-LUL3SX2F.js → chunk-MHUQYPTB.js}

@@ -1,7 +1,7 @@
 // src/utils/logger.ts
 import pino from "pino";
-function isDevelopment() {
-  return process.env.NODE_ENV !== "production";
+function usePrettyPrint() {
+  return process.env.NODE_ENV === "development";
 }
 function getDefaultLevel() {
   const envLevel = process.env.LOG_LEVEL?.toLowerCase();
@@ -17,7 +17,7 @@ function createLogger(name, level) {
     name,
     level: logLevel
   };
-  if (isDevelopment()) {
+  if (usePrettyPrint()) {
     options.transport = {
       target: "pino-pretty",
       options: {
@@ -1717,6 +1717,406 @@ function loadConfigSync(configPath) {
   return { ...DEFAULT_CONFIG };
 }
 
+// src/mcp/tools.ts
+import { z as z2 } from "zod";
+var logger3 = createLogger("mcp:tools");
+var ReadFileInputSchema = z2.object({
+  path: z2.string().describe("Path to the file to read")
+});
+var WriteFileInputSchema = z2.object({
+  path: z2.string().describe("Path to the file to write"),
+  content: z2.string().describe("Content to write to the file")
+});
+var DeleteFileInputSchema = z2.object({
+  path: z2.string().describe("Path to the file to delete")
+});
+var ListDirectoryInputSchema = z2.object({
+  path: z2.string().describe("Path to the directory to list")
+});
+var DelegateTaskInputSchema = z2.object({
+  description: z2.string().describe("Description of the task to delegate"),
+  scope: z2.enum(["execute", "analyze", "suggest"]).describe("Task scope"),
+  data: z2.record(z2.unknown()).optional().describe("Additional task data")
+});
+var RequestContextInputSchema = z2.object({
+  query: z2.string().describe("Query describing what files to retrieve")
+});
+var TOOL_DEFINITIONS = [
+  {
+    name: "bridge_read_file",
+    description: "Read a file from the remote connected instance",
+    inputSchema: ReadFileInputSchema
+  },
+  {
+    name: "bridge_write_file",
+    description: "Write a file to the remote connected instance",
+    inputSchema: WriteFileInputSchema
+  },
+  {
+    name: "bridge_delete_file",
+    description: "Delete a file on the remote connected instance",
+    inputSchema: DeleteFileInputSchema
+  },
+  {
+    name: "bridge_list_directory",
+    description: "List files and folders in a directory on the remote connected instance",
+    inputSchema: ListDirectoryInputSchema
+  },
+  {
+    name: "bridge_delegate_task",
+    description: "Delegate a custom task to the remote connected instance",
+    inputSchema: DelegateTaskInputSchema
+  },
+  {
+    name: "bridge_request_context",
+    description: "Request files matching a query from the remote connected instance",
+    inputSchema: RequestContextInputSchema
+  },
+  {
+    name: "bridge_status",
+    description: "Get bridge status and connected peers",
+    inputSchema: z2.object({})
+  }
+];
+function createToolHandlers(bridge) {
+  const handlers = {};
+  function errorResponse(message) {
+    return {
+      content: [{ type: "text", text: `Error: ${message}` }],
+      isError: true
+    };
+  }
+  function successResponse(text) {
+    return {
+      content: [{ type: "text", text }]
+    };
+  }
+  async function delegateFileTask(action, data, description) {
+    const taskId = `mcp-${Date.now()}-${Math.random().toString(36).substring(2, 9)}`;
+    return bridge.delegateTask({
+      id: taskId,
+      description,
+      scope: "execute",
+      data: { action, ...data }
+    });
+  }
+  handlers["bridge_read_file"] = async (args) => {
+    const input = ReadFileInputSchema.parse(args);
+    logger3.debug({ path: input.path }, "Reading file");
+    try {
+      const result = await delegateFileTask(
+        "read_file",
+        { path: input.path },
+        `Read file: ${input.path}`
+      );
+      if (!result.success) {
+        return errorResponse(result.error || "Failed to read file");
+      }
+      return successResponse(result.data.content);
+    } catch (err) {
+      logger3.error({ error: err.message, path: input.path }, "Failed to read file");
+      return errorResponse(err.message);
+    }
+  };
+  handlers["bridge_write_file"] = async (args) => {
+    const input = WriteFileInputSchema.parse(args);
+    logger3.debug({ path: input.path, contentLength: input.content.length }, "Writing file");
+    try {
+      const result = await delegateFileTask(
+        "write_file",
+        { path: input.path, content: input.content },
+        `Write file: ${input.path}`
+      );
+      if (!result.success) {
+        return errorResponse(result.error || "Failed to write file");
+      }
+      return successResponse(`File written successfully: ${input.path} (${result.data.bytesWritten} bytes)`);
+    } catch (err) {
+      logger3.error({ error: err.message, path: input.path }, "Failed to write file");
+      return errorResponse(err.message);
+    }
+  };
+  handlers["bridge_delete_file"] = async (args) => {
+    const input = DeleteFileInputSchema.parse(args);
+    logger3.debug({ path: input.path }, "Deleting file");
+    try {
+      const result = await delegateFileTask(
+        "delete_file",
+        { path: input.path },
+        `Delete file: ${input.path}`
+      );
+      if (!result.success) {
+        return errorResponse(result.error || "Failed to delete file");
+      }
+      return successResponse(`File deleted successfully: ${input.path}`);
+    } catch (err) {
+      logger3.error({ error: err.message, path: input.path }, "Failed to delete file");
+      return errorResponse(err.message);
+    }
+  };
+  handlers["bridge_list_directory"] = async (args) => {
+    const input = ListDirectoryInputSchema.parse(args);
+    logger3.debug({ path: input.path }, "Listing directory");
+    try {
+      const result = await delegateFileTask(
+        "list_directory",
+        { path: input.path },
+        `List directory: ${input.path}`
+      );
+      if (!result.success) {
+        return errorResponse(result.error || "Failed to list directory");
+      }
+      const entries = result.data.entries;
+      if (!entries || entries.length === 0) {
+        return successResponse(`Directory is empty: ${input.path}`);
+      }
+      const listing = entries.map((e) => `${e.type === "directory" ? "\u{1F4C1}" : "\u{1F4C4}"} ${e.name}`).join("\n");
+      return successResponse(`Contents of ${input.path}:
+${listing}`);
+    } catch (err) {
+      logger3.error({ error: err.message, path: input.path }, "Failed to list directory");
+      return errorResponse(err.message);
+    }
+  };
+  handlers["bridge_delegate_task"] = async (args) => {
+    const input = DelegateTaskInputSchema.parse(args);
+    logger3.debug({ description: input.description, scope: input.scope }, "Delegating task");
+    try {
+      const taskId = `mcp-${Date.now()}-${Math.random().toString(36).substring(2, 9)}`;
+      const result = await bridge.delegateTask({
+        id: taskId,
+        description: input.description,
+        scope: input.scope,
+        data: input.data
+      });
+      if (!result.success) {
+        return errorResponse(result.error || "Task failed");
+      }
+      return successResponse(JSON.stringify(result.data, null, 2));
+    } catch (err) {
+      logger3.error({ error: err.message }, "Failed to delegate task");
+      return errorResponse(err.message);
+    }
+  };
+  handlers["bridge_request_context"] = async (args) => {
+    const input = RequestContextInputSchema.parse(args);
+    logger3.debug({ query: input.query }, "Requesting context");
+    try {
+      const files = await bridge.requestContext(input.query);
+      if (files.length === 0) {
+        return successResponse("No files found matching the query.");
+      }
+      const fileResults = files.map((f) => {
+        const header = `=== ${f.path} ===`;
+        const content = f.content;
+        return `${header}
+${content}`;
+      }).join("\n\n");
+      return successResponse(`Found ${files.length} file(s):
+
+${fileResults}`);
+    } catch (err) {
+      logger3.error({ error: err.message }, "Failed to request context");
+      return errorResponse(err.message);
+    }
+  };
+  handlers["bridge_status"] = async () => {
+    logger3.debug("Getting bridge status");
+    const peers = bridge.getPeers();
+    const peerCount = bridge.getPeerCount();
+    const isStarted = bridge.isStarted();
+    const mode = bridge.getMode();
+    const instanceName = bridge.getInstanceName();
+    const status = {
+      instanceName,
+      mode,
+      started: isStarted,
+      peerCount,
+      peers: peers.map((p) => ({
+        id: p.id,
+        name: p.name,
+        connectedAt: new Date(p.connectedAt).toISOString(),
+        lastActivity: new Date(p.lastActivity).toISOString()
+      }))
+    };
+    return successResponse(JSON.stringify(status, null, 2));
+  };
+  return handlers;
+}
+function zodToJsonSchema(schema) {
+  if (schema instanceof z2.ZodObject) {
+    const shape = schema.shape;
+    const properties = {};
+    const required = [];
+    for (const [key, value] of Object.entries(shape)) {
+      const zodValue = value;
+      properties[key] = zodToJsonSchema(zodValue);
+      if (!(zodValue instanceof z2.ZodOptional)) {
+        required.push(key);
+      }
+    }
+    return {
+      type: "object",
+      properties,
+      ...required.length > 0 ? { required } : {}
+    };
+  }
+  if (schema instanceof z2.ZodString) {
+    const result = { type: "string" };
+    if (schema.description) {
+      result.description = schema.description;
+    }
+    return result;
+  }
+  if (schema instanceof z2.ZodEnum) {
+    return {
+      type: "string",
+      enum: schema.options
+    };
+  }
+  if (schema instanceof z2.ZodOptional) {
+    return zodToJsonSchema(schema.unwrap());
+  }
+  if (schema instanceof z2.ZodRecord) {
+    return {
+      type: "object",
+      additionalProperties: true
+    };
+  }
+  if (schema instanceof z2.ZodUnknown) {
+    return {};
+  }
+  return { type: "string" };
+}
+
+// src/mcp/server.ts
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema
+} from "@modelcontextprotocol/sdk/types.js";
+var logger4 = createLogger("mcp:server");
+var BridgeMcpServer = class {
+  server;
+  bridge;
+  config;
+  toolHandlers = null;
+  constructor(config) {
+    this.config = config;
+    this.server = new Server(
+      {
+        name: config.name ?? "claude-bridge",
+        version: config.version ?? "0.4.0"
+      },
+      {
+        capabilities: {
+          tools: {}
+        }
+      }
+    );
+    const bridgeConfig = {
+      mode: "client",
+      instanceName: config.instanceName ?? `mcp-server-${process.pid}`,
+      connect: {
+        url: config.bridgeUrl
+      },
+      taskTimeout: config.taskTimeout ?? 6e4
+    };
+    this.bridge = new Bridge(bridgeConfig);
+    this.registerHandlers();
+  }
+  /**
+   * Register MCP request handlers
+   */
+  registerHandlers() {
+    this.server.setRequestHandler(ListToolsRequestSchema, async () => {
+      logger4.debug("Listing tools");
+      return {
+        tools: TOOL_DEFINITIONS.map((tool) => ({
+          name: tool.name,
+          description: tool.description,
+          inputSchema: zodToJsonSchema(tool.inputSchema)
+        }))
+      };
+    });
+    this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
+      const { name, arguments: args } = request.params;
+      logger4.debug({ tool: name }, "Tool call received");
+      if (!this.toolHandlers) {
+        this.toolHandlers = createToolHandlers(this.bridge);
+      }
+      const handler = this.toolHandlers[name];
+      if (!handler) {
+        logger4.warn({ tool: name }, "Unknown tool requested");
+        return {
+          content: [{ type: "text", text: `Unknown tool: ${name}` }],
+          isError: true
+        };
+      }
+      try {
+        const result = await handler(args ?? {});
+        logger4.debug({ tool: name, isError: result.isError }, "Tool call completed");
+        return {
+          content: result.content,
+          isError: result.isError
+        };
+      } catch (err) {
+        logger4.error({ tool: name, error: err.message }, "Tool call failed");
+        return {
+          content: [{ type: "text", text: `Error: ${err.message}` }],
+          isError: true
+        };
+      }
+    });
+  }
+  /**
+   * Start the MCP server
+   * Connects to bridge daemon and starts listening on stdio
+   */
+  async start() {
+    console.error("[MCP] Starting bridge MCP server...");
+    console.error(`[MCP] Connecting to bridge at ${this.config.bridgeUrl}`);
+    try {
+      await this.bridge.start();
+      console.error("[MCP] Connected to bridge daemon");
+      this.toolHandlers = createToolHandlers(this.bridge);
+      const transport = new StdioServerTransport();
+      await this.server.connect(transport);
+      console.error("[MCP] MCP server started and listening on stdio");
+      logger4.info("MCP server started");
+    } catch (err) {
+      console.error(`[MCP] Failed to start: ${err.message}`);
+      throw err;
+    }
+  }
+  /**
+   * Stop the MCP server
+   */
+  async stop() {
+    console.error("[MCP] Stopping MCP server...");
+    try {
+      await this.bridge.stop();
+      await this.server.close();
+      console.error("[MCP] MCP server stopped");
+      logger4.info("MCP server stopped");
+    } catch (err) {
+      console.error(`[MCP] Error during shutdown: ${err.message}`);
+    }
+  }
+  /**
+   * Get the bridge instance
+   */
+  getBridge() {
+    return this.bridge;
+  }
+};
+async function startMcpServer(config) {
+  const server = new BridgeMcpServer(config);
+  await server.start();
+  return server;
+}
+
 export {
   createLogger,
   createChildLogger,
@@ -1745,6 +2145,10 @@ export {
   DEFAULT_CONFIG,
   mergeConfig,
   loadConfig,
-  loadConfigSync
+  loadConfigSync,
+  TOOL_DEFINITIONS,
+  createToolHandlers,
+  BridgeMcpServer,
+  startMcpServer
 };
-//# sourceMappingURL=chunk-LUL3SX2F.js.map
+//# sourceMappingURL=chunk-MHUQYPTB.js.map