eliasstravik/herdr-projects

Herdr Projects lets you run a larger piece of work in Herdr when one agent isn't enough and managing five by hand is a job in itself. You talk to one coordinator agent. It starts a separate agent for each task on its own branch, gives every one of them the same goal, instructions and memory, and Herdr's own sidebar shows you which threads need you, which are ready for review and which are still working.

_{✓ Free, MIT licensed   ✓ Runs on your machines, no hosted service   ✓ macOS and Linux, Herdr 0.9.1+}

The coordinator never does the work itself, so it's always free to answer you. Each task runs in its own thread: a separate agent in its own git worktree and branch, or in its own folder when there's no repository. You read reports and answer the threads that need you instead of briefing every agent yourself.

Keep your attention on decisions. Herdr Projects starts and tracks the threads, your agents do the work, and you choose what to review, answer, or merge.

Each thread's sidebar row shows its id and title, and a line under it with what Herdr's own state word does not say (review · PR #4, ~40%) and the agent's own activity. Agents and spaces are grouped by project: the project's home space and its coordinator head the group with the project's name in bold, then its threads with what needs you first and its other spaces as Herdr's own rows; everything else comes last. The tab bar says projects: 2 need you. prefix+a opens one popup with threads, tasks, inbox, routines and settings, where every thread's own list of next steps is a number key away.

Say what you want once. The coordinator proposes threads and waits for your go-ahead, then each thread starts from a brief with the project's goal, your standing instructions, the project's memory and its task, on the agent you pick (Claude Code, Codex, OpenCode or any other kind Herdr runs). Lessons a thread reports under ## Remember flow back into memory for the next one.

Agents report their own progress, so a thread that asked you something shows needs you even when it looks idle, and you get a notification that names the project and the thread. A background ticker follows pull requests: failing checks and review comments go back to the thread to fix, and a merged pull request resolves the thread and removes its worktree and branch once its agent has finished (it may still be tagging or deploying).

For developers who run coding agents in Herdr on macOS or Linux Free    ✓  A coordinator that delegates and never does the work itself    ✓  Threads on their own worktree and branch, or in a tab    ✓  Shared instructions and memory in every brief    ✓  What needs you, in the sidebar, the tab bar and one popup    ✓  Pull request follow-up, routines, cleanup after a merge    ✓  Threads on your saved SSH machines, reports copied home

Once, if you're on 0.2.2 or older (herdr-projects --version), which has no update yet:

herdr-projects ticker stop
herdr plugin install eliasstravik/herdr-projects
herdr-projects doctor --fix
herdr-projects ticker start

Herdr reinstalls the plugin in the same folder, and the plugin keeps your ~/.local/bin/herdr-projects link pointing at it. If you linked a local checkout with herdr plugin link instead, run git pull and sh scripts/install.sh in it in place of the herdr plugin install line.

From then on:

herdr-projects update           # fetch, install the new binary, doctor --fix, restart the ticker
herdr-projects update --check   # only print the installed and the newest version

update works for both install types and changes nothing when you're already on the newest release. Its doctor --fix also links the autoproject skill for each harness you configured, so existing users don't need to run configure again. A linked checkout must be on main with no uncommitted changes, or update stops and says why. When the install fails, the old version stays installed and the ticker is restarted. doctor says when a newer version is out.

You need to be comfortable in a terminal. The plugin downloads its own prebuilt binary on install, and a project is a plain folder of Markdown and TOML files, but you never have to edit them: everything changes by asking the coordinator or from the popup. You'll need macOS or Linux, Herdr 0.9.1 or newer, Git, and an agent CLI Herdr can start, such as Claude Code. Rust/Cargo is needed only when there is no prebuilt binary for your machine. The getting-started guide covers the prerequisites.

Run:

herdr plugin action invoke doctor --plugin herdr-projects

The command checks the Herdr version, the tools it calls, the ticker, and each project's session. The getting-started guide walks through a project that won't open, a thread that doesn't start, and a ticker that isn't running.

It runs the herdr-projects binary every turn, so you'll want to allow-list it in your agent by subcommand, never the bare binary. Allow reading and steering (skill, context, report, inbox done, thread list, thread prompt, thread next, thread read, thread keys and the like) and leave thread resolve, sweep, delete, rename, routine approve and configure on your agent's normal permission prompt. Leave thread start off the list too unless you've set start_threads = "auto": then every thread start is a real confirmation. Operations has the exact patterns.

No. A project is a folder on your machine, the plugin talks to your local Herdr session, and remote threads use your own SSH machines. Your agent CLI still uses its own service as usual.

Only to clean up after a thread is resolved, which happens when you resolve it, when its pull request is merged, or after auto_resolve_days idle. Then it removes the thread's worktree (never with force, so uncommitted changes keep it) and, only if the pull request is merged, the local branch. The thread's report and files are copied home first and always kept. It never merges or pushes itself: a merge happens when you send a thread its own "Merge the PR" line and the thread does it with its own tools.

In ~/.herdr-projects/<name>/ by default: PROJECT.md for your settings and standing instructions, AGENTS.md for priming the coordinator, MEMORY.md and memory/ for what the coordinator remembers, TASKS.md for the task list the coordinator keeps for you (each task assigned to you, a person, an agent profile, another machine or both: task owners), uploads/ for files you give the threads, threads/ for thread records and reports, and library/ for files threads produced. The safety settings live outside it, in ~/.config/herdr-projects/config.toml, where no agent works. Operations lists every file.

No. Run herdr-projects thread start yourself, or take an agent pane you already started and make it a thread with thread adopt. The herdr-projects adopt-workspace command turns the workspace you're in into a project with its agent as the first thread.

They are soft. By default the coordinator proposes threads and waits (until you turn on yolo mode in the popup), thread agents keep their normal permission prompts, which the coordinator answers for plainly in-task actions and brings to you otherwise (it may choose their model, never their launch flags), and routines may not run shell commands until you enable them and approve each command in a terminal. But agents have a shell: one that runs with skip-permission arguments can edit those files, a thread can prompt the coordinator pretending to be you, an approved routine command covers its text and not the scripts it calls, and whatever reaches memory is repeated in every later brief. Operations says plainly what each guard stops and what it doesn't.

Herdr Projects is free and MIT licensed. Your agent CLI's usual usage charges still apply: every thread is a full agent session, and the coordinator spends tokens each turn reading its digest.

Your first project starts with an install, a name, and one sentence about what you want. Herdr Projects starts the threads and keeps them in view. You choose what to review and what to merge.

_{✓ Free, MIT licensed   ✓ Runs on your machines, no hosted service   ✓ macOS and Linux, Herdr 0.9.1+}