TeleFlock

Your agents, herded.

TeleFlock is a native desktop and phone app for the omp coding agents you run inside herdr. Every agent lands on one live board: you see what each one is doing right now, answer its questions and approvals with one tap, dispatch new tasks into fresh worktrees, review and ship the diff, and drop into a real terminal whenever you need it. It connects over Tailscale SSH, to herdr on this machine, or inside WSL. Your sessions keep running in herdr as they always did; TeleFlock is the window onto them.

Download: Windows · Android · Linux .deb / AppImage / Arch · macOS

Contents

Feature tour · Install · Set up a host · How it works · Build from source · Repository · Status · Credits · License

Feature tour

_{All screenshots are from the built-in demo host (?demo), which simulates a flock of agents. Nothing in them is mocked up.}

The board: is everything alive?

Four lanes, Needs you · Running · Review · Done, with every omp agent on every host. Needs you comes first, and its oldest question sits on top, answerable right on the card. Every card has the same layout in every lane: the state and its time on top (turn 27:24, waiting 6:13, finished 25m ago), then who and where, the task, what it is doing right now, and labelled meters (ctx 61%, subs 59%, +188 −74 · 3 files, model, thinking). Running cards keep a live heartbeat with the streaming line, tool timers and tokens per second, and agents that go quiet while working are called out. Above the lanes sit today's spend with the subscription limit you will hit first, every host's health and a live terminal tile. Mark a reviewed card done (with Undo) and its herdr pane closes, worktree workspace included; the card stays in Done with its transcript, and Resume, opening its terminal or simply sending it a message picks the session back up with omp --resume. Drag a card back to reopen it, multi-select, filter, and drive everything from the keyboard (J/K, Enter, A answer, T terminal). When omp's cleanup (or you) deletes an agent's session file, the agent disappears from the board, the inbox and Dispatch.

Easy to start, nothing hidden

New to omp and herdr? The board's First steps checklist walks you through the demo flock (answer a question, approve a command, steer an agent, review, dispatch, the palette) and retires itself. Dotted terms such as pane, steer, follow-up, worktree or compact explain themselves on hover or tap, short hints beside the composer and the phone pager retire after a few sightings, and every launcher and palette action says what it does. Each fact is shown once, in one place, with its unit. Motion is calm by default: only changes and what needs you move, briefly, then the screen holds still; nothing animates while the window is in the background, and Settings → Motion → Lively brings back the full show.

AI naming with omp's tiny model

TeleFlock uses the tiny model role you set up in omp (modelRoles.tiny, falling back to smol) as its AI provider, on the host and through your own omp login. It names Dispatch worktrees and branches, wizard branches and agents, fan-out runs and templates, suggests a name when you rename a session or workspace, and drafts commit messages and pull request titles and descriptions in Review. AI-made names carry a ✨, are always editable, and fall back to names made from your own text when the model is slow or switched off (Settings → AI naming). Nothing is stored: the text goes only to your own model provider, through omp.

Every omp setting, in the app

Everything you can configure in omp is on the omp settings page (Ctrl+8, a host card's ⋯ menu, or Settings → New agents), per host: all of omp's settings under omp's own tabs, groups, labels and descriptions, with search, the right control for each (switches, choices with their explanations, numbers with omp's presets, lists, JSON), a modified dot and reset to default. The model roles editor at the top of the Model tab assigns a model and thinking level to every role (default, smol, slow, plan, tiny, task, advisor, …) and to roles of your own. TeleFlock reads omp's own settings schema from the omp on the host and writes through omp config, so omp validates every change; secrets are write-only.

A native session for every agent

A real GUI for the omp transcript: streaming markdown, rich tool cards (diffs, bash with ANSI colours, search, todos, subagents, web, images) and thinking blocks. Click any image to open it full screen, then zoom and pan (wheel, pinch, double-click) and page through the rest of the message. When the agent asks, its question becomes a card you answer with a click or 1–9, with each option's trade-off written inside its button (Skip answers nothing). Enter sends, or steers the running turn, and Alt+Enter queues a follow-up, with an editable queue, a / palette covering omp's commands and your own, @ file search, and images. Whatever you type, anywhere in the app, stays put: drafts and pasted images survive switching agents, closing dialogs and restarts until you send them. Model, thinking, plan, goal and fast mode sit in the header and say whether they are on. The inspector shows how much context is used and how much of your subscription is left, spend by source, throughput, todos, changed files, the session tree (branch, fork, navigate) and more. A fresh agent offers starter prompts.

