paddock

demo · install · running locally · docs

---

watch and answer your coding agents from your phone.

You have several agents running in herdr panes. You step away from the desk. One finishes, another hits a permission prompt, and both sit there waiting — because the only way to find out is to walk back and look.

• triage — grouped into needs you, working, idle, not alphabetically
• read — full ANSI colour; prose reflows to the screen, tables keep their columns
• answer — the agent's own option labels, and what Enter will commit before you tap it
• notify — a Telegram message when an agent needs you, sent only once the state has held, with mute and a per-agent cooldown. settings →
• install as an app — Add to Home Screen gives it an icon and no browser chrome
• cheap to watch — adaptive polling, and only changed lines on the wire

try the live demo → — synthetic agents, no install, best in mobile mode.

---

install

curl -fsSL https://lntvan166.github.io/paddock/install.sh | sh

Installs to ~/.local/bin/paddock, no sudo, checksum verified before anything is written · read it first · binaries

herdr version

paddock talks to herdr over herdr's own socket protocol. This release is built against protocol 20, which herdr 0.8.2 speaks. install.sh checks after installing, and you can ask again whenever:

paddock doctor

The check is directional. A herdr newer than this paddock is accepted and runs — paddock verifies the fields it actually reads rather than demanding an exact version number, so a herdr release that adds things breaks nothing. A herdr older than protocol 20 is refused, because paddock would be reading fields that herdr does not send yet.

So if herdr is older, upgrade herdr and restart its daemon: the socket answers from the running daemon, not from the binary on disk, so upgrading alone keeps reporting the old protocol.

then start it where herdr is running:

paddock

ctrl+c stops it. To keep it running after you close the terminal:

paddock start     # detached
paddock status    # is it up?
paddock stop

To reach it from your phone without configuring anything first:

paddock tunnel

That publishes a temporary public URL gated by a one-time pairing code, and prints both. It is a try-it path, not a deployment — see from your phone for what it does and does not protect, and for the durable setup.

paddock update upgrades it; paddock never updates itself unasked. paddock --demo runs it with synthetic agents and no herdr.

It checks for a newer release at most once a day, caching the answer in ~/.config/paddock/update-check.json — set PADDOCK_NO_UPDATE_CHECK=1 and it makes no request and writes nothing. A running paddock re-reads that answer hourly, so an instance left up for a week still notices; the once-a-day limit is on the request, not on the noticing. When there is something newer, the terminal says so and the dashboard shows a dismissable banner.

Warning

paddock has no login of its own. Anyone who reaches its port can send keystrokes to your agents, answer their prompts, and read their screens. Never port-forward it or bind 0.0.0.0.

from your phone

paddock stays on 127.0.0.1. Put an authenticating tunnel in front — a Cloudflare Tunnel with Zero Trust Access dials out, so no inbound port is opened and the identity check happens before any request reaches paddock.

paddock tunnel, from the install steps above, is the shortcut: a temporary Cloudflare quick tunnel gated by a one-time pairing code. It is a try-it path, not a deployment — a quick tunnel cannot have Cloudflare Access in front of it, so that code is the only gate there is, and the URL is public until you close it. --for 2h bounds how long it lives.

Then Share → Add to Home Screen, and it is an app: its own icon, no browser chrome, and it opens where you left off.

running locally →

docs

running locally · settings · cloudflare tunnel · architecture · gotchas · decisions · roadmap

gotchas.md is the one worth reading first if you are building anything against herdr — it records what its API actually does, measured rather than assumed.

development

bun install
make dev     # vite HMR + server reload
make test    # builds the UI first, then runs the suite

make check is tsc --noEmit; make check-clean scans for anything that should not be in a public repo. contributing →

contributing

Issues and pull requests welcome — especially multi-host (several machines in one list, the biggest gap left), a linter, and more component tests. roadmap → · house rules →

thanks

The idea comes from herdr-remote by dcolinmorgan: pushing herdr agent status to a phone for monitoring and one-tap approval.

paddock reuses that concept and none of its implementation. herdr-remote is AGPL-3.0-or-later; paddock is MIT. No code, markup or styling has been copied between them, and the two solve the problem differently — herdr-remote relays through a Python service, paddock speaks herdr's socket protocol directly.

license

MIT — see LICENSE.