ColliePWA

Try it in your browser — no install · colliepwa.dev
_{A real Collie build running in the page against faked data.}

ColliePWA is an open-source (MIT) mobile client for Herdr, with experimental
support for tmux and zellij. It is a
self-hosted web app (PWA) for driving terminal AI agents such as Claude Code, Codex and OpenCode
from your phone. Each instance connects to one multiplexer. It is served over Tailscale by default.
Open the URL on an iPhone or Android phone to see which agent needs input and respond directly from
your mobile keyboard.

Using Herdr? Read about the
Herdr mobile client.

The input box uses a standard text field compatible with system voice dictation. Collie also
includes built-in voice input that remains disabled
until explicitly configured.

Features

• React Router + Vite with TypeScript, Tailwind, shadcn, and a Bun bridge
• Status dashboard led by what needs your input; every other pane sits under its own workspace, tab on the row
• Push notifications when an agent blocks on user input
• Quick actions and slash commands configured per agent
• Keypad for terminal control keys: Esc, Ctrl+C, arrows, and modifier combinations
• Output search and full conversation history beyond standard terminal scrollback
• File attachments: images from the camera roll, and markdown, text and code files
• Device pairing as the write credential: once a device is paired, every write needs its token
• Crews: several machines' Collies behind one URL, with operator-triggered failover
• Six UI languages and a per-device typeface setting
• Herdr session switching managed from the web interface
• PWA support running locally on loopback with no external accounts or cloud dependencies

Demo

Using Collie from a phone: the dashboard places agents that need input at the top. You can inspect
spaces, tabs, and panes. Long-press a pane pill or tab chip to rename or close it; Claude panes
reflect names set via /rename. Hold a dashboard row or a pane pill, or right-click it with a mouse,
to pin that pane to the top of the dashboard and the switcher. Tap to answer an AskUserQuestion
prompt, switch between herds, and receive push notifications when an agent blocks on input.

The interactive demo runs the web client in your browser against mock
data without installation.

Dashboard — every pane stays in its workspace, what needs you is marked in place	Ask — the agent's own prompts become tappable buttons
Space — its tabs and panes, deep-linkable	Keys — the special-keys pad, no chords to remember
Quick — your own one-tap replies, from quick-replies.toml	Settings — appearance, language, typeface, per device

Motivation

I wanted to check on my agents from my phone. The usual route is Termux to SSH
in and attach to the terminal multiplexer session. Driving a TUI through on-screen controls is
clumsy: special keys are fiddly, Ctrl/Esc/arrows require awkward chords, and simple text input
fights the soft keyboard. I wanted a mobile interface instead of a terminal shoehorned onto a
touchscreen. Collie lets you tap the agent that needs input, type normally, and send Esc or
Ctrl+C with one thumb.

Who is this for

Collie is for developers running AI agents in a terminal multiplexer who want to resume sessions
from a phone. Herdr is the primary supported target in 1.0. Support for tmux and zellij is
experimental: both run, but testing is limited to a single operator on one machine. If you use
either, bug reports are welcome, including
reports of working setups.

The setup assumes a Tailscale tailnet. Your phone and host must share a
tailnet, with tailscale serve configured as the default ingress. Collie is single-user: it
supports one operator on one tailnet, with no multi-tenant authentication. Do not use it for shared
or public access. Read the security section below before running it.

Security — read this first

Collie provides remote shell access to your machine by design. A single Collie API call sends
arbitrary keystrokes directly into a live terminal pane. Anyone with access to the URL can read pane
output (source code, secrets, environment variables, agent output) and execute arbitrary commands
with your full user privileges. There is no sandbox and no command allow-list, as these would defeat
the core workflow. Treat the URL as a root login: bind it strictly to your tailnet, set
COLLIE_TRUSTED_USER, and pair only the physical phone you are using. Read
docs/security.md for details on the security model, defense layers, and
device gating before running the service.

🚫 Never tailscale funnel this: funnel exposes the port to the public internet, whereas
serve limits access to your private tailnet. Do not funnel Collie under any circumstances.

Quickstart

New to Tailscale or Herdr? Install in five minutes walks the
whole setup, from an empty computer to Collie on your phone.

Run this on the host, not your phone. It requires curl, tar, and a sha256 utility. It needs no
compiler toolchain and does not ask for sudo:

curl -fsSL https://colliepwa.dev/install.sh | sh

The script downloads the latest release for your platform, verifies the sha256 checksum, installs
the files, and puts collie on your PATH. It then prints the remaining manual steps: seed a config,
then run collie start. You do not need to specify a multiplexer ahead of time. On its first run,
collie start detects Herdr, tmux, and zellij, then prompts for your choice. If you prefer to build
from source, docs/install.md covers manual builds, each system and
package, Herdr routes, and adding Collie to the home screen of an iPhone or Android phone.