Ask cards	Approvals

Dispatch: fire tasks into fresh worktrees

Pick a repository and send tasks like chat messages. omp's tiny model names each one (dispatch/offline-board-cache), and each gets its own worktree and omp agent; they all run side by side. A thread per repo shows every agent's progress live: naming, creating the worktree, starting, then the agent's status and streaming line. You can answer its questions inline and jump to its session, terminal or review. Templates, model, thinking and plan mode are set per message, and you can paste, drop or attach images that go to the agent with its first message. Every worktree forks from a freshly fetched origin/main, not a local main that may be behind. Put hosts in a group (host editor) and pick Auto · : each task goes to the least busy host of the group that has the repository (running agents, tasks on their way, CPU and memory; clones are matched by their origin URL), and its card says where it went and why. Up to three worktrees are created at once; the rest queue. Need a specific branch or several attempts? New worktree and Fan out are one click away, with the repository filled in.

Automations: agents on a schedule

A host can start an omp agent on a schedule: a nightly dependency audit, a weekday standup summary, a weekly flaky-test triage. Each automation has a prompt, a model, thinking level and plan mode, and either a fresh worktree per run (forked from origin/main) or a folder it runs in. Schedules are cron expressions in the host's time zone; the editor has presets and reads the next runs back in plain English. A run whose previous agent is still busy is skipped instead of piling up, and a run missed while the host was off can catch up once. Every run lands in the history with a link to its agent, and your devices get a notification. tf-hostd runs the schedules itself, so no app needs to be connected; on Linux with systemd a timer brings it back after reboots and crashes while an automation is enabled.

Subagents and agent chat

When omp fans out, TeleFlock shows the swarm live: each subagent's own estimate of how far it is (% done), its context meter, tool count and cost. Open any of them in the full-height subagent viewer to read its transcript as it streams, message or steer it, kill it or revive it ([ / ] jump between siblings). When agents talk to each other over omp's IRC, the messages appear as chat bubbles in the transcript, and the Agent chat tab collects every thread.

Agent chat in the transcript	Subagent viewer

Cost, throughput and subscription limits

Every agent's spend counts its subagents and the advisor too, broken down by source in the inspector, alongside a live tokens-per-second meter. The Usage page tracks spend per day, model and agent. Subscriptions & limits reads the quota windows of every account omp is logged into (Claude 5-hour, 7-day, Codex…), with reset countdowns and a pace projection that warns before you hit a limit. The session inspector has a limits tile, and a header chip appears when an account runs low.

Review and ship

A diff viewer (unified or split) for any worktree. From there you commit (✨ let the tiny model draft the message, or ask the agent), push, open a PR (✨ title and description), watch the checks and merge. A ship stepper shows where the worktree stands and its next step, even on a laptop screen, and Review cards on the board show that next step too.

A real terminal when you need it

xterm.js attached to any herdr pane, in Fira Code with Nerd Font icons. Beside it, Running panes lists every pane on the host, shells and agents, grouped by workspace and tab with the program running in each (vim, bun run dev, htop); the sidebar shows shells under their workspace and the palette finds them, and opening one attaches to the existing pane instead of starting a new shell. It supports control or observe mode with take-over, search, tabs, localhost preview tunnels, and an extra-keys row on phones. omp keeps running as its normal TUI inside herdr, so the terminal is always the real thing.

In your pocket

The phone layout is built for one thumb: Flock · Inbox · Dispatch · Terminal · More. Flock home puts what needs you first, with each option's trade-off on the card, tiles that take you somewhere (Answer →, running ↓, today's spend ›) and a ⋯ menu on every row. Sessions swipe between agents, and a Next chip jumps to the next one waiting; the Terminal tab reopens the terminal you used last. Bottom sheets, pull to refresh and haptics come with it.

Notifications that clear themselves

When an agent needs you, you get an OS notification you can act on: a Windows toast with buttons and inline reply, or an Android notification with up to three actions and inline reply. Once a question is handled anywhere (the card, the toast, the board, Ctrl+J "answer next", another device or the omp TUI itself), its notification disappears everywhere. Read ones are retracted too. The Inbox holds what needs you first, then unread updates (finished, errors, quiet agents); the bell is a quick peek at the same list. Desktop also has a tray icon with a live badge, a taskbar overlay on Windows, and per-agent mute and quiet hours. Linux and macOS have no OS notifications yet; there the inbox and the tray badge carry the same information.

