Claude Code Bridge (pandapaw)

Connect to Claude Code through PandaNpc — two connection modes for different scenarios.

What is pandapaw? pandapaw is the unified PandaNpc CLI (one binary, ~4 MB) that ships three components:

pandapaw cc-bridge — the Claude Code remote bridge (this page)

pandapaw codex-bridge — the OpenAI Codex bridge

pandapaw watch — bidirectional file watcher that syncs .claude/ ↔ .agents/ rules / skills / memories

One install gets you all three. It replaces the old standalone cc-bridge (last released as v1.1.0 in April 2026) — same protocol, same Bridge ID format, fully wire-compatible with PandaNpcApp.

Connection Modes

Mode	Scenario	Port Required
Relay (recommended)	Claude runs on another machine, connect via relay	No
Local	Claude runs on this machine	No

Relay Mode (Recommended)

Best for: Your Claude runs on a home PC / server, and you want to access it from anywhere — phone, laptop, office — without opening any ports.

Your PC (pandapaw cc-bridge)  ──outbound WSS──▶  Relay Server  ◀──outbound WSS──  PandaNpcApp
                                                 cc.pandanpc.com
Both sides connect OUT. Zero ports opened. Works behind any firewall/NAT.

Step 1: Install pandapaw on your server

macOS (Apple Silicon & Intel — universal binary)

curl -fsSL https://cos.pandanpc.com/pandapaw/install.sh | sh

The script downloads pandapaw-macos-universal (~6.6 MB) into ~/.local/bin/, then runs pandapaw install which:

Writes a launchd User Agent to ~/Library/LaunchAgents/com.pandanpc.pandapaw.watcher.plist
Runs launchctl load -w to start it immediately + restart automatically on every login
Starts the file watcher daemon
Prints the install summary with Bridge ID + Token

No sudo required.

Linux (musl static binary, runs on any glibc / Alpine / etc.)

curl -fsSL https://cos.pandanpc.com/pandapaw/install.sh | sh

The script downloads pandapaw-linux-x86_64 (~4.4 MB), then pandapaw install registers a systemd user service:

~/.config/systemd/user/pandapaw-watcher.service  (Type=simple, Restart=on-failure)

If you want the watcher to keep running across SSH sessions (headless server), enable user lingering once:

sudo loginctl enable-linger $USER

Windows (PowerShell)

iwr -useb https://cos.pandanpc.com/pandapaw/install.ps1 | iex

The script downloads pandapaw-windows-x86_64.exe (~3.5 MB) into %LOCALAPPDATA%\Programs\pandapaw\, then pandapaw install registers a Task Scheduler task:

PandapawWatcher  /SC ONLOGON  /RL LIMITED   (no admin / UAC required)

The task runs as the logged-in user, starts immediately, and re-runs on every login.

Step 2: Verify install

After any of the three installers finishes, check the status:

pandapaw status

Expected output:

pandapaw v0.1.0
features: cc-bridge, codex-bridge, sync, install

Components:
  watcher        running   pid=...
  cc-bridge      on-demand (called by cc-relay per session)
  codex-bridge   on-demand (called by cc CLI per session)

Autostart: enabled
Binary:    ~/.local/bin/pandapaw
Logs:      ~/.pandapaw/logs

Step 3: Get your Bridge ID + Token

The cc-bridge component is on-demand — it auto-starts when PandaNpcApp connects. Your Bridge ID and Token are stored at:

macOS / Linux: ~/.pandanpc/cc-bridge/.env
Windows:       %USERPROFILE%\.pandanpc\cc-bridge\.env

Open this file and copy:

CC_BRIDGE_ID=bridge-a1b2c3d4
CC_TOKEN=77a1449c3119aa87e16b95b13c40d03f...

Step 4: Connect from PandaNpcApp

Open PandaNpc → Claude Code page
Click New Connection
Select Relay mode
Fill in:
- Bridge ID: from .env above
- Token: from .env above
- Working Directory: the remote directory for Claude to work in
Click Create & Connect

Session Continuity

pandapaw cc-bridge is designed to survive unstable networks without losing your conversation.

On WebSocket reconnect (e.g. after Wi-Fi hiccup, sleep/wake, or CDN proxy timeout):

Within 5 minutes (grace period): PandaNpcApp auto-resubscribes and reattaches to the live Claude process — zero context lost. Any output Claude produced during the disconnect is replayed from the bridge's message buffer.
After 5 minutes: Claude is relaunched with --resume, loading the full conversation history from disk JSONL files.

No manual action needed. On each reconnect PandaNpcApp runs session.check_alive against all previously-opened sessions and sends session.resume automatically for the ones still alive. The UI keeps showing your tab; messages update in place as history replays.

Process Supervision

The Linux systemd user unit and macOS launchd plist both have automatic restart on failure (5-second backoff). The Windows Task Scheduler task is set to restart on logon. The bridge itself also has an internal reconnect loop (5-second retry) for cases where the process stays up but its WebSocket to the relay drops.

Local Mode

Best for: Running Claude directly on the machine where PandaNpcApp is installed. Simplest setup, zero network.

Prerequisites

Install Claude Code CLI:

claude --version

Usage

Open PandaNpc → Claude Code page
Click New Connection
Select Local mode
Working Directory: click "Browse" to select a folder
Click Create & Connect

PandaNpc spawns Claude as a local subprocess. No network, no ports, no bridge needed. (Local mode does not use pandapaw — it goes directly through PandaNpcApp.)

Security

Relay mode

