wolfpack-bridge

Wolfpack

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

Mobile & desktop command center for AI coding agents. Control tmux-based sessions (Claude, Codex, Gemini, or any custom command) across multiple machines from your phone or browser. 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

Architecture

┌─────────────┐      ┌───────────┐      ┌──────────────────────────────────┐
│   Phone /   │      │ Tailscale │      │          Your Machine            │
│   Browser   │◄────►│  (HTTPS)  │◄────►│                                  │
│   (PWA)     │      │  mesh VPN │      │  ┌──────────┐ ┌──────┐ ┌─────┐  │
└─────────────┘      └───────────┘      │  │ wolfpack │ │ tmux │ │Agent│  │
                                        │  │  server  │◄│      │◄│(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, proxies tmux via capture-pane/send-keys
• 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

• tmux
• Tailscale — install from tailscale.com/download, sign in, and make sure both your computer and phone are on the same tailnet

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)
• 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 tmux agent sessions
• 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

• Capture-pane polling — real-time terminal view optimized for mobile
• Swipe gestures — swipe between sessions and views
• Haptic feedback — vibration on key actions
• PWA — install as a standalone app on your phone's home screen

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.

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,
  "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