herdr-foreman
Health Warn
- License — License: MIT
- Description — Repository has a description
- Active repo — Last push 0 days ago
- Low visibility — Only 5 GitHub stars
Code Fail
- exec() — Shell command execution in app/foreman/main.js
- process.env — Environment variable access in plugin/ask.js
Permissions Pass
- Permissions — No dangerous permissions requested
No AI report is available for this listing yet.
Write one sentence; a lead agent splits it across your coding agents (Claude Code, Codex, opencode…), each in its own git worktree. You approve before any code changes. A herdr plugin.

herdr-foreman
herdr is a terminal multiplexer for AI coding agents, with about 38k GitHub stars and a place in the ThoughtWorks Technology Radar (Assess, November 2026). foreman is a plugin for it that gives one task to several coding agents at once.
You have one task and more than one agent: Claude Code, Codex, opencode, agy. Doing it by hand means splitting the work yourself, keeping the agents out of each other's files and checking what each one did. foreman does that for you. A lead agent reads the repository, splits the task, picks an agent and model for each part, and runs every worker in its own git worktree and herdr pane.
Nothing changes until you approve the plan. Workers first only read the code and propose changes. The leader puts the proposals in one numbered list and you answer, for example "1 and 3 yes, 2 no". Only then do the workers write code, each in its own worktree. The leader collects and tests the result and asks again before anything lands on your branch. foreman never pushes and never opens a pull request.
foreman "check the payment module for security holes and fix what needs fixing"

Install
herdr plugin install Kvmyk/herdr-foreman
You need herdr 0.9.5 or newer, Node.js 20 or newer (nodejs.org), git (git-scm.com) and at least one coding agent, signed in, for example Claude Code, Codex, opencode or agy. The command sets everything up, the Herdr desktop app too if you have it. Only use the desktop app? See Other ways to install.
- Start a task: open a terminal in your project folder (a git repository with at least one commit). In herdr press
Ctrl+B, thenF. In the desktop app pressCtrl+Shift+Y, type the task and pressCtrl+Enter. The leader opens in a new tab and tells you what it plans before anything changes. - From your phone: the Herdr phone app works with the same install on the machine it connects to. See From your phone.
- Update:
herdr plugin update(or run the install script again). - Something does not work: type
foreman setup. It checks everything, fixes what it can and says what is left. See Troubleshooting.
Start a task (terminal)
- Open a terminal in your project folder and type
herdr. - Press
Ctrl+B, let go, then pressF. - Type what you want done, in plain words. You can paste several lines; finish with an empty line. An empty first line cancels.
The lead agent opens in a new tab and tells you what it plans to do before anything changes. In the desktop app, use its prompt instead (see Herdr app).
Describing the task
- Both prompts: write it in your own words. Point at files with
@and the file name (@src/login.js); links to issues or docs work too. foreman checks that the files exist and warns you when one has changes you have not committed. - Command line: a longer task can be written in a file (
foreman -f task.md) or piped in (cat task.md | foreman). - herdr prompt (terminal): you can paste several lines and finish with an empty line (or Ctrl+D), or type
eto write the task in an editor ($VISUALor$EDITOR; Notepad on Windows). - Desktop prompt:
Enteris a new line andCtrl+Enterstarts, so a long task can be written in the box itself;@offers file names.
Other ways to install
Herdr desktop app only. Open the app once first, then in a terminal:
# Windows (PowerShell)
irm https://raw.githubusercontent.com/Kvmyk/herdr-foreman/main/install.ps1 | iex
# macOS and Linux
curl -fsSL https://raw.githubusercontent.com/Kvmyk/herdr-foreman/main/install.sh | sh
The script checks Node.js and git, runs npm install -g github:Kvmyk/herdr-foreman and then foreman setup, and prints what, if anything, is left to do (for example an agent to sign in). Read install.ps1 or install.sh first if you like, or run those two commands by hand. To update, run it again.
As a command, or set up by hand: see Advanced install. On Windows, read Windows and PowerShell.
Herdr app (desktop)
If the Herdr desktop app is installed (its folder is ~/.config/herdr-app, on Windows %USERPROFILE%\.config\herdr-app, or $HERDR_APP_HOME), foreman setup also adds foreman to it. You do not need the terminal version of herdr for this.
In the app, open a terminal in your project folder and press Ctrl+Shift+Y. A prompt opens:
- Desktop prompt, keys:
Enteradds a line,Ctrl+Enter(Cmd+Enteron a Mac) or the Start button starts,Esccancels. What you typed is kept as a draft when you cancel and comes back the next time. - Desktop prompt,
@: type@and part of a file name to get a list of files of your project; click one to insert it. - While workers run: a worker that is stuck on a question or has stopped puts its name in its tab's title (
⚠ w2 needs you) and the app brings that tab forward.
More about the prompt, and what setup changes in the app folder: Reference.
From your phone

