eliasstravik/herdr-projects

Herdr Projects – Coordinating many coding agents for a single piece of work

What it is

• A free, MIT‑licensed plugin for the Herdr AI‑coding environment (macOS / Linux, Herdr 0.9.1+).
• It adds a coordinator agent that lets you launch a whole “project” made up of several independent agent threads, each working on its own Git worktree/branch (or plain folder).
• You keep a single conversation with the coordinator while the threads run in parallel, and the Herdr sidebar groups them by status (needs you, working, ready for review, etc.).

Why you’d use it

• When a task is too big for one coding agent, you can split it into multiple agents automatically instead of manually starting and tracking each one.
• The coordinator never does the heavy lifting, so it stays free to answer your questions.
• All threads share the same goal, standing instructions, and memory, ensuring consistency across the whole project.
• No hosted service – everything lives on your own machine and your own SSH‑accessed machines.

Key features

Feature	What you get
Parallel execution	Each task runs in its own Git worktree/branch (or folder) so work proceeds concurrently.
Single chat	Talk only to the coordinator; it forwards progress reports and asks for input when a thread needs you.
Sidebar overview	Threads appear as rows with IDs, titles, and status tags (e.g., review · PR #4, ~40%).
Automatic thread lifecycle	After a PR is merged or a thread is idle for a configurable period, the plugin cleans up the worktree/branch and copies reports to a safe location.
Works with any Herdr‑compatible agent	Claude Code, Codex, OpenCode, or any CLI‑based agent Herdr can launch.
No extra fees	All functionality is free; you only pay the normal usage costs of the underlying agent model.
Configurable safety	Fine‑grained allow‑list for what the coordinator may ask the agent to do; optional “yolo” mode to auto‑approve.
CLI‑first workflow	Install with herdr plugin install eliasstravik/herdr-projects, then use commands like herdr-projects new, herdr-projects open, herdr-projects thread start, etc.

How it works (high‑level flow)

1. Install & configure – herdr plugin install … downloads a pre‑built binary; herdr-projects configure sets up sidebar rows, popup keys, and the /autoproject skill.
2. Create a project – herdr-projects new "Billing" --repo ~/dev/app creates a folder under ~/.herdr-projects/ with a set of Markdown/TOML files (PROJECT.md, AGENTS.md, MEMORY.md, …).
3. Talk to the coordinator – Describe the overall goal in the coordinator’s pane. The coordinator proposes a set of threads (each a separate agent task) and waits for your approval.
4. Threads run – Approved threads start in their own Git worktrees/branches (or folders) and execute the agent CLI. They report progress, ask questions, and open PRs as needed.
5. You stay in the loop – The sidebar highlights threads that need you; you can answer, review, or merge PRs directly from Herdr.
6. Cleanup – When a thread finishes, the plugin removes its worktree/branch (unless there are uncommitted changes) and archives the report.

Getting started (quick three‑step cheat sheet)

Step	Command	What it does
1️⃣ Install	herdr plugin install eliasstravik/herdr-projects herdr-projects configure	Pulls the binary, registers sidebar rows and popup shortcuts.
2️⃣ Create	herdr-projects new "MyProject" --repo ~/dev/myrepo herdr-projects open myproject	Sets up the project directory and launches the coordinator agent.
3️⃣ Describe	Type your high‑level description in the coordinator pane and confirm the suggested threads.	Coordinator spawns the parallel agents; you watch their status in the sidebar.

Where data lives

• Project folder: ~/.herdr-projects/<name>/ (contains PROJECT.md, AGENTS.md, MEMORY.md, TASKS.md, threads/, library/, etc.).
• Configuration & safety settings: ~/.config/herdr-projects/config.toml (outside the project, never edited by agents).

Updating

• Run herdr-projects update (or --check to just see versions). The command fetches the newest binary, runs doctor --fix, and restarts the background ticker that keeps projects alive.

Safety & permissions

• The coordinator runs the herdr-projects binary; you should allow‑list it by subcommand, not the raw binary. Typical allowed actions: skill, context, report, thread list, thread prompt, etc. More restrictive actions (e.g., thread resolve, sweep) stay behind the normal agent permission prompt.
• The plugin never pushes or merges code on its own; merges happen only when a thread explicitly runs a “Merge the PR” command.

Who should use it

• Developers comfortable with a terminal who already use Herdr for AI‑assisted coding.
• Teams that need to break a large feature into several independent AI‑driven subtasks while keeping a single point of interaction.
• Anyone who wants a fully local, free solution without a hosted project‑management service.

License

• MIT License – you can use, modify, and redistribute the plugin freely.

---

All details above are taken directly from the repository’s README; no additional features have been inferred.