ColliePWA is not in the App Store or Google Play. You add it to your home screen from the browser,
and that is the only way to install it on a phone.

Documentation

Guides

Reference

Repository-level specifications live at the root: ARCHITECTURE.md ·
docs/deployment.md · MUX_CONTRACT.md ·
CREW_PROTOCOL.md · HERDR_API.md ·
DESIGN.md · CONTRIBUTING.md.

Deployment variants

Collie always binds loopback only; what changes between deployments is what sits in front
of it and how a request proves who it is. Variant A is the default and sits below; the other four
are in docs/deployment.md. Pick one.

Variant A — tailscale serve + person identity (default)

The happy path from Install. tailscale serve terminates TLS on your MagicDNS name and
injects Tailscale-User-Login; set COLLIE_TRUSTED_USER to your tailnet login and Collie
rejects anyone else.

# in your .env
[email protected]

• Granularity: the tailnet person, not the device.
• Why it's safe on bare tailscale serve: serve is the trusted injector of
  Tailscale-User-Login — it sets that header itself and a client can't forge it through the proxy.
• Nothing else to configure; origins match automatically on the MagicDNS name.
• Want per-device control without standing up a proxy? Pair the
  device — it composes on top of this variant.

This is the right choice unless you specifically need a proxy in the path. If you do, or if Tailscale
isn't in the path at all, docs/deployment.md has the rest:

• B — identity-aware proxy, authorised by device — a proxy on this host; some devices drive, others watch.
• C — reverse proxy as the only front door — no Tailscale anywhere in the path.
• D — off-host identity proxy over the tailnet — one central ingress node fronting Collie among your other services.
• E — any other mesh or tunnel — NetBird, ZeroTier, Cloudflare Tunnel: you own the ingress, Collie publishes nothing.

Windows (experimental)

The bridge runs on Windows against the Herdr Windows beta; the launcher does not. Herdr on
Windows exposes its control socket as a named pipe derived from the full socket path instead of an
AF_UNIX socket. Collie connects via node:net rather than Bun.connect using a single shim,
bridge/dial.ts, which documents the path mapping.

Operational details:

• Run the bridge directly with bun run bridge/index.ts. There is no systemd unit. Herdr action
  buttons invoke bash, requiring Git Bash on PATH. The manifest lists only linux and macos
  support to avoid exposing actions that might fail silently.
• tailscale serve integration is unavailable on Windows. Follow
  Variant C: bind to
  loopback, place your own ingress in front, and set COLLIE_PUBLIC_HOSTS. The rules in
  §Security still apply.
• Set COLLIE_MULTI_SESSION=off, as session discovery relies on POSIX paths.
• The socket path defaults to %APPDATA%\herdr\herdr.sock. Override it with HERDR_SOCKET_PATH.
  Explicit \\.\pipe\… values pass through directly.

Lifecycle management: The bridge added named pipe support in 0.15.0. An unsupported,
community-maintained Task Scheduler configuration for start, stop, and update routines is available
in contrib/windows/.

Verification: The bridge logs [events] stream up on startup. Event streaming runs over the
pipe, providing real-time updates without falling back to polling.

COLLIE_HERDR_DIAL=net forces the node:net dialer on Linux and macOS. This allows testing the
Windows connection path without a Windows environment; bridge/dial.test.ts relies on it.

Architecture

A small Bun process sits between your phone and your multiplexer — the browser never touches the
multiplexer.

  phone (PWA)
     │  HTTPS over the tailnet
     ▼
  tailscale serve        terminates TLS, injects the identity header
     │  127.0.0.1:PORT    (the bridge binds loopback only)
     ▼
  Collie bridge (Bun)    serves the UI + a small JSON API; polls the multiplexer
     │  one mux adapter, chosen per install
     ▼
  the multiplexer        owns the panes, agents and terminal state
  Herdr · tmux · zellij

Under Variant C a
reverse proxy replaces the tailscale serve box; everything below the front door is identical.

