Herdr Projects
github.com/eliasstravik/herdr-projects- Category
- AI Agents
- Rank
- No. 1055Tools index
- Pricing
- Open Source
- Type
- TOOL
- Use case
- Agent Building
- Interfaces
- Agent Skill / Plugin
- Builder
- @eliasstravik
- GitHub
- 1.1k stars
- Latest release
- v2.1.0
- Date
About
Herdr Projects is a plugin for the Herdr agent tool that lets one coordinator conversation start a separate agent for each task in a larger project, each on its own branch with the same instructions and shared memory. It shows which task threads are ready for review, waiting on the user, or still working, so the coordinator stays free to respond while the work runs in parallel. It runs locally on macOS and Linux with no hosted service, requiring Herdr 0.9.1 or later.
What it does
Shepherdr, the current name of this repository, is a self-hosted web app that acts as a remote control for Claude Code and Codex running on herdr-core, a local agent runtime. Each project folder gets a coordinator chat: you describe the work in plain words, it writes task briefs, and every task gets its own git worktree, branch and agent. A fresh reviewer agent checks each task before it merges. The server listens only on your own machine and you reach it from a phone, tablet or desktop over Tailscale, so questions and permission requests arrive as tappable cards and push alerts.
Why it's ranked here
Free, MIT licensed, and aimed at a real bottleneck: keeping many parallel coding agents moving without watching a wall of terminals. The safety choices are specific. No agent writes in your checkout, a merge only fast-forwards main, a task with uncommitted or unmerged work keeps its worktree, and an optional Linux Autopilot mode runs agents inside bubblewrap namespaces with an HTTPS host allowlist and a hard traffic cap. The project is also unusually plain about maturity: its own getting-started page says the 2.1 rewrite is not an approved production release, and testing against a real external machine is recorded as unverified rather than passed.
What's good
Everything you see is a plugin, including chat, tasks, terminal and voice, and your own plugins live outside the repository, so updates never overwrite them. A plugin that fails to build is set aside with its error while the rest keeps running. Secrets are handled by name: an agent asks for one through a masked input card, and a helper injects the value into a single child process with output masking. The app never updates itself, so a merge to its own main cannot change what is running. Data stays on your machine apart from your agent CLI's usual service, browser push and optional ElevenLabs voice.
Tradeoffs
The requirement list is long: macOS or Linux, herdr-core, Bun, Git, Tailscale and a signed-in Claude Code or Codex, plus optional GitHub CLI, Chrome and ElevenLabs. Version 2.1 is a standalone app beside herdr-core rather than a plugin for terminal Herdr, so older descriptions of it as a Herdr plugin are out of date, and 2.0 plugins break until migrated. Agents start with your own CLI permission settings, and the docs state that briefs and reviews are guidance, not a sandbox. Plugins run unsandboxed with the server's full account access. Autopilot is refused on macOS and remote machines. Tasks merge automatically by default once review and quick checks pass.
How to use it well
It suits a developer already running Claude Code or Codex across several repositories who wants to hand off work and answer questions from a phone. Install herdr-core and Bun, clone the repository, run bun install with the frozen lockfile flag and bun run build, then shepherdr start. Share it with tailscale serve on port 7787 under the /shepherdr path; shepherdr status prints the private link. Before the first real task, set Merge to ask me first in Settings, because automatic merging is the default. Skip it if you need agents to keep working with every machine of yours switched off, which its own comparison table says it cannot do.
Technical notes+
server/app.ts serves the API and websockets with Bun.serve on 127.0.0.1 only, rejects cross-site /api requests through a sameSite check, and closes any websocket whose send buffer passes 1 MiB so the client reconnects for a fresh snapshot. server/main.ts starts only a fictional demo world when SHEPHERDR_SOURCE is demo and otherwise throws, directing users to the core launcher. plugins.json lists fourteen base plugins; plugins/terminal/server.ts and plugins/worktree/server.ts are one-line definePlugin declarations, the worktree one described as read only. docs/plugins.md requires user plugins to carry a manifest declaring api 2, caps plugin method input at 64 KiB and results at 1 MiB, and gives setup a five-second deadline. docs/secrets.md describes a fresh 256-bit AES-GCM mailbox capability per launch, with reviewers given no secret access. docs/autopilot.md lists PID, mount, user and network namespaces, a CONNECT gateway limited to exact public HTTPS hosts, and a shared traffic allowance in MiB. package.json pins React 19, xterm, web-push and agent-browser.
Observed
- License
- MIT (LICENSE)
- Language and runtime
- TypeScript on Bun, React front end built with Vite (package.json)
- Interfaces
- Web app for phone, tablet and desktop, plus a shepherdr CLI (start, stop, status)
- Platform support
- macOS and Linux; Autopilot requires a local Linux repository space with bubblewrap
- Agent CLIs
- Claude Code and Codex, installed and signed in on each machine
- Network exposure
- Server binds 127.0.0.1 and is shared privately through tailscale serve (server/app.ts)
- Hosting
- Self-hosted; no hosted Shepherdr service
- Plugin isolation
- Plugins are trusted local code, not sandboxed (docs/plugins.md)
- Dependency
- Requires herdr-core; version 2.1 is a standalone app, not a terminal Herdr plugin (docs/get-started.md)
Read from README.md, package.json, LICENSE, docs/get-started.md, docs/plugins.md, docs/secrets.md, docs/machines.md, docs/autopilot.md, server/main.ts, server/app.ts, plugins.json, plugins/terminal/server.ts, plugins/worktree/server.ts.
Tags
Tech Stack
Comments (0)
No comments yet
Editorially curated, with community endorsements as a secondary signal. Corrections welcome.