claudelink-bridge 0.1.1 → 0.1.3

package/README.md

@@ -1,182 +1,231 @@
 # claudelink-bridge
 
-> Local bridge server that connects the [ClaudeLink Chrome extension](https://github.com/devops-monk/claude-link) to Claude Code CLI running on your machine.
+**Bridge your browser to Claude Code CLI.**
 
-[![npm version](https://img.shields.io/npm/v/claudelink-bridge.svg)](https://www.npmjs.com/package/claudelink-bridge)
-[![npm downloads](https://img.shields.io/npm/dm/claudelink-bridge.svg)](https://www.npmjs.com/package/claudelink-bridge)
-[![License: MIT](https://img.shields.io/badge/License-MIT-purple.svg)](https://opensource.org/licenses/MIT)
-[![Platform](https://img.shields.io/badge/platform-macOS%20%7C%20Linux%20%7C%20Windows-blue.svg)](#)
+The local server for the [ClaudeLink Chrome extension](https://github.com/devops-monk/claude-link). Send screenshots, selected text, page content, and custom commands from any webpage directly to your local Claude Code — without leaving the browser.
+
+[![npm](https://img.shields.io/npm/v/claudelink-bridge?color=7c3aed&label=npm)](https://www.npmjs.com/package/claudelink-bridge)
+[![license](https://img.shields.io/npm/l/claudelink-bridge?color=7c3aed)](LICENSE)
+[![node](https://img.shields.io/node/v/claudelink-bridge?color=7c3aed)](https://nodejs.org)
+[![platform](https://img.shields.io/badge/platform-macOS%20%7C%20Linux%20%7C%20Windows-7c3aed)](#installation)
 
 ---
 
-## What is this?
+## How it works
+
+```
+Chrome Extension  ←── WebSocket (localhost:9999) ──→  claudelink-bridge  ──→  claude CLI
+```
+
+The bridge runs a local WebSocket server. The ClaudeLink extension connects to it, sends prompts and context, and the bridge passes them to your local `claude` binary — streaming the response back token by token. **Everything stays on your machine.**
 
-ClaudeLink is a Chrome extension that lets you send browser content — screenshots, selected text, page context, form data — directly to **Claude Code CLI** without leaving your browser.
+---
 
-This package (`claudelink-bridge`) is the local server that makes it work. It:
+## Quick start
 
-- Runs a **WebSocket server on `localhost:9999`** that the extension connects to
-- Receives prompts and context from the browser
-- Passes them to your local `claude` CLI and streams the response back
-- Can be installed as a **background service** that starts automatically on login
+**Step 1 — Install Claude Code CLI** (if you haven't already)
 
+```bash
+npm install -g @anthropic-ai/claude-code
+claude   # log in
 ```
-Chrome Extension  ←──WebSocket──→  claudelink-bridge  ←──spawns──→  claude CLI
+
+**Step 2 — Install the bridge as a background service**
+
+```bash
+npx claudelink-bridge setup
 ```
 
-Everything stays on your machine. No data is sent to any external server.
+That's it. The bridge starts automatically on every login — no manual steps after this.
+
+**Step 3 — Install the ClaudeLink Chrome extension**
+
+Download from the [latest GitHub release](https://github.com/devops-monk/claude-link/releases/latest), unzip, and load it in `chrome://extensions` with Developer Mode enabled.
+
+---
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `npx claudelink-bridge setup` | Install as auto-start background service (**run once**) |
+| `npx claudelink-bridge start` | Run manually in the foreground |
+| `npx claudelink-bridge status` | Check if the service is running |
+| `npx claudelink-bridge stop` | Stop the background service |
+| `npx claudelink-bridge kill` | Force-kill whatever is on port 9999 |
+| `npx claudelink-bridge uninstall` | Remove the background service |
 
 ---
 
 ## Requirements
 
-- **Node.js** v18 or higher
-- **Claude Code CLI** — [install here](https://docs.anthropic.com/en/docs/claude-code)
+- **Node.js** v18+
+- **Claude Code CLI** — `npm install -g @anthropic-ai/claude-code`
 
-```bash
-# Check Node.js version
-node --version
+---
 
-# Install Claude Code CLI
-npm install -g @anthropic-ai/claude-code
+## Auto-start setup by platform
 
-# Log in (one time)
-claude
-```
+Running `npx claudelink-bridge setup` does everything automatically. Here's what happens on each platform and how to verify it worked.
 
 ---
 
-## Installation
+### macOS
 
-### Recommended — install as a background service (runs automatically on login)
+`setup` creates a **launchd plist** and loads it immediately. The bridge will start automatically every time you log in.
 
 ```bash
 npx claudelink-bridge setup
 ```
 
-This single command:
-1. Checks that Node.js and Claude Code CLI are installed
-2. Installs the bridge as a background service
-3. Starts it immediately
+**Verify it's running:**
+```bash
+npx claudelink-bridge status
+# or check directly:
+launchctl list | grep claudelink
+```
+
+**View logs:**
+```bash
+tail -f ~/.claudelink/bridge.log
+```
 
-| Platform | Method |
-|----------|--------|
-| **macOS** | launchd plist in `~/Library/LaunchAgents/` |
-| **Linux** | systemd user service |
-| **Windows** | Task Scheduler entry at login |
+**If it stops unexpectedly:**
+```bash
+launchctl unload ~/Library/LaunchAgents/com.devops-monk.claudelink.plist
+launchctl load  ~/Library/LaunchAgents/com.devops-monk.claudelink.plist
+```
 
-After setup, you never need to think about the bridge again — it starts automatically every time you log in.
+**Config file location:** `~/Library/LaunchAgents/com.devops-monk.claudelink.plist`
 
 ---
 
-### Manual — run in the foreground
+### Linux
 
-If you prefer to start it manually:
+`setup` creates a **systemd user service** and enables it so it starts on login. No root/sudo required.
 
 ```bash
-npx claudelink-bridge start
+npx claudelink-bridge setup
 ```
 
-Keep the terminal open while using the extension. Press `Ctrl+C` to stop.
+**Verify it's running:**
+```bash
+npx claudelink-bridge status
+# or check directly:
+systemctl --user status claudelink
+```
 
----
+**View live logs:**
+```bash
+journalctl --user -u claudelink -f
+```
 
-## Commands
+**If it stops unexpectedly:**
+```bash
+systemctl --user restart claudelink
+```
 
+**Lingering (start on boot without login):** If you want the bridge to run even when you're not logged in interactively:
 ```bash
-npx claudelink-bridge setup      # Install as auto-start background service (run once)
-npx claudelink-bridge start      # Run manually in the foreground
-npx claudelink-bridge status     # Check if the service is running
-npx claudelink-bridge stop       # Stop the background service
-npx claudelink-bridge kill       # Force-kill whatever is on port 9999
-npx claudelink-bridge uninstall  # Remove the background service
+loginctl enable-linger $USER
 ```
 
+**Config file location:** `~/.config/systemd/user/claudelink.service`
+
 ---
 
-## Configuration
+### Windows
 
-### Custom port
+`setup` creates a **Task Scheduler entry** that runs the bridge at login. Run this in **PowerShell** (no admin required):
 
-By default the bridge listens on port `9999`. To use a different port:
+```powershell
+npx claudelink-bridge setup
+```
 
-```bash
-CLAUDELINK_PORT=9998 npx claudelink-bridge setup
+**Verify it's running:**
+```powershell
+npx claudelink-bridge status
+# or check directly in Task Scheduler:
+schtasks /Query /TN ClaudeLinkBridge
 ```
 
-Then update the port in the extension: **Popup → Settings → Bridge port**.
+**View logs:**
+```powershell
+Get-Content "$env:USERPROFILE\.claudelink\bridge.log" -Wait
+```
 
-### Logs (macOS / Linux)
+**If it stops unexpectedly:**
+```powershell
+schtasks /Run /TN ClaudeLinkBridge
+```
 
-```bash
-# View bridge output
-cat ~/.claudelink/bridge.log
+**Manually open Task Scheduler** to verify: press `Win+R` → type `taskschd.msc` → look for `ClaudeLinkBridge` in the task list.
 
-# View errors
-cat ~/.claudelink/bridge-error.log
-
-# Follow live
-tail -f ~/.claudelink/bridge.log
-```
+**Config:** Task Scheduler entry named `ClaudeLinkBridge`, visible in Task Scheduler Library.
 
 ---
 
-## Troubleshooting
+## Configuration
 
-**Status indicator is red ("Disconnected")**
+**Custom port** (default: `9999`):
 
 ```bash
-npx claudelink-bridge status
-npx claudelink-bridge start     # restart if stopped
+CLAUDELINK_PORT=9998 npx claudelink-bridge setup
 ```
 
-**`EADDRINUSE` — port already in use**
+Then update the port in the extension popup → **Settings → Bridge port**.
+
+**Logs** (macOS/Linux):
 
 ```bash
-npx claudelink-bridge kill      # kill whatever is on the port
-npx claudelink-bridge start     # start fresh
+tail -f ~/.claudelink/bridge.log        # live output
+cat ~/.claudelink/bridge-error.log      # errors
 ```
 
-**"Failed to start claude" in the output panel**
+---
 
-Make sure Claude Code CLI is installed and logged in:
+## Troubleshooting
 
+**Red dot / "Disconnected" in extension**
 ```bash
-npm install -g @anthropic-ai/claude-code
-claude --version
-claude    # log in if prompted
+npx claudelink-bridge status
+npx claudelink-bridge start
 ```
 
-**Bridge stops after system update (macOS/Linux)**
-
+**Port already in use**
 ```bash
-npx claudelink-bridge setup     # re-register the service
+npx claudelink-bridge kill
+npx claudelink-bridge start
 ```
 
-**Remove everything**
+**"Failed to start claude"** — Claude Code CLI not found or not logged in:
+```bash
+npm install -g @anthropic-ai/claude-code
+claude
+```
 
+**Bridge stopped after system update**
 ```bash
-npx claudelink-bridge uninstall
+npx claudelink-bridge setup   # re-registers the service
 ```
 
 ---
 
 ## Security
 
-- The bridge only accepts WebSocket connections from `chrome-extension://` origins — no other apps or websites can connect to it
-- All prompts and responses stay local — the bridge only communicates with your local `claude` binary
-- No telemetry, no analytics, no external API calls
+- Accepts connections **only from `chrome-extension://` origins** — no other apps or websites can connect
+- All data stays local — the bridge only talks to your local `claude` binary
+- No telemetry, no analytics, no external requests
 
 ---
 
-## Related
+## Links
 
-- [ClaudeLink Chrome Extension](https://github.com/devops-monk/claude-link) — the browser extension
-- [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code) — Anthropic's official CLI
-- [DevOps-Monk](https://devops-monk.com) — more developer tools
+- [ClaudeLink Chrome Extension](https://github.com/devops-monk/claude-link)
+- [Claude Code CLI docs](https://docs.anthropic.com/en/docs/claude-code)
+- [Report an issue](https://github.com/devops-monk/claude-link/issues)
+- [DevOps-Monk](https://devops-monk.com)
 
 ---
 
-## License
-
 MIT © [DevOps-Monk](https://devops-monk.com)

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "claudelink-bridge",
-  "version": "0.1.1",
-  "description": "Local bridge server connecting ClaudeLink Chrome extension to Claude Code CLI",
+  "version": "0.1.3",
+  "description": "Bridge your browser to Claude Code CLI. The local server for the ClaudeLink Chrome extension — send screenshots, page content, and custom commands from any webpage directly to Claude Code.",
   "type": "module",
   "bin": {
     "claudelink-bridge": "bin/cli.js"
@@ -9,6 +9,11 @@
   "scripts": {
     "start": "node lib/server.js"
   },
+  "files": [
+    "bin/",
+    "lib/",
+    "README.md"
+  ],
   "dependencies": {
     "ws": "^8.18.0"
   },
@@ -18,9 +23,28 @@
   "keywords": [
     "claude",
     "claude-code",
-    "cli",
-    "chrome-extension"
+    "claude-code-cli",
+    "anthropic",
+    "chrome-extension",
+    "browser-extension",
+    "ai",
+    "llm",
+    "devtools",
+    "websocket",
+    "bridge",
+    "devops"
   ],
-  "author": "DevOps-Monk",
-  "license": "MIT"
+  "author": {
+    "name": "DevOps-Monk",
+    "url": "https://devops-monk.com"
+  },
+  "license": "MIT",
+  "homepage": "https://github.com/devops-monk/claude-link#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/devops-monk/claude-link.git"
+  },
+  "bugs": {
+    "url": "https://github.com/devops-monk/claude-link/issues"
+  }
 }

package/bridge.js

@@ -1,92 +0,0 @@
-#!/usr/bin/env node
-// ClaudeLink bridge — run once: node bridge/bridge.js
-// Connects Claude Code CLI to the browser extension via WebSocket.
-
-import { WebSocketServer } from 'ws';
-import { spawn } from 'child_process';
-import { writeFileSync, unlinkSync } from 'fs';
-import { tmpdir } from 'os';
-import { join } from 'path';
-
-const PORT = process.env.CLAUDELINK_PORT ? parseInt(process.env.CLAUDELINK_PORT) : 9999;
-const ALLOWED_ORIGIN = 'chrome-extension://';
-
-const wss = new WebSocketServer({ port: PORT });
-
-console.log(`\n⚡ ClaudeLink bridge running on ws://localhost:${PORT}`);
-console.log(`   Waiting for extension to connect…\n`);
-
-wss.on('connection', (ws, req) => {
-  const origin = req.headers['origin'] ?? '';
-  if (!origin.startsWith(ALLOWED_ORIGIN)) {
-    ws.close(1008, 'Forbidden');
-    return;
-  }
-
-  console.log(`[+] Extension connected`);
-
-  ws.on('message', async (raw) => {
-    let msg;
-    try { msg = JSON.parse(raw.toString()); }
-    catch { ws.send(JSON.stringify({ type: 'error', text: 'Invalid JSON' })); return; }
-
-    if (msg.type === 'ping') {
-      ws.send(JSON.stringify({ type: 'pong' }));
-      return;
-    }
-
-    if (msg.type === 'prompt') {
-      console.log(`[>] Prompt: ${String(msg.prompt).slice(0, 80)}…`);
-      runClaude(['--print', msg.prompt], ws);
-      return;
-    }
-
-    if (msg.type === 'file-prompt') {
-      const tmpFile = join(tmpdir(), `claudelink-${Date.now()}.md`);
-      writeFileSync(tmpFile, msg.content);
-      console.log(`[>] File prompt: ${tmpFile}`);
-      runClaude(['-p', tmpFile], ws, () => { try { unlinkSync(tmpFile); } catch {} });
-      return;
-    }
-
-    if (msg.type === 'run-script') {
-      const tmpScript = join(tmpdir(), `claudelink-script-${Date.now()}.sh`);
-      writeFileSync(tmpScript, msg.script, { mode: 0o755 });
-      console.log(`[>] Running script: ${tmpScript}`);
-      runScript(tmpScript, ws, () => { try { unlinkSync(tmpScript); } catch {} });
-      return;
-    }
-  });
-
-  ws.on('close', () => console.log(`[-] Extension disconnected`));
-});
-
-function runClaude(args, ws, onClose) {
-  const proc = spawn('claude', args, { env: { ...process.env } });
-  proc.stdout.on('data', (d) => ws.send(JSON.stringify({ type: 'chunk', text: d.toString() })));
-  proc.stderr.on('data', (d) => ws.send(JSON.stringify({ type: 'error', text: d.toString() })));
-  proc.on('close', (code) => {
-    onClose?.();
-    ws.send(JSON.stringify({ type: 'done', exitCode: code }));
-    console.log(`[✓] Done (exit ${code})`);
-  });
-  proc.on('error', (e) => {
-    ws.send(JSON.stringify({ type: 'error', text: `Failed to start claude: ${e.message}\nMake sure Claude Code CLI is installed: npm install -g @anthropic-ai/claude-code` }));
-    ws.send(JSON.stringify({ type: 'done', exitCode: 1 }));
-  });
-}
-
-function runScript(scriptPath, ws, onClose) {
-  const proc = spawn('bash', [scriptPath], { env: { ...process.env } });
-  proc.stdout.on('data', (d) => ws.send(JSON.stringify({ type: 'chunk', text: d.toString() })));
-  proc.stderr.on('data', (d) => ws.send(JSON.stringify({ type: 'error', text: d.toString() })));
-  proc.on('close', (code) => {
-    onClose?.();
-    ws.send(JSON.stringify({ type: 'done', exitCode: code }));
-    console.log(`[✓] Script done (exit ${code})`);
-  });
-  proc.on('error', (e) => {
-    ws.send(JSON.stringify({ type: 'error', text: `Script error: ${e.message}` }));
-    ws.send(JSON.stringify({ type: 'done', exitCode: 1 }));
-  });
-}