• Only the adapter touches the multiplexer (bridge/mux/<name>/ — Herdr dials a Unix socket, tmux and zellij shell out to their CLIs); everything else speaks the bridge's HTTP API. What every adapter must answer is MUX_CONTRACT.md.
• Polling is still the model — the bridge takes one snapshot per tick from the adapter and the browser polls /api/snapshot; where the multiplexer offers an event stream (Herdr does) it only pokes the bridge's poll to go faster, it never replaces it. No resync logic.
• Actions are plain HTTP — a reply or key POSTs to /api/pane/:id/{reply,keys}, and the adapter types it into a real terminal (hence the security posture).
• The UI is a static PWA — Vite builds web/dist, served from disk, so a rebuild is live with no restart.
• A second Collie is a peer, not a second bridge — one machine's bridge mirrors one multiplexer, and a lead reads its peers over the crew link (CREW_PROTOCOL.md).

Full design rationale in ARCHITECTURE.md.

Developing

Clone and build the repository
(Install → the same result, from source), then edit
in place.

• Every verb is implemented once, in cli/, and runs as bin/collie <verb>
  (Commands). No other layer implements verbs. scripts/collie-ctl.sh is a
  bootstrap shim that compiles the binary and passes your argv. The Herdr adapter's
  herdr-plugin.toml is a thin registration file whose [[actions]] call that shim
  (Herdr actions). Both files contain explanatory comments.
• Development loop asymmetry: web/ rebuilds appear immediately without a restart because the
  bridge serves web/dist directly from disk. Changes to bridge/ require
  systemctl --user restart collie. Build, test, and versioning rules live in
  CLAUDE.md. Versioning is enforced by git hooks, so check the document before
  committing.
• Multiplexer adapters: MUX_CONTRACT.md defines the interface an adapter
  must implement, and MUX_CONTRIBUTING.md covers the integration
  boundaries. ARCHITECTURE.md §3 explains why Collie runs as a supervised
  service instead of an embedded pane, which keeps the Herdr manifest limited to [[actions]] and
  [[build]].
• Pull requests: CONTRIBUTING.md documents base branches (main for
  bugfixes, v1 for features), CI checks, and version bump requirements.

The states playground

A development page that renders the web components across mock states (boot, idle, dashboard, crew,
settings) without a running agent. This lets you inspect visual elements like banners, marks, boot
screens, and lock states without manually reproducing each condition. Its browser tab wears a red
icon, so it is never mistaken for a real Collie build.

cd web && COLLIE_DEV_HOSTS=bluefin,localhost bun run playground

Open http://<host>:5199/playground.html. Port 5199 redirects root requests to the playground and
disables /api, preventing requests to a live Collie instance. Vite targets only index.html
during production builds, keeping playground.html and src/playground/ out of dist and the PWA
precache. This exclusion is tested in src/playground/playground-entry.test.ts.

The page is tabbed: one section is shown at a time, picked from a sidebar on wide screens and a top
bar on narrow ones, and only the selected section's components are mounted. The selected tab lives
in the URL hash. #pane opens
the Pane tab, and #pane/<card-handle> also scrolls that card into view once it mounts (the handle
is the card's data-state, e.g. pane-mid-tool-run). With no hash, the last tab you were on is
remembered (localStorage); with neither, the page opens on the first tab.

The tabs, in order: Dashboard, Pane, Crew, Settings, Boot & connection, Idle & resume, Brand,
Notices, Motion. Notices covers everything that ANNOUNCES (the notice primitive, the strip band,
the status toast); Motion covers everything that MOVES without announcing anything (collapse and
swap primitives, loading bars, sheets, menus, pending and pulsing controls).

Within a tab, cards are grouped under a Group — a small heading over its own .pg-grid — ordered
from the everyday state to the rare one, so a tab with a dozen cards can be skimmed by its group
titles instead of scrolled blind.

To add a state, add a <Card> to the relevant Group in the relevant file under
src/playground/sections/ and the corresponding mock data in src/playground/fixtures.ts. To add
a whole new section, add a file there exporting DEF (a SectionDef) and a <Something>Section
component wrapping its cards in one or more Groups, then add one line to the SECTIONS registry
in src/playground/app.tsx.

For Herdr adapter development, refer to upstream documentation for the plugin system:
authoring ·
CLI reference ·
example plugins. Collie's socket
integration is documented in HERDR_API.md.

See also

• All how-to pages: docs/
• Deployment variants B through E: docs/deployment.md
• Architecture and design rationale: ARCHITECTURE.md
• Multiplexer query interface and capabilities: MUX_CONTRACT.md
• Lead-to-peer crew protocol: CREW_PROTOCOL.md (topology diagram in
  §2)
• Crew recovery from a phone after lead failure:
  docs/deployment.md → the standby door
• Verified Herdr socket API: HERDR_API.md
• Operations, versioning, and project conventions: CLAUDE.md
• Contribution guidelines: CONTRIBUTING.md
• Names, logo and forks: TRADEMARKS.md
• Release history: CHANGELOG.md