Updates

The app finds new versions on GitHub releases by itself: shortly after launch, about every hour while it keeps running, and when you come back to it after 20 minutes or more. On Android, an update found in the background asks to install the next time you open the app.

Platform	How it updates
Windows	Downloads the signed installer, installs it with a progress window (no prompts) and relaunches
Linux AppImage / .deb	Downloads the signed package, replaces the AppImage or installs the .deb (password prompt), restarts
Android	Downloads the APK, checks its checksum and signing certificate, then Android asks you to confirm
macOS	Tells you a new version is out and opens the download (the CI-built app is not signed for auto-install)
Arch	Through pacman / the AUR, like any other package

Desktop packages are verified against the release signing key and the release version before anything is installed. Turn automatic updates off in Settings → Updates.

And more

Command palette (Ctrl+K) with a one-line description for every action, an activity feed with a "while you were away" digest, a usage dashboard, agent templates, fan-out (N approaches in parallel), worktree and agent wizards with a remote folder browser, past sessions and resume, offline-first cached state, and the built-in demo host.

Install

Grab the files from the latest release. Every package has a .sha256 next to it.

Platform	File	Notes
Windows 10/11 (x64)	TeleFlock_<version>_x64-setup.exe	Per-user install, no admin. Needs WebView2, which Windows 11 includes.
Android 7+	TeleFlock_<version>_universal.apk	Allow installs from this source. Grant notifications on first launch; for background alerts, allow the battery-optimisation exemption in Settings. Updates need the "install unknown apps" permission once.
Debian / Ubuntu (x64)	TeleFlock_<version>_amd64.deb	sudo apt install ./TeleFlock_<version>_amd64.deb. Debian 12+, Ubuntu 22.04+.
Any Linux (x64)	TeleFlock_<version>_amd64.AppImage	chmod +x and run. Registers teleflock:// links on first launch.
Arch Linux (x64)	teleflock-bin-<version>-1-x86_64.pkg.tar.zst	sudo pacman -U teleflock-bin-…pkg.tar.zst. The PKGBUILD is in packaging/arch/.
macOS 11+ (Apple silicon + Intel)	TeleFlock_<version>_universal.dmg	Not notarized (no paid Apple account), so see below.

macOS first launch (Gatekeeper)

The app is ad-hoc signed but not notarized, so macOS blocks it the first time:

1. Drag TeleFlock to Applications and open it once. macOS says it can't be verified.
2. Open System Settings → Privacy & Security, scroll down and click Open Anyway (on macOS 14 and older you can instead right-click the app → Open).

Or, in Terminal: xattr -dr com.apple.quarantine /Applications/TeleFlock.app.

iOS is not offered. Without the paid Apple Developer Program, an app can only be sideloaded with a 7-day signature, and iOS would also suspend the live host connection in the background.

Set up a host

On the machine that runs herdr and omp:

1. Tailscale SSH (remote hosts):

   • Run sudo tailscale set --ssh.
   • Make sure your tailnet policy lets your devices SSH to this host as your user.
   • If the policy uses check mode, TeleFlock shows an Open browser card to finish the login.

2. herdr and omp must be installed (herdr --version, omp --version; omp ≥ 18.12). From then on the host keeps them current: tf-hostd checks for new releases every 6 hours and installs them (omp update, plain herdr update, never a live server handoff, so running agents keep running). The host card shows both versions with Check now / Update now and a switch to turn it off.

3. In TeleFlock: Add host (first launch, or the + next to HOSTS in the sidebar) → Tailscale SSH (MagicDNS name or 100.x IP, user), Local, or WSL (pick a distro) → Test → Add host. The dialog lists what the host needs, and a failed test shows the command that fixes it. TeleFlock deploys tf-hostd to ~/.teleflock/ and connects.

