claudelink-bridge

Bridge your browser to Claude Code CLI.

The local server for the ClaudeLink Chrome extension. Send screenshots, selected text, page content, and custom commands from any webpage directly to your local Claude Code — without leaving the browser.

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.

Quick start

Step 1 — Install Claude Code CLI (if you haven't already)

npm install -g @anthropic-ai/claude-code
claude   # log in

Step 2 — Install the bridge as a background service

npx claudelink-bridge setup

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, 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+
• Claude Code CLI — npm install -g @anthropic-ai/claude-code

Auto-start setup by platform

Running npx claudelink-bridge setup does everything automatically. Here's what happens on each platform and how to verify it worked.

macOS

setup creates a launchd plist and loads it immediately. The bridge will start automatically every time you log in.

npx claudelink-bridge setup

Verify it's running:

npx claudelink-bridge status
# or check directly:
launchctl list | grep claudelink

View logs:

tail -f ~/.claudelink/bridge.log

If it stops unexpectedly:

launchctl unload ~/Library/LaunchAgents/com.devops-monk.claudelink.plist
launchctl load  ~/Library/LaunchAgents/com.devops-monk.claudelink.plist

Config file location: ~/Library/LaunchAgents/com.devops-monk.claudelink.plist

Linux

setup creates a systemd user service and enables it so it starts on login. No root/sudo required.

npx claudelink-bridge setup

Verify it's running:

npx claudelink-bridge status
# or check directly:
systemctl --user status claudelink

View live logs:

journalctl --user -u claudelink -f

If it stops unexpectedly:

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:

loginctl enable-linger $USER

Config file location: ~/.config/systemd/user/claudelink.service

Windows

setup creates a Task Scheduler entry that runs the bridge at login. Run this in PowerShell (no admin required):

npx claudelink-bridge setup

Verify it's running:

npx claudelink-bridge status
# or check directly in Task Scheduler:
schtasks /Query /TN ClaudeLinkBridge

View logs:

Get-Content "$env:USERPROFILE\.claudelink\bridge.log" -Wait

If it stops unexpectedly:

schtasks /Run /TN ClaudeLinkBridge

Manually open Task Scheduler to verify: press Win+R → type taskschd.msc → look for ClaudeLinkBridge in the task list.

Config: Task Scheduler entry named ClaudeLinkBridge, visible in Task Scheduler Library.

Configuration

Custom port (default: 9999):

CLAUDELINK_PORT=9998 npx claudelink-bridge setup

Then update the port in the extension popup → Settings → Bridge port.

Logs (macOS/Linux):

tail -f ~/.claudelink/bridge.log        # live output
cat ~/.claudelink/bridge-error.log      # errors

Troubleshooting

Red dot / "Disconnected" in extension

npx claudelink-bridge status
npx claudelink-bridge start

Port already in use

npx claudelink-bridge kill
npx claudelink-bridge start

"Failed to start claude" — Claude Code CLI not found or not logged in:

npm install -g @anthropic-ai/claude-code
claude

Bridge stopped after system update

npx claudelink-bridge setup   # re-registers the service

Security

• 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

Changelog

0.1.3

• Expanded platform setup docs with per-platform verify, log, and restart steps

0.1.2

• Added full README with quick-start, commands, platform setup, troubleshooting, and security sections
• Added repository, homepage, bugs metadata to package
• Added files whitelist — cleaner published package

0.1.1

• Initial README added

0.1.0

• Initial release
• WebSocket bridge server on localhost:9999
• Streams Claude Code CLI responses token by token
• Auto-start service installer for macOS (launchd), Linux (systemd), Windows (Task Scheduler)
• setup, start, stop, status, kill, uninstall commands
• Handles screenshots as base64 inline images for Claude
• 50MB max payload for large screenshots

Links

• ClaudeLink Chrome Extension
• Claude Code CLI docs
• Report an issue
• DevOps-Monk

MIT © DevOps-Monk