Claude Code Bridge

Connect Claude Desktop, Claude Code CLI, and Chrome Extension into a unified agentic workflow.

The Claude Code Bridge is an MCP (Model Context Protocol) server that enables communication between Claude Desktop (Windows/Mac), Claude Code CLI (WSL/Linux/Mac), and the Claude Chrome Extension. It provides 7 tools for task delegation, inter-agent messaging, system management, and skill discovery.

                    Windows / Mac Host
  ┌──────────────────────────────────────────────┐
  │         Claude Desktop App                    │
  │    (claude_desktop_config.json)               │
  └──────────────┬───────────────────────────────┘
                 │ MCP Protocol (stdio)
                 │ wsl.exe -e bash start.sh
  ───────────────┼───────────────────────────────────
                 ▼
              WSL2 / Linux / Mac
  ┌──────────────────────────────────────────────┐
  │   bridge/server.js (stdio MCP)               │
  │   bridge/server-http.js (HTTP/SSE MCP)       │
  └──────┬────────────────────┬──────────────────┘
         │                    │
         ▼                    ▼
  ┌──────────────┐   ┌──────────────────────┐
  │  claude CLI  │   │  agent-comms/        │
  │  (headless)  │   │  - messages/         │
  └──────────────┘   │  - tasks/            │
                     └──────────────────────┘
         │
  ┌──────────────────────────────────────────────┐
  │   Chrome Extension (port 3899)               │
  │   - Streamable HTTP (/mcp)                   │
  │   - Legacy SSE (/sse + /messages)            │
  │   - Health (/health)                         │
  └──────────────────────────────────────────────┘

Features

• 7 MCP Tools: Task delegation, agent messaging, command execution, file reading, system status, skills inventory
• Dual Transport: stdio for Claude Desktop + HTTP/SSE for Chrome Extension
• Agent Message Board: Async JSON message passing between any Claude instance
• Ralph Autonomous Loop: Run Claude Code in a continuous development loop until task completion
• Custom Skills System: Extend Claude with markdown-based skill definitions
• Hooks System: Auto-sync memory to Weaviate RAG, session indexing, autonomous loop control
• Security: Command blocking, path sanitization, timeouts, buffer limits

Quick Start

Prerequisites

• Claude Code CLI installed (npm install -g @anthropic-ai/claude-code)
• Node.js 18+
• Claude Desktop (for stdio bridge) and/or Chrome Extension (for HTTP bridge)

1. Install the Bridge

git clone https://github.com/YOUR_USER/claude-code-bridge.git
cd claude-code-bridge/bridge
npm install

2. Configure Claude Desktop (stdio)

Edit your Claude Desktop config:

Windows: %APPDATA%\Claude\claude_desktop_config.json Mac: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "claude-code-bridge": {
      "command": "wsl.exe",
      "args": ["-e", "bash", "/path/to/claude-code-bridge/bridge/start.sh"]
    }
  }
}

Mac/Linux (no WSL needed):

{
  "mcpServers": {
    "claude-code-bridge": {
      "command": "node",
      "args": ["/path/to/claude-code-bridge/bridge/server.js"]
    }
  }
}

Restart Claude Desktop.

3. Start HTTP Server (Chrome Extension)

# Foreground
bash bridge/start-http.sh

# Or as daemon
bash bridge/start-http-daemon.sh

Then configure the Chrome Extension MCP to connect to http://localhost:3899/sse (legacy) or http://localhost:3899/mcp (Streamable HTTP).

4. Test

From Claude Desktop, try:

Use the system_status tool to check WSL status

From Chrome Extension, check health:

curl http://localhost:3899/health

Tools Reference

Tool	Description
claude_code_task	Send a task to Claude Code CLI (headless mode). Supports workdir and max_turns.
agent_post	Post a message to the shared agent message board.
agent_read	Read recent messages with filtering by type and time.
wsl_command	Execute a shell command (with security blocks).
wsl_read_file	Read a file (with sensitive path blocking).
system_status	Check memory, Docker, disk, and service status.
list_installed_skills	Inventory of all installed skills, commands, agents, and plugins.