4. Host setup (on the Hosts page, which opens it by itself while items are open; the board shows a Fix… strip too) offers one-tap fixes, each explained by what goes wrong without it. Each runs only when you tick its consent box:

   • herdr's omp integration (install-herdr-integration): accurate working/blocked/idle states.
   • Share sessions with TeleFlock (enable-global-sharing): sets collab.autoStart: control and collab.relayUrl: ws://127.0.0.1:47466 in omp's global config. Every omp session, including ones you start by hand or herdr restores, then appears live in TeleFlock.
   • TeleFlock bridge for every session (install-global-bridge): copies the TeleFlock extension into ~/.omp/agent/extensions/ so precise controls work for every session.
   • herdr outside login sessions (move-herdr-out-of-login-session, Linux with systemd, root): appears when the running herdr server still lives in the login session that started it. systemd kills everything in a login session's scope when logind tears the session down (on logout with KillUserProcesses=yes, or when a restarted logind cleans up sessions that already ended), and every agent goes with it. The fix moves herdr and all its processes into a scope of their own; nothing is stopped or restarted. Non-root users see what to do instead (loginctl enable-linger).

   You can skip all of them. Agents started from TeleFlock are shared and bridged per process anyway, an unshared session can be connected with one click (Connect injects /collab into it), and on Linux with systemd the herdr servers TeleFlock starts get their own scope from the start.

5. AI naming needs nothing extra: it uses omp's tiny model role (or smol) on the host. Check it with omp config get modelRoles.

Phones connect over Tailscale SSH only. Your tailnet identity is the login, so no keys or passwords are stored. Desktops can also use Local (herdr on this machine) and, on Windows, WSL.

How it works

flowchart LR
  subgraph devices["Your devices"]
    desk["TeleFlock desktop<br/>Windows · Linux · macOS"]
    phone["TeleFlock phone<br/>Android"]
  end
  subgraph host["herdr host"]
    hostd["tf-hostd<br/>(deployed by the app)"]
    omp["omp TUIs in herdr panes"]
    herdr[("herdr server")]
    gh["GitHub (git · gh)"]
    tiny["omp one-shot<br/>(tiny model role)"]
  end
  desk -- "Tailscale SSH · Local · WSL" --> hostd
  phone -- "Tailscale SSH" --> hostd
  omp -- "collab guest (loopback relay)" --> hostd
  omp -. "teleflock-bridge extension" .-> hostd
  hostd <-- "local API" --> herdr
  hostd --> gh
  hostd -- "naming and drafts" --> tiny

Loading

• omp keeps running as its normal TUI inside herdr, so herdr's state tracking and the real terminal keep working.
• The app's Rust core uploads and starts a small host daemon, tf-hostd, over SSH (or locally), and speaks one protocol to it whatever the transport.
• All your devices share that daemon. When they run different app versions, the host keeps the newest tf-hostd and older apps attach to it instead of replacing it, so one device never knocks the other off.
• On Linux with systemd, tf-hostd and any herdr server it starts run in transient scopes of their own (root: the system manager; other users: their user manager when lingering is on), so the SSH login that started them can end, or be cleaned up, without taking the agents down.
• tf-hostd joins each omp session as a private collab guest on a loopback relay. Room keys never leave the host.
• A companion omp extension adds structured controls (model, thinking, tree, queue, …).
• herdr is driven through its local API; git and gh run on the host for review and shipping.
• AI naming runs omp --mode json once per request on the host with the tiny role (no tools, no session), reads the answer and stops the process.
• tf-hostd also runs the host's automations and keeps omp and herdr up to date; on Linux with systemd a timer restarts it after a reboot while an automation is enabled.
• omp settings come from omp's own schema (read once per omp build by a throwaway headless omp with the TeleFlock extension) and are written through omp config set.
• The UI is React, rendered by the system webview through Tauri 2. Desktop and Android share all of it.

Details: docs/architecture.md · spec: docs/spec.md · feature coverage: docs/coverage.md · bridge protocol: docs/bridge-protocol.md.

Build from source

Toolchain, CI, signing and every command are in docs/build.md.

bun install
bun run dev                  # UI with the demo host: http://127.0.0.1:1420/?demo
cargo test --workspace && bun test && bun run typecheck
scripts/build-windows.sh     # → dist-release/TeleFlock_<v>_x64-setup.exe (cross-compiled, NSIS)
scripts/build-android.sh     # → dist-release/TeleFlock_<v>_universal.apk (signed)
scripts/build-linux.sh       # → dist-release/ .deb + AppImage + Arch package (docker)

macOS is built on GitHub's macOS runners (.github/workflows/macos.yml). Releases come from scripts/release.sh.

To run the real stack in a browser against a herdr session on this machine, start the dev server below. It prints a tokened URL; open that.

cargo run -p tf-devserver -- --static dist --bind 127.0.0.1:7420 --hostd-bin target/<dir>/debug/tf-hostd

