wolfpack-bridge

Wolfpack

        ...:.
           :=+=:
       . .-*####+-
      .- :++**####*=.
       -  :+***#####*=:.
       :   .+**######*+==++++++=:..
       ..   .=*#######*++++====+=--=-.
       .:.-    -+**######**+*#*+=-:-===:
     -.  ..     -++++***#**++*#*--:---===:
     -.:--==+=--=*++*+**********+==------++-
     .:----=++*++##########******+=====--=+#=-.
       .::-----=+*#%%%%%%#***###*+===--==+*=++=:.
         ...::::-=+*#%%############*+-----===+****+=:.
          :--=-====+******++****##***-.::--++*######**
         .++-+++++***********#*+*#***=.:---=+**=--=+==
         -**++*++****+***##*++*****++=. ----=+=.  ..:-
        .+##***+*+*****##*#=-=**=-=-::. -**-::-==+++++
        :*%%*+=+=+****##**++****+**+-.. -*=-   .::::-=
        .-#%#*+*+**#***+++**+****+*++=--+=::-:..:...-+
         =###***=*+++++-=*=+++++-====-=:-=--:=---==---
        .:-+***+=*+++**+++===*++++=--:=  ::=::-=----++
          .+****+++++*##+***++=+*-.:--:..-===---=-:-++
          .-+###**+++*#****+=---:--==.--=:==-==:::-=++
            :####*****+++======:.. :...:::---:.=------
            .=###***+++*++++--:.:::.   :-=::.:..-:---:
             :+**++++++*++*+=-:: .. ...... ..   .:..::

Mobile & desktop command center for AI coding agents. Control agent sessions (Claude, Codex, Gemini, or any custom command) across multiple machines from your phone or browser. Two session backends: pty (lightweight, no dependencies) or tmux (persistent, survives restarts). Secured by Tailscale — zero-config encrypted access, no ports to open.

Install on your phone's home screen for a native app experience — scan the QR code after setup and tap "Add to Home Screen".

Desktop

Mobile

Classic                                                     Ghostty (WASM)

Architecture

┌─────────────┐      ┌───────────┐      ┌──────────────────────────────────┐
│   Phone /   │      │ Tailscale │      │          Your Machine            │
│   Browser   │◄────►│  (HTTPS)  │◄────►│                                  │
│   (PWA)     │      │  mesh VPN │      │  ┌──────────┐ ┌──────┐ ┌─────┐  │
└─────────────┘      └───────────┘      │  │ wolfpack │ │pty or│ │Agent│  │
                                        │  │  server  │◄│ tmux │◄│(any)│  │
                                        │  │ HTTP/WS  │ │      │ │     │  │
                                        │  └──────────┘ └──────┘ └─────┘  │
                                        └──────────────────────────────────┘

Components:

• PWA — single-file vanilla JS app (~90KB), no framework. Mobile-optimized touch UI + desktop ANSI terminal
• Server — Bun HTTP + WebSocket. Serves embedded assets, manages sessions via pty (default) or tmux backend
• Ralph — detached subprocess that iterates through a markdown plan file, invoking agents per-task
• Agents — Claude, Codex, Gemini, or any shell command. Agent-agnostic by design

Quick Install

bunx wolfpack-bridge

Or with npx:

npx wolfpack-bridge

Or via shell script (no Node/Bun required):

curl -fsSL https://raw.githubusercontent.com/almogdepaz/wolfpack/main/install.sh | bash

This will download the pre-built binary for your platform, run the setup wizard, and optionally install as a login service.

Supported platforms: macOS (Apple Silicon, Intel), Linux (x64, arm64).

Prerequisites

• Tailscale (optional) — install from tailscale.com/download, sign in, and make sure both your computer and phone are on the same tailnet. Required for remote access.
• tmux (optional) — only needed if you choose the tmux backend. The default pty backend has no external dependencies.

Session Backends

Wolfpack supports two backends for managing terminal sessions. You choose during setup and can switch at runtime from Settings.

	PTY (default)	tmux