Project Structure

claude-code-bridge/
├── bridge/                     # Core MCP servers
│   ├── server.js               # stdio transport (Claude Desktop)
│   ├── server-http.js          # HTTP/SSE transport (Chrome Extension)
│   ├── package.json
│   ├── start.sh                # Launcher for stdio
│   ├── start-http.sh           # Launcher for HTTP
│   └── start-http-daemon.sh    # Background daemon launcher
├── skills/                     # Custom skill system
│   ├── README.md               # How to create skills
│   └── examples/               # Example skill definitions
│       ├── qa-webapp.md
│       └── sandbox.md
├── hooks/                      # Claude Code hooks
│   ├── README.md               # How hooks work
│   └── examples/
│       ├── sync-memory-to-weaviate.py
│       ├── session-end-hook.sh
│       └── ralph-stop-hook.sh
├── ralph/                      # Autonomous dev loop
│   ├── ralph                   # CLI controller
│   └── PROMPT.template.md      # Task prompt template
├── config/                     # Configuration templates
│   └── examples/
│       ├── claude-desktop-config.json
│       ├── settings.json
│       └── mcp.json
├── docs/                       # Documentation
│   ├── SETUP.md                # Full setup guide
│   ├── TOOLS.md                # Tool reference
│   └── ARCHITECTURE.md         # Architecture deep dive
└── README.md

175 Skills + 42 Commands Included

This repo ships with 175 open-source skills and 42 commands from the community:

Collection	Count	Description
Toolkit Skills (tk-*)	35	Expert knowledge: React, TypeScript, Docker, K8s, Security, etc.
Agile Skills (ln-*)	98	Full Agile SDLC: planning, execution, QA, auditing, bootstrap
Toolkit Commands (tk-*)	42	Git workflows, architecture, testing, security, DevOps
Example Skills	2	QA testing + Sandbox exploration

# Install all at once
bash install-skills.sh

# Or selectively
bash install-skills.sh --toolkit
bash install-skills.sh --agile
bash install-skills.sh --commands

See the full Skills Catalog for descriptions of every skill.

Create your own skills

Skills are markdown files in ~/.claude/skills/. See skills/README.md.

# My Skill Name

## Trigger
- /my-skill

## Instructions
You are a specialist in [domain]. When triggered...

Ralph - Autonomous Dev Loop

Ralph enables Claude Code to work autonomously in a loop until a task is complete:

# Activate Ralph mode
./ralph/ralph start

# Run with a prompt
./ralph/ralph run "Fix all TypeScript errors in src/"

# Check status
./ralph/ralph status

# Stop manually
./ralph/ralph stop

See ralph/README.md for details.

Hooks

Hooks are scripts that run in response to Claude Code events:

Hook	Trigger	Purpose
sync-memory-to-weaviate.py	PostToolUse (Write/Edit)	Auto-sync memory files to Weaviate RAG
session-end-hook.sh	Stop	Index session data
ralph-stop-hook.sh	Stop	Control autonomous loop continuation

Configure in ~/.claude/settings.json. See hooks/README.md.

Security

• Blocked commands: rm -rf /, mkfs, dd, fork bombs, shutdown, reboot
• Blocked file paths: .ssh/, shadow, .env, credentials, secrets
• Timeouts: Commands 120s max, Claude tasks 5min max
• Buffer limits: 5MB max output
• CORS: Enabled for Chrome Extension on HTTP server

Customization

Add your own tools

Edit bridge/server.js or bridge/server-http.js to add custom tools. Follow the existing patterns.

Environment-specific paths

The bridge uses /root/ paths by default. Update these for your environment:

• WORKSPACE in server.js/server-http.js
• Skill paths in list_installed_skills
• Start scripts

Installing on Another PC

For a step-by-step guide to set everything up on a new machine, see docs/INSTALL-ON-ANOTHER-PC.md (in Spanish).

License

MIT

Credits

• Claude Code by Anthropic
• MCP SDK for the protocol layer
• Ralph concept inspired by Geoffrey Huntley's autonomous loop technique