coordinator
Health Gecti
- License — License: MIT
- Description — Repository has a description
- Active repo — Last push 0 days ago
- Community trust — 42 GitHub stars
Code Basarisiz
- exec() — Shell command execution in herdr/mods/coordinator-spaces/main.js
- network request — Outbound network request in herdr/mods/coordinator-topbar/main.js
Permissions Gecti
- Permissions — No dangerous permissions requested
Bu listing icin henuz AI raporu yok.
Turn one Claude Code session into a coordinator that runs, watches and cleans up a fleet of agent sessions in Herdr.
Coordinator
A higher-level agentic workflow for Claude Code and Herdr
Coordinator turns one coding-agent session into a manager for a body of
work. You give it a domain, such as a repo or a product area, and send it
requests as they come up. It writes a brief for each task and starts a
separate agent session to do it, in its own Git worktree and its own tab.
It watches those sessions, relays their questions to you, checks their
work, and cleans up when a task lands. You talk to one session, and up to
three others work in parallel.
It is a pair of skills for Claude Code,
with Python scripts that drive Herdr. Herdr runs each
agent in a terminal that stays alive and shows them all in one app.
How it works
- The coordinator is a Claude Code session you start with
/coordinator <domain or project>. It owns one domain and keeps its state in a
Markdown backlog file: what the domain covers, what you approved for
good, what is open, and what is done. The backlog is what survives a
restart. - Delegates are the sessions it starts, one per task. Each gets a Git
worktree, a brief that says what done looks like and where to stop, and a
tab in the Herdr app listed under the coordinator. A delegate writes aREPORT.mdwhen it stops. - The watcher,
fleet_watch.py, runs in the background and wakes the
coordinator when a delegate finishes, asks something or gets stuck. It
also wakes it when a pull request is merged, fails its checks or gets a
review. - The cap check keeps at most three delegates working at once, and can
hold the number of open pull requests in a repo under a limit you set. - Quiet delegates are ended after a day without a response, and resumed
with the same session when something arrives for them. - fleet-sweep, the second skill, removes finished worktrees, branches,
tabs and stray processes. It refuses anything that would lose work and
asks you about it.
The coordinator decides small, reversible things on its own and says what
it chose. It asks you when the answer changes what gets built, costs time
or money, reaches other people, or is a matter of taste. Questions arrive in
batches of at most five, each with its options and a recommendation.
Requirements
| Tool | Why |
|---|---|
herdr-core (hc) |
runs every agent in a terminal that outlives the app |
Herdr app (herdr-app) |
shows each delegate in its own tab |
| Claude Code | runs the coordinator and its delegates |
| Python 3.9 or newer | runs the scripts, which use only the standard library |
| git | worktrees and branches |
| gh, signed in | pull request status, for domains with a GitHub repo |
Optional:
- Codex can take small, mechanical
delegate tasks. - The inbox mod for Claude Code collects
every question in one pane. The scripts read its saved questions when it
is installed. - The Coordinator layout for Herdr is in
herdr/, described under
Herdr sidebar.
Tested on macOS with herdr-core 0.1.21, the Herdr app 0.1.15, Claude Code
2.1.325 and Codex 0.164.0.
Install herdr-core with:
curl -fsSL https://releases.herdr.dev/core/install.sh | sh
and download the Herdr app from herdr.dev.
Install
To have an agent do it, paste this into Claude Code:
Set up the coordinator workflow by following https://raw.githubusercontent.com/petekp/coordinator/main/SETUP.md
It installs Herdr, these skills and the Inbox plugin, and offers Vignette
and the Herdr sidebar, asking before each step. To install by hand:
git clone https://github.com/petekp/coordinator.git ~/src/coordinator
~/src/coordinator/install.sh
install.sh links both skills into ~/.claude/skills, where Claude Code
finds them, and ~/.agents/skills, where Codex finds them. It then checks
for the tools above. Keep the clone where it is: the links point into it.
To update, run git pull in the clone. At its first wake-up each day, the
fleet watcher checks whether the clone is behind its upstream, and the
coordinator tells you when it is. It never pulls by itself. To uninstall, run~/src/coordinator/install.sh --remove, then delete the clone.
Coordinator-first layout for Herdr, with the Inbox mod

