Installation Guide

Get Codebridge running on your machine in under 3 minutes.

Prerequisites

Claude Code CLI

The AI engine. Install via npm:

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

Anthropic API Key

For Claude. Get one at console.anthropic.com:

export ANTHROPIC_API_KEY=sk-ant-...

You also need a WhatsApp account and a license key (free Starter tier available).

Install

Option 1: One-line installer (recommended)

Works on macOS, Linux, and WSL. Detects your OS and architecture automatically.

Terminal

curl -fsSL https://codebridge.huntco.fr/install.sh | sh

Installs to ~/.local/bin/codebridge · Creates ~/.codebridge/config.json

Option 2: Manual download

Download the binary for your platform from GitHub Releases:

Platform	Binary
macOS Apple Silicon (M1/M2/M3/M4)	`codebridge-darwin-arm64`
macOS Intel	`codebridge-darwin-amd64`
Linux x64	`codebridge-linux-amd64`
Linux ARM64 (Raspberry Pi, etc.)	`codebridge-linux-arm64`
Windows x64	`codebridge-windows-amd64.exe`

Terminal

chmod +x codebridge-darwin-arm64
mv codebridge-darwin-arm64 ~/.local/bin/codebridge
mkdir -p ~/.codebridge

Configure

Edit ~/.codebridge/config.json (created by the installer):

~/.codebridge/config.json

{
  "license_key": "CB-XXXXXXXX-XXXXXXXX",
  "port": 8042,
  "whatsapp": {
    "connector": "whatsmeow",
    "allowed_numbers": ["+33612345678"]
  },
  "repos": [
    {
      "name": "my-project",
      "path": "/Users/you/code/my-project",
      "mode": "plan-only"
    }
  ],
  "claude": {}
}

Key fields

license_key — Your license key from codebridge.huntco.fr
allowed_numbers — Your phone number with country code (e.g. +33...). Only these numbers can send commands.
repos[].path — Absolute path to the repo on your machine
repos[].mode — Security level: plan-only (read-only), confirm (supervised edits), auto (full autonomy)
port — Dashboard port (default 8042). Override with PORT env var.

You can also configure everything from the built-in dashboard (Settings page) after launching.

Launch

Terminal

codebridge

The gateway starts and displays a QR code in the terminal. Open http://localhost:8042 for the web dashboard.

Pair WhatsApp

Open WhatsApp on your phone
Go to Settings > Linked Devices > Link a Device
Scan the QR code (terminal or dashboard)
Send help in your “Note to Self” chat

That's it. Claude Code is now accessible from WhatsApp.

WhatsApp Commands

Command	Description
`help`	Show available commands
`status`	Connection status, tier, active repo
`switch to <repo>`	Switch active repository
`new session [name]`	Start a new Claude session
`resume <name>`	Resume a named session
`sessions`	List sessions for current repo
`history [N]`	Show last N messages
`archive session`	Archive current session
`anything else`	Send as prompt to Claude Code

Running in Background

After initial QR pairing, you can run Codebridge as a background service.

Option 1: nohup (simplest)

Terminal

# Start in background
nohup codebridge > ~/.codebridge/codebridge.log 2>&1 &

# View logs
tail -f ~/.codebridge/codebridge.log

# Stop
pkill codebridge

Option 2: macOS (launchd) — auto-start on login

Create ~/Library/LaunchAgents/com.codebridge.plist:

com.codebridge.plist

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.codebridge</string>
    <key>ProgramArguments</key>
    <array>
        <string>/Users/YOU/.local/bin/codebridge</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
    <key>StandardOutPath</key>
    <string>/Users/YOU/.codebridge/codebridge.log</string>
    <key>StandardErrorPath</key>
    <string>/Users/YOU/.codebridge/codebridge.log</string>
    <key>EnvironmentVariables</key>
    <dict>
        <key>ANTHROPIC_API_KEY</key>
        <string>sk-ant-...</string>
    </dict>
</dict>
</plist>

Terminal

# Replace /Users/YOU with your home directory
launchctl load ~/Library/LaunchAgents/com.codebridge.plist

# Stop
launchctl unload ~/Library/LaunchAgents/com.codebridge.plist

Option 3: Linux (systemd)

Create ~/.config/systemd/user/codebridge.service:

codebridge.service

[Unit]
Description=Codebridge Gateway
After=network.target

[Service]
ExecStart=%h/.local/bin/codebridge
Restart=on-failure
Environment=ANTHROPIC_API_KEY=sk-ant-...

[Install]
WantedBy=default.target

Terminal

systemctl --user daemon-reload
systemctl --user enable --now codebridge

# View logs
journalctl --user -u codebridge -f

License Tiers

Starter

Free

1 repo, read-only mode
20 messages/day
1 session
24h message history

Pro

9€one-time

10 repos, all modes
Unlimited messages
5 concurrent sessions
Unlimited history
Media support, live feed

Compare all features →

Troubleshooting

"command not found: codebridge"

Add ~/.local/bin to your PATH:
export PATH="$HOME/.local/bin:$PATH"

"command not found: claude"

Install Claude Code CLI:
npm install -g @anthropic-ai/claude-code

QR code not showing

Make sure port 8042 is not already in use (or whatever port you configured). Check terminal output for errors.

WhatsApp disconnected

WhatsApp disconnects linked devices after 14 days of inactivity. Re-pair via the dashboard QR code.

License validation failed

The gateway falls back to Starter tier offline. Check your internet. License is cached 24h.

Claude not responding

Verify your ANTHROPIC_API_KEY is valid:
claude --version

Ready to code from your phone?

Get Started Free GitHub