Repository

Path	What
crates/tf-proto	Wire protocol, the single source of truth (TypeScript generated into src/core/gen by scripts/gen-proto-ts.sh)
crates/tf-hostd	Host daemon: collab relay and guests, herdr client, state, ops, bridge server
crates/tf-collab · crates/tf-herdr	omp collab protocol (relay, guest, replica) · herdr API client
crates/tf-transport · crates/tf-client	Tailscale SSH / Local / WSL transports · the app's core engine
crates/tf-devserver	Browser bridge to the app core (token-protected)
src-tauri/	Tauri 2 shell: tray, toasts, Snap Layouts, deep links, self-update; Android Kotlin plugin (keep-alive service, notifications)
host/teleflock-bridge/	omp companion extension
src/	React UI: core (transports, stores, demo host), design (Bento design system), features/*
packaging/	Linux release build container, Arch PKGBUILD
scripts/	Build, version and release scripts
docs/	Architecture, spec, coverage, build, research (herdr / omp / collab maps with captured samples)

Status

What has been verified, and how:

• Test suites: the Rust workspace tests, the frontend unit tests and the typecheck.
• Real omp + herdr, on Linux: the full stack was exercised end to end through the UI in herdr lab sessions, via tf-devserver with the local transport, including subscription limits against real Claude and Codex accounts. AI naming (ai.complete) was run against omp 18.12.3's real tiny model role (an answer in about 4 s).
• 0.4.0 interface: the changed screens were walked in the demo at 1440×900, 1280×720 and on a Pixel 5 profile, and the whole change went through a code review.
• 0.4.1 fixes: each was reproduced first and re-checked after the fix: the collab join of resumed sessions against a live omp 18.12.3 room (joined in about 1 s instead of timing out every 30 s), queued steers, omp's own /btw with follow-ups, kept image originals and the observed terminal size in herdr lab sessions, the systemd scopes and the herdr move on a throwaway process tree, and the update schedule in unit tests plus a live run against GitHub. The Android lifecycle hook for updates was compiled only in the release build.
• 0.5.0: the Rust and frontend suites, plus lab runs against real omp 18.12.3 and herdr 0.9.0: Mark done closing the pane, the parked card, Resume, a prompt resuming a parked agent, a daemon restart and pruning after the session file was deleted; a Dispatch task whose image reached omp with its first prompt (the agent answered "Red") in a worktree forked from the fetched origin/main with no upstream; all 559 omp settings read from omp's schema and a set/reset round trip in a temporary agent dir; scheduled, catch-up and skipped automation runs and the systemd timer on a lab home; the omp/herdr updater against fake binaries; every pane of a lab herdr session listed with its program. Rendering was measured in headless Chromium and in WebKitGTK at 2× scale: on an idle board the GPU process went from 97% to 3% CPU and compositor layers from 75 to 17, and WebKitGTK's web process from 584% to 114%. The new screens were walked in the demo at 1440×900 and 412×892, and the whole change went through a code review.
• Packages: the Windows installer, the signed APK and the Linux .deb, AppImage and Arch package build from this tree. The Linux app was smoke-run: the window renders, the tray starts, a second launch hands its teleflock:// link to the first, and the .deb installs and runs on a clean Ubuntu 22.04.

Not yet exercised:

• on real Windows, Android or macOS hardware (macOS is built only in CI);
• on a real Linux desktop session (tray rendering, the update password prompt, a fractional-scale monitor) and real WebView2 GPU usage;
• against a real remote Tailscale SSH peer (the SSH path is covered by an in-process server that imitates Tailscale);
• WSL mode.

Smoke-test those on your devices first, and please report what you find.

Credits

• Tauri (MIT / Apache-2.0) for the app shell, its plugins (updater, deep link, single instance, log) and tauri-plugin-snap-layout.
• xterm.js (MIT) for the terminal.
• Fira Code by The Fira Code Project Authors, SIL Open Font License 1.1.
• Nerd Fonts Symbols Only v3.5.1 by Ryan L McIntyre, MIT; the bundled icon sets keep their own licenses, listed in its README.
• React, Radix UI, Tailwind CSS, Lucide, Motion, zustand, russh, tokio and the rest of the dependency tree in package.json and Cargo.lock.
• omp and herdr, which do the actual herding of agents.

License

MIT © 2026 Studio Plascode