The Herdr phone app (iPhone, iPad, Android, herdr.dev/mobile) is a remote client. It connects over SSH to herdr-core on your machine, lists your agents in an Inbox (needs you, done, working, idle) and gives you a terminal with a key bar and a box for composing text.
What you need
- the Herdr phone app, connected to your machine
- herdr-core or the Herdr desktop app on that machine
- foreman installed on that machine (see Install)
Runs use the app backend. A run started in the Herdr terminal app (TUI) does not show on the phone.
Start a task
- With the launcher. The first time you run
foreman setupin a terminal, it asks whether you want to start foreman from the Herdr phone app; answery. You can also typeforeman launcher onat any time, or turn on Phone launcher in the desktop prompt. A terminal titledforeman: new taskthen sits in your Inbox, in the space you used last. Open it, paste or dictate the task and send it. It asks for the project, the leader, auto and uncommitted changes; answer each by sending a number. The project list includes the repositories of the folders of your Herdr app spaces, even ones with no run yet. It starts the leader, then waits for the next task.foreman launcher offturns it off and closes the terminal. - Without the launcher. Open any terminal on the machine and type
foreman new(or justforeman). It asks for the task the same way.
Answer questions
Answer everything in the terminal of the leader, with short replies such as 1 or yes. The leader names the worker, asks one question at a time and passes your answer to the worker itself. You only go to another terminal to sign in to an agent.
What the phone does not do
- There is no shortcut and no prompt window; use the launcher or
foreman new. - Banners show only while the app is open. To get a message when a worker needs you, set
notifyCommandinconfig.json(see Files). - When you type into a terminal from the phone, it gets the width of the phone until you click it on the desktop. Workers are then shown one per tab (
"layout": "tabs"), and output is shorter under 60 columns.
How a task runs
foreman "<task>"in a git repository. Outside herdr it starts the herdr server if needed, opens a workspace and attaches; inside herdr it opens a new tab.- The leader (default:
claude) runsforeman brief --json: installed agents, whether they are signed in, their models, what is known about each harness and model family, and your own past results per task category. - It shows the plan, then opens workers with
foreman spawn, each in its own git worktree and pane. Workers are stacked one under another to the right of the leader (up to 4; more go to a tab of their own);"layout": "grid"inconfig.jsonputs them side by side instead. - Workers investigate without changing anything and write proposals. The leader merges them into one numbered list; you answer, for example, "1 and 3 yes, 2 no".
- Approved items are implemented and committed in the workers' worktrees.
foreman mergecollects them on the run branch<type>/<name>(for examplefeat/auto-accept-workers; workers usewip/<name>/<worker>) in a separate worktree; the leader builds, tests and reviews. - You choose: merge into your current branch (
foreman land), leave the branch for later, or send comments back. foreman cleanupcloses worker panes and removes worktrees;foreman journal addrecords how each agent did. The leader then asks whether to close its own tab.
Workers write their reports to .foreman/ inside their own worktree; foreman adds .foreman/ to the repository's .git/info/exclude, so reports never show up in git status or a commit.
If a worker asks for permission, the leader asks you once whether you answer such questions yourself or let it answer on your behalf. It never approves a push or a pull request. In auto mode claude workers get --permission-mode auto (with git push and gh denied), codex --ask-for-approval never in a workspace-write sandbox without network, gemini --approval-mode yolo, opencode --auto, and agy --dangerously-skip-permissions, because agy's own --mode auto still asks before every shell command. When you choose auto before the start, the leader starts in its auto mode too, and every worker of that task gets auto mode even if the leader leaves out --auto. The workers run in foreman's own worktrees, which have the push guard; for agy, opencode and gemini it is the only thing that blocks a push.
Choosing agents
Choosing is based on three layers:
- What works right now: every run probes the installed agents, for example
claude auth status,agy models,opencode models,pi --list-models. An agent that is not signed in is left out, with the reason. - General knowledge:
knowledge/agents.jsonholds dated facts (benchmark scores with rank, harness and date; the newest release of each program; the newest model of each family), each tied to a renewable public source. Model facts (context, price, release date) come from models.dev, fetched at most once a day. - Your results: the journal in
~/.herdr-foreman/journal.jsonl. Once a category has 5 or more results, they outweigh the general knowledge.
How that knowledge stays up to date: Reference.
More documentation
- Troubleshooting: what to do when something does not work
- FAQ: cost, what foreman changes, what it never does, how to remove it
- Windows and PowerShell: PATH, script policy, quoting tasks
- Reference: every subcommand,
config.jsonand the other files, token use, the agent knowledge
Development
npm test
Tests use only Node's built-in test runner; git tests create throwaway repositories in the system temp directory.
To try the plugin from a working copy, run herdr plugin link . in it (and herdr plugin unlink herdr-foreman to undo).
Changes are listed in CHANGELOG.md.
Media
The logo, the banners and the demo GIF are original and covered by the same license. The images in this README live on the assets branch. The demo GIF follows foreman's real flow and command names, but its repository, findings and commit ids are made up. A recording of a real run is planned.
License
MIT
Reviews (0)
Sign in to leave a review.
Leave a reviewNo results found