The herdr/ folder holds an optional Herdr layout made for this workflow.
Its sidebar lists pinned coordinators first, in the order you drag them,
with each coordinator's delegates under it. The tab bar hides while a
coordinator's tab shows. Each agent gets a colored tile, and the inbox's
counts follow its name. The layout works without the coordinator or the
inbox, but the counts need the inbox.
It is listed in Herdr's layout gallery at
herdr.dev/layouts/petekp/coordinator--herdr.
The agent that follows SETUP.md offers the layout. To add it yourself, paste
this into an agent running inside the Herdr app:
Add the Herdr layout at https://github.com/petekp/coordinator/tree/main/herdr
The agent reads herdr/RECIPE.md and the layout's files,
then tells you what the mods run. It asks before it changes your keys or
your window. It also offers the inbox plugin, whose Herdr panel is the one on
the right of the picture.
Once a day the sidebar's top row checks GitHub for a newer version of the
layout, and shows a dot when one exists. Clicking the dot gives you a
line to paste to your agent, which updates the files you haven't edited and
asks about the rest. The agent asks at install whether to keep the check.
Configure
Every setting has a default, so you can skip this at first. To change one,
copy config.example.json to ~/.config/coordinator/config.json, delete
the keys you don't need, and edit the rest. Its values are examples, not the
defaults. COORDINATOR_CONFIG can name another file.
| Key | What it sets | Default |
|---|---|---|
backlog_dir |
the folder for backlogs; briefs for domains without a repo go in its briefs/ |
~/.config/coordinator/backlogs |
state_dir |
ended delegates, the cap check's log and the watcher's state | ~/.local/state/coordinator |
pr_limits |
most open pull requests from your GitHub account per repo, as {"owner/repo": 30} |
none |
keep_running |
domains whose delegates are never ended for being quiet | none |
delegate_claude_args |
extra Claude Code arguments for every delegate, such as ["--autocompact", "300000"] |
none |
delegate_codex_overrides |
extra Codex -c settings for every Codex delegate |
none |
inbox_store |
the inbox's saved state, needed only when more than one exists | found on its own |
backlog_limit_kb |
most kilobytes of a backlog outside its Done section, which the coordinator reads at each start; 40 KB is about 10,000 tokens | 40 |
done_limit_kb |
most kilobytes of a backlog's Done section | 20 |
trim_by_delegate_over_kb |
above this many kilobytes outside Done, about 37,000 tokens at 150, the coordinator has a delegate trim the backlog instead of reading it whole | 150 |
user_names |
regular expressions for your name, so the backlog check also finds your words quoted after it, as in Sam said "..." |
none |
open_ask_patterns |
regular expressions, matched ignoring case, for other ways your backlogs mark an open ask | none |
check_for_updates |
whether the fleet watcher checks, at its first wake-up each day, that the clone is up to date with its upstream | true |
Put backlog_dir inside a Git repo if you want the coordinator to commit
each backlog change.
First run
- Open the Herdr app and a terminal tab in it.
- Start Claude Code in the repo you want coordinated, and run
/coordinator <domain>, for example/coordinator web-app. - The coordinator asks what the domain covers, creates its backlog, and
reports what it found. - Send it a request. For anything bigger than a few files it starts a
delegate in a new tab and tells you the tab's name.
Ask "where are we" at any time for a status table of delegates, pull
requests and open questions.
To start a coordinator for another domain in its own tab:
~/.claude/skills/coordinator/scripts/coordinator_restart.py start <domain> --cwd <repo> --space <space id>
The space id comes from herdr-app ls.
Scripts
Each script's --help covers it in full.
| Script | What it does |
|---|---|
delegate_start.py |
starts a delegate, or resumes one whose terminal is gone |
delegate_cap.py |
allows or refuses a new delegate, and sends a message to one when allowed |
fleet_watch.py |
waits until something in the fleet needs the coordinator |
fleet_status.py |
prints the fleet's state, grouped by who acts next; with --resume, also the backlog sections to read again and whether the watcher runs |
backlog_check.py |
prints a backlog's size, and lists what a trim dropped that it must put back |
delegate_end.py |
ends a quiet delegate, and resumes it later |
coordinator_restart.py |
starts, restarts and stops coordinators |
watcher_check.py |
run by a scheduler, tells each coordinator with work and no fleet watcher to arm one; SETUP.md has examples |
sweep.py (fleet-sweep) |
reports leftovers and removes the safe ones |
Limits
- Delegates open as tabs in the Herdr app, so the app is required.
- Removing a worktree moves its ignored files, such as
.envand.scratch/, into<main checkout>/.scratch/parked/. Nothing here
deletes parked folders, so clear them out now and then. - Codex delegates start only in repos you have marked as trusted in Codex.
- Delegates run in your Claude Code permission mode. In the default mode
each one stops at permission prompts, and at the folder trust prompt in
each new worktree, until you answer in its tab. - Delegates start through your login shell when it is zsh, bash or another
POSIX shell, so they get your PATH. With fish or another non-POSIX shell
they start through/bin/sh, and needhc,claudeandpython3on
its PATH.
License
MIT
Yorumlar (0)
Yorum birakmak icin giris yap.
Yorum birakSonuc bulunamadi