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 small binary) that ships everything you need to use Claude Code remotely:

pandapaw cc-bridge — Claude Code remote bridge, headless mode (API-key / custom-base billing)

pandapaw cc-tty — Claude Code remote bridge, interactive mode (uses your Claude subscription: Pro / Max)

pandapaw codex-bridge — the OpenAI Codex bridge

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

One install gets you everything. pandapaw install registers all three background services (watcher + cc-bridge + cc-tty) as always-on autostart daemons, auto-detects whether your Claude uses an API key (→ headless) or a subscription (→ interactive), generates your credentials, and prints a QR code so you can connect from the PandaNpc iOS app in one scan — no copying Bridge IDs or tokens by hand.

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, signed & notarized)

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

On macOS the script installs a signed & notarized PandaPaw.app into ~/Applications/ (so it shows up in System Settings → Login Items as "PandaPaw" with the panda icon, and runs without Gatekeeper warnings), symlinks the pandapaw CLI into ~/.local/bin/, then runs pandapaw install which:

Registers three launchd User Agents (watcher, cc-bridge, cc-tty) under ~/Library/LaunchAgents/com.pandanpc.pandapaw.*.plist, each set to KeepAlive (auto-restart) and start on every login
Generates your Bridge ID + Token and saves them to the config
Prints a QR code — scan it with the PandaNpc iOS app to connect instantly

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 into ~/.local/bin/, then pandapaw install registers three systemd user services and prints a QR code:

~/.config/systemd/user/pandapaw-watcher.service   (Restart=always)
~/.config/systemd/user/pandapaw-ccbridge.service  (Restart=always)
~/.config/systemd/user/pandapaw-cctty.service     (Restart=always)

If you want the services 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 into %LOCALAPPDATA%\Programs\pandapaw\, then pandapaw install registers three Task Scheduler tasks (no admin / UAC required) and prints a QR code:

PandaPaw-watcher   /SC ONLOGON  /RL LIMITED
PandaPaw-ccbridge  /SC ONLOGON  /RL LIMITED
PandaPaw-cctty     /SC ONLOGON  /RL LIMITED

The tasks run as the logged-in user, start immediately, and re-run on every login.

Step 2: Verify install

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

pandapaw status

Expected output (all three services running):

pandapaw v0.1.x
features: cc-bridge, cc-tty, codex-bridge, sync, install

Components:
  watcher        running   pid=...
  cc-bridge      running   pid=...
  cc-tty         running   pid=...

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

Step 3: Connect — scan the QR code (recommended)

pandapaw install prints a QR code at the end. To show it again anytime:

pandapaw qr

  🐼  PandaPaw · scan to connect

  ███▀▀▀█▀█▀▀▀███   ← (a styled QR code with the panda logo)
  ...

Then on the PandaNpc iOS app:

Open the Agent tab
Tap the scan icon (top-right viewfinder)
Point the camera at the QR code on your server's screen

That's it — the connection is created automatically. No Bridge ID or token to copy.

Security: the QR encodes a one-time pairing code that expires in 2 minutes, not your real token. Even if the QR image leaks (screenshot / photo), it's useless after 2 minutes. Just re-run pandapaw qr for a fresh code.

Step 3 (alternative): Manual connect with Bridge ID + Token

For the desktop app (no camera), or if you prefer manual setup, copy your credentials from the config:

macOS / Linux: ~/.pandapaw/config.toml   (the [relay] section)

[relay]
bridge_id = "bridge-yourhost-a1b2c3"
token     = "77a1449c3119aa87e16b95b13c40d03f..."
relay_url = "wss://cc.pandanpc.com"

Then in PandaNpc → Claude Code → New Connection → Relay mode, fill in the Bridge ID, Token, and a Working Directory, and 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 ~/.pandapaw/config.toml
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 all three services + autostart state
pandapaw qr                # show the QR code to connect from the iOS app
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 all daemons + 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 (~/.pandapaw/config.toml) 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

# Windows
Remove-Item -Recurse $env:USERPROFILE\.pandapaw

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 → pass --claude-bin /full/path/to/claude, or set CLAUDE_BIN in the service environment
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 the token in the [relay] section of ~/.pandapaw/config.toml.

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 ~/.pandapaw/config.toml (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