Layer	Purpose
Bearer Token	Only those with the token can connect to your bridge
HMAC-SHA256 signing	Every client request is signed with a compiled-in app secret — only genuine PandaNpcApp builds can reach your bridge
TLS (WSS)	All traffic encrypted between bridge ↔ relay ↔ app
Session isolation	Each bridge has a unique ID, sessions cannot cross bridges

Who can't connect?

Scenario	Result
No token	❌ Rejected
Wrong Bridge ID	❌ Bridge not found
Wrong token	❌ Unauthorized
Non-PandaNpcApp client (missing HMAC signature)	❌ Rejected
PandaNpcApp + correct Bridge ID + Token	✅ Connected

Token Management

Lost? Re-run the install script — it reuses the existing token from ~/.pandanpc/cc-bridge/.env
Compromised? Stop the watcher → delete .env → re-run install script to rotate
Rotation? Recommended every 90 days

Service Management

pandapaw exposes a unified set of commands across all three platforms:

pandapaw status            # show binary path + watcher PID + autostart state
pandapaw watch start       # start watcher daemon
pandapaw watch stop        # stop watcher daemon
pandapaw watch restart     # stop then start
pandapaw watch status      # is the watcher daemon running?
pandapaw uninstall         # full reverse install (stop daemon + remove autostart + delete binary)

Platform-specific service inspection

If you need to inspect the OS service layer directly:

macOS

launchctl list | grep com.pandanpc.pandapaw.watcher
launchctl unload ~/Library/LaunchAgents/com.pandanpc.pandapaw.watcher.plist  # stop
launchctl load   ~/Library/LaunchAgents/com.pandanpc.pandapaw.watcher.plist  # start

Linux

systemctl --user status   pandapaw-watcher
systemctl --user restart  pandapaw-watcher
systemctl --user stop     pandapaw-watcher

Tip: For headless servers without active login sessions: sudo loginctl enable-linger $USER

Windows

schtasks /Query /TN PandapawWatcher
schtasks /Run   /TN PandapawWatcher
schtasks /End   /TN PandapawWatcher

Update

To update to the latest pandapaw version, just re-run the install script — it will overwrite the existing binary and restart the daemon:

# macOS / Linux
curl -fsSL https://cos.pandanpc.com/pandapaw/install.sh | sh

# Windows
iwr -useb https://cos.pandanpc.com/pandapaw/install.ps1 | iex

Existing config (~/.pandanpc/cc-bridge/.env) and Bridge ID + Token are preserved.

Uninstall

pandapaw uninstall

This stops the watcher, removes autostart registration, and deletes the binary. Your data (config, logs, Bridge IDs) is preserved at ~/.pandapaw/ — remove manually if you want a clean slate:

# macOS / Linux
rm -rf ~/.pandapaw ~/.pandanpc/cc-bridge

# Windows
Remove-Item -Recurse $env:USERPROFILE\.pandapaw, $env:USERPROFILE\.pandanpc\cc-bridge

Troubleshooting

"Bridge not online"

Check if cc-bridge is running:

ps -ef | grep 'pandapaw cc-bridge'         # macOS / Linux
Get-Process | ? Name -eq pandapaw          # Windows

If not running, look at the bridge log:

# macOS / Linux
tail -f ~/.pandapaw/logs/cc-bridge-*.log

# Windows
Get-Content $env:USERPROFILE\.pandapaw\logs\cc-bridge-*.log -Tail 20

Look for Registered as bridge: <your-id>. If missing, the relay connection failed (network/firewall blocking outbound WSS to cc.pandanpc.com).

Connection drops frequently

Check network stability between pandapaw and relay server
pandapaw cc-bridge automatically reconnects every 5 seconds on disconnect
PandaNpcApp auto-reconnects up to 15 times with 3-second intervals
If you're behind an aggressive CDN / proxy, the WebSocket may be cut every few minutes — the automatic resume flow (see Session Continuity above) still preserves your conversation

Session appears frozen after reconnect

This used to happen when the client's tab showed "connected" but the underlying session hadn't resubscribed. Recent PandaNpcApp versions (v0.6.27+) detect this case automatically: on any reconnect, every live session is re-resumed and message history is replayed in place. No tab click is required.

If you still see a stuck tab, click Connect on the connection once — that re-runs the full check-alive + resume flow.

Service won't start

Common causes:

Claude CLI not in PATH → set CLAUDE_BIN=/full/path/to/claude in ~/.pandanpc/cc-bridge/.env
Relay server unreachable → check network / firewall for outbound WSS to cc.pandanpc.com
(Linux) user session not lingering → sudo loginctl enable-linger $USER

Wrong token

Verify the token in PandaNpc matches CC_TOKEN in ~/.pandanpc/cc-bridge/.env.

Migrating from old standalone cc-bridge

If you previously installed the old cc-bridge (pre-v0.1.0 pandapaw):

The new pandapaw installer overwrites it cleanly — your existing ~/.pandanpc/cc-bridge/.env (Bridge ID + Token) is reused, so no need to update PandaNpcApp connection settings
Old cc-bridge service / autostart entries should be removed manually:
- macOS: launchctl unload ~/Library/LaunchAgents/com.pandanpc.cc-bridge.plist && rm ~/Library/LaunchAgents/com.pandanpc.cc-bridge.plist
- Linux: systemctl --user disable --now cc-bridge && rm ~/.config/systemd/user/cc-bridge.service
- Windows: Unregister-ScheduledTask PandaNpc-cc-bridge -Confirm:$false