Dependencies	None	Requires tmux installed
Session persistence	In-memory — sessions lost on server crash/restart	tmux server is a separate process — sessions survive wolfpack restarts, deploys, and crashes
Terminal streaming	Direct binary WebSocket (/ws/pty) — low latency	Capture-pane polling (/ws/terminal)
Desktop terminal	ghostty-web with full scrollback	ghostty-web with full scrollback
Best for	Quick setup, no-dependency environments	Long-running agent sessions where persistence matters

Why tmux is more robust: tmux runs as an independent server process. Your agent sessions live inside tmux, not inside wolfpack. If wolfpack crashes, gets redeployed, or restarts (e.g. launchctl kickstart), tmux sessions keep running untouched. When wolfpack comes back up, it reconnects to the existing tmux sessions automatically. With the PTY backend, a wolfpack restart kills all running sessions — any in-progress agent work is lost.

Why PTY is the default: zero dependencies, simpler setup, and lower latency terminal streaming. For most users running short agent tasks, the convenience outweighs the persistence tradeoff.

Both backends can run simultaneously — the backend router tracks which backend owns each session. You can have tmux sessions and PTY sessions active at the same time.

tmux History

Wolfpack can only hydrate history that tmux still retains. Desktop terminal sessions prefill the latest 5,000 lines on connect, so if you want deeper scrollback, raise tmux's history limit:

set -g history-limit 50000

Reload tmux or restart your sessions after changing it.

Usage

wolfpack                    # Start the server (runs setup on first launch)
wolfpack setup              # Re-run the setup wizard
wolfpack service install    # Auto-start on login (launchd / systemd)
wolfpack service stop       # Stop the background service
wolfpack service start      # Start the background service
wolfpack service status     # Check if running
wolfpack service uninstall  # Remove the launch agent
wolfpack uninstall          # Remove everything (service, config, global command)

Setup Wizard

On first run, wolfpack walks you through:

• Checking prerequisites (tmux, Tailscale — both optional)
• Choosing a session backend (pty or tmux, default: pty)
• Setting your projects directory (default: ~/Dev)
• Choosing a port (default: 18790)
• Enabling Tailscale HTTPS access
• Optionally installing as a login service
• Displaying a QR code to scan with your phone

Features

Session Management

• Create, view, and kill agent sessions (pty or tmux backend)
• Agent picker — Claude, Codex, Gemini, or custom commands per session
• Session triage — running, idle, and needs-input states with color-coded indicators
• Live terminal output preview on session cards

Desktop

• Multi-terminal grid — view 2-6 sessions side-by-side in a CSS grid layout. Click + on any sidebar card to add it to the grid, × to remove. Focused cell highlighted with green glow.
• Collapsible sidebar — pin or auto-hide. Shows all sessions across machines with status badges, output preview, and grid/kill buttons.
• xterm.js PTY — full terminal emulator with direct PTY connection (not capture-pane polling)
• Keyboard shortcuts:
  • Cmd/Ctrl + ArrowUp/Down — cycle between sessions
  • Cmd/Ctrl + ArrowLeft/Right — navigate grid cells
  • Cmd/Ctrl + T — new session (project picker)
  • Cmd/Ctrl + K — clear terminal

Mobile

• Two terminal modes — choose in Settings:
  • Classic (default) — lightweight capture-pane polling. No WASM, works on all devices. Best for quick monitoring and input.
  • Ghostty (WASM) — full terminal emulator via ghostty-web. Richer output (colors, cursor, scrollback) but heavier on battery. Keyboard is suppressed by default — tap the keyboard button to open it.
• Keyboard accessory — quick-action bar with Enter, Esc, arrow keys, Ctrl combos, and git status
• Touch scrolling — momentum physics, long-press to select text and copy
• Haptic feedback — vibration on key actions (toggleable)
• PWA — install as a standalone app on your phone's home screen

All settings (terminal mode, font size, haptics, etc.) persist in localStorage across sessions.

Multi-Machine

