Manage hundreds of coding agents across your machines from your phone, tablet or desktop, without the cognitive overload

Shepherdr is mission control for herdr: one private app on your tailnet with your spaces in a sidebar, each with its own coordinator. You tell a space's coordinator what needs doing and it turns it into tasks. Every task runs as an ordinary herdr agent in its own git worktree, gets reviewed by fresh eyes before it merges, and asks you on a card when it needs a decision. The tasks list shows which need you, which are ready and which are still working.

_{✓ Free, MIT licensed   ✓ Runs on your machines, private on your tailnet   ✓ macOS and Linux, herdr 0.9+}

/`. Write one yourself or ask an agent to build it. Add a feature to any of the screen's slots (a bar at the top, a menu item, a side panel tab, a settings page, a key), change or replace any built-in plugin's screen parts by giving yours its name (copy it there and edit it; the server's own behaviour stays), and switch any plugin off in Settings → Plugins. A theme of your own works the same way: Shepherdr's colours are CSS variables that a plugin can set. Updates never touch that folder, so you keep every new release without a fork: save a file and Shepherdr rebuilds and restarts in seconds, and a plugin that breaks is set aside with its error while the rest runs. [Plugins](docs/plugins.md) has a hello world and every slot. ### ⚡ Stop briefing every agent yourself Write what needs doing to a space's coordinator: it makes it a task or several, each with a brief and a Settings block that says how it is reviewed and merged. Each agent starts on Claude Code, Codex, pi or another CLI herdr can start, in a worktree of its own, at once or as soon as the machine has room. Want more control? Ask for it "for later", "after SHE-12", or "ask me before merging". Turn on [Autopilot](docs/autopilot.md) and the coordinator works on its own between your messages, or add [automations](docs/autopilot.md) that start tasks on a schedule. ### 💬 Know when a task needs an answer An agent that asks you something, wants a permission or a plan approved shows under `Needs you`, and its question comes as a card you answer with a tap, from the chat or straight from an [alert](docs/get-started.md#install-it-as-an-app-with-alerts) on your lock screen. Each task's chat also shows its live terminal, files, diff, pull request and a [shared browser](docs/browser.md) you can take over. Reports and draft screens come as [artifacts](docs/artifacts.md) you mark up beside the chat, and you can call a coordinator by [voice](docs/get-started.md#voice). ## Open Shepherdr in three steps

1️⃣ Install the plugin Run herdr plugin install eliasstravik/shepherdr. herdr builds it and starts it at every herdr start; it gets its own Bun if you have none.

2️⃣ Share it on your tailnet Run the plugin action "Share Shepherdr on my tailnet". It serves the app privately with tailscale serve, never public, and prints its link.

3️⃣ Write to a coordinator Open the link on your phone and add it to the home screen, then turn alerts on in Settings. Pick a space and say what needs doing. ? on a keyboard shows everything else.

## Get everything included, free

For developers who run coding agents in herdr on macOS or Linux Free    ✓  A coordinator for every space that turns what you write into tasks    ✓  Every task on its own worktree and branch, with its own agent    ✓  A review by fresh eyes before it merges, through a pull request on GitHub    ✓  Cards, alerts and voice calls on your phone, tablet or desktop    ✓  Every machine you saved in herdr, from one app    ✓  Your own plugins and themes, kept through every update    ✓  Autopilot, automations, artifacts, a shared browser and split view

## Updating ```bash herdr plugin update herdr-projects # its plugin id, from the plugin it replaced ``` The next herdr start, or the next press of the open key, swaps the running Shepherdr for the new version. A linked checkout updates itself: when it moves to a new commit, Shepherdr builds a release of it and restarts on it, and every open screen reloads with what you were typing kept. Coming from herdr-projects, the same command takes you there. [Upgrading and updates](docs/upgrading.md) has the details. ## Get your questions answered ### Do I need to know how to code? You need to be comfortable in a terminal for the install. After that everything happens in the app: you write to coordinators and answer cards, and Settings holds the few defaults. You'll need macOS or Linux, herdr 0.9 or newer, Git, Tailscale to reach it from your other devices, and an agent CLI herdr can start: Claude Code, Codex, pi or another. Bun comes by itself. `gh` (pull requests), Chrome for the shared browser and an ElevenLabs key for voice are optional. [Get started](docs/get-started.md) covers the prerequisites. ### How do I check that Shepherdr is running? The plugin action "Open Shepherdr" starts it when it is not running and shows its link. To check every machine, run on the main one: ```bash shepherdr doctor ``` It checks every machine saved in herdr, puts Shepherdr's helper there again, starts its worker again and says what is missing. Settings → Machines says how each one is, and each machine's home space shows its load, memory and disk. [Other machines](docs/machines.md) has the details. ### What permissions do the agents get? **Codex starts with full access** (`--dangerously-bypass-approvals-and-sandbox`), so a task never waits on a prompt nobody sees. Claude Code and pi start with your own permission settings; Shepherdr adds only its hooks, from a settings file of its own, and yours are never touched. A permission prompt shows the task under `Needs you` (`Asks permission`), and startup trust and MCP prompts come as cards. The brief's rules and the review are guidance, not a sandbox. [Tasks](docs/tasks.md) has the details. ### Does the plugin send my work to a hosted service? No. Shepherdr runs on your own machine, keeps its files there, talks to your local herdr, and reaches your other machines over herdr's remote and your own SSH. The app is shared only on your tailnet. Your agent CLI still uses its own service as usual, alerts go through your browser's push service, and voice calls go through ElevenLabs if you set them up. ### Will it touch my branches or worktrees on its own? Only the ones it made. Every task works in its own worktree, on its own branch `work/-`, never in your checkout; a merge only moves your main forward (fast-forward, or a squash merge when there's no GitHub remote). By default a task merges on its own once its review is done and its quick checks pass; set Settings → How tasks work → Merge to "ask me first", or say so for one task. On GitHub it merges through the task's pull request. When a task is done its worktree and branch are removed; one with uncommitted or unmerged work stays, and Shepherdr says so. ### Where do my tasks live? In `~/.shepherdr/` on the main machine (`SHEPHERDR_HOME` to move it): your spaces, tasks, chats, artifacts, settings, Autopilot checklists and your own plugins. Other machines get only a small helper folder. [Develop](docs/develop.md) and [Plugins](docs/plugins.md) cover the code and how to change Shepherdr's screen for yourself. ### Can I use several machines? Yes. Shepherdr is installed once, on the main machine. Every other machine you save in herdr's remote (`herdr machine add `) shows up in the sidebar on its own, with its spaces, tasks and coordinators, and needs nothing installed by hand. [Other machines](docs/machines.md) has the details. ### Do I have to start every task through a coordinator? Mostly. The app has no new-task button: you ask a space's coordinator in your own words and it adds the task (`shepherdr task add`), so every one gets a brief and the same rules. An [automation](docs/autopilot.md) adds tasks on a schedule or when something happens, such as a merge. ### What if the safety settings aren't enough? They are soft. A task's review, merge and rules are lines in its brief, and its agent follows them. Codex runs with full access and every agent has a shell: one can do anything you can, a review is another agent's judgement and not a proof, and Autopilot and automations run with nobody watching. Set Merge to "ask me first" for a yes before anything lands, and keep Autopilot off where you want to decide every step. ### What does it cost? Shepherdr is free and [MIT licensed](LICENSE). Your agent CLI's usual usage charges still apply: every task is a full agent session plus a review, each coordinator spends tokens on each message and on Autopilot's heartbeat, and voice calls use your ElevenLabs account. ## Open Shepherdr in three steps

Shepherdr starts with an install, one link, and one sentence to a coordinator about what needs doing. It starts the agents, follows their work and brings what needs you to your phone. You choose what to answer and what to merge.

_{✓ Free, MIT licensed   ✓ Runs on your machines, private on your tailnet   ✓ macOS and Linux, herdr 0.9+}