• One phone connects to multiple Wolfpack servers
• Sessions grouped by machine with online/offline status
• Auto-discover Tailscale peers running Wolfpack
• Cross-machine session management from a single UI

Other

• Notifications — browser notifications + vibration when sessions need attention
• Search — find text in terminal output with match navigation
• Reconnect handling — auto-recovers on connection drop with status indicator
• Auto-resize — terminal resizes to match your screen/grid cell

Remote Access

• Install Tailscale on both your computer and phone
• Sign in to the same Tailscale account on both devices
• Run wolfpack setup and say y to "Enable Tailscale HTTPS access?"
• Scan the QR code with your phone
• Tap "Add to Home Screen" for the native app experience

Tailscale's encrypted mesh network handles auth and routing — no ports to open, no DNS to configure.

Security

Always use the Tailscale hostname (e.g. https://mybox.tail1234.ts.net) — not raw IPs. The QR code from setup already points to the correct URL. Raw IP access (LAN or Tailscale 100.x.x.x) bypasses Tailscale's DNS-based routing and may not be protected by CORS.

JWT authentication adds a second layer of protection. Without it, anyone who can reach the server port has full access to your tmux sessions. To enable:

• Generate a secret (minimum 32 characters):

  openssl rand -base64 48
  

• Set the environment variable before starting wolfpack:

  export WOLFPACK_JWT_SECRET="your-secret-here"
  

  For service installs, add it to your shell profile or the service environment.

• Optional configuration:

  • WOLFPACK_JWT_AUDIENCE — expected aud claim
  • WOLFPACK_JWT_ISSUER — expected iss claim
  • WOLFPACK_JWT_CLOCK_TOLERANCE_SEC — clock skew tolerance (default: 30s)

Tokens use HS256 (HMAC-SHA256). The server validates but does not issue tokens — generate them with any JWT library using the same secret.

Without WOLFPACK_JWT_SECRET set, authentication is disabled. This is fine for localhost-only usage but strongly recommended when the server is reachable over a network.

Ralph Loop

Autonomous task runner. Write a markdown plan file, pick an agent, set iterations, and let it rip. Ralph reads the plan, extracts the first incomplete task, hands it to the agent, marks it done, and moves on — implementing, testing, and committing along the way. See full documentation.

Config

Stored in ~/.wolfpack/config.json:

{
  "devDir": "/Users/you/Dev",
  "port": 18790,
  "backend": "pty",
  "tailscaleHostname": "your-machine.tailnet-name.ts.net"
}

Agent command and settings stored in ~/.wolfpack/bridge-settings.json.

Contributing

Dev Setup

Requires Bun (v1.2+).

git clone https://github.com/almogdepaz/wolfpack.git
cd wolfpack
bun install
bun run scripts/gen-assets.ts   # generate embedded assets (required once)
bun run cli.ts                  # start the server locally

Testing

bun test                             # all tests
bun test tests/unit/                 # unit tests only
bun test tests/unit/plan-parsing.test.ts  # single file

Tests use Bun's built-in runner. Three categories:

• tests/unit/ — plan parsing, ralph log parsing, escaping, validation, grid logic
• tests/snapshot/ — launchd plist and systemd unit generation
• tests/integration/ — API routes, ralph loop endpoints

Asset Pipeline

Frontend files live in public/. The server doesn't serve from disk — everything is embedded:

• Edit files in public/ (HTML, PNG, manifest, etc.)
• Run bun run scripts/gen-assets.ts — embeds them into public-assets.ts (binary→base64, text→string)
• Do NOT edit public-assets.ts manually — it's auto-generated

Building Binaries

bun run scripts/build.ts    # assets + 4 platform binaries in dist/

Compiles for: linux-x64, linux-arm64, darwin-x64, darwin-arm64.

PR Conventions

• Branch off main
• Tests must pass (bun test)
• Keep PRs focused — one feature or fix per PR

Community & Support

• 💬 Open a Discussion — questions, ideas, show & tell
• 🐛 File an Issue — bugs and feature requests
• ⭐ Star the repo if Wolfpack saves you time — it helps others find it

License

MIT