Getting started.

herdbot is a macOS tool, and this is the part that does not move: the daemon runs under launchd. The cask declares macOS Sequoia or later.

It drives other tools rather than replacing them. You need:

• herdr running. herdbot was tested with herdr 0.9.1, socket protocol 22.
• at least one harness CLI on your PATH, signed in: claude, codex, cursor-agent or pi. Pi is restricted to the opencode-go provider — herdbot rejects any other pi model.
• Rust with edition 2024 support, only if you build from source. The cask does not need it.

Nothing else is required. There is no server to run and no database to install: the herdbot home is a directory of plain files.

brew install --cask slogsdon/tap/herdbot

The cask is published from the slogsdon/homebrew-tap repository — Homebrew’s slogsdon/tap shorthand names it. That tap is the distribution channel for Herdbot, not a second project: the cask installs Herdbot.app into Applications and links the binary bundled at Herdbot.app/Contents/Helpers/herdbot onto your PATH. Uninstalling the cask stops dev.herdbot.daemon and quits the menu bar app.

The zip from GitHub Releases works the same way: drag Herdbot.app to Applications, open it, and press Set up everything.

Then pick one: open Herdbot from Applications and use its setup window, or run herdbot setup in a terminal. Both do the same work, and step 3 covers the terminal path.

herdbot doctor is the first-run and health check, and it exits 1 if any check fails. It looks at whether herdr answers, which harness CLIs are on PATH, whether the herdbot home and herdbot.toml exist, whether the launchd service is installed and runs the same binary you just invoked, whether the CLI is linked onto PATH, and whether the running daemon is older than the binary on disk.

herdbot doctor

herdbot doctor --json prints the same checks for a script.

herdbot setup runs the fixes doctor names, once each, in order: home, cli-link, service, restart-daemon. --only picks one of those; --yes answers its prompts.

herdbot setup

What that does, in the README’s words: it checks herdr and the harness CLIs, creates ~/Bots and a commented herdbot.toml, links the CLI, installs the launchd service, and offers a starter bot. Accept the starter-bot prompt to create helper, then edit its instructions:

$EDITOR ~/Bots/helper/BOT.md

The service writes ~/Library/LaunchAgents/dev.herdbot.daemon.plist and starts the daemon at login. After upgrading the binary, doctor flags a daemon older than the file on disk; restart it with:

herdbot setup --only restart-daemon

herdbot service status, install and uninstall manage the same plist by hand. Set HERDBOT_HOME to keep bots somewhere other than ~/Bots.

A bot is a folder with a bot.toml and a BOT.md. herdbot new takes a name, and optionally a working directory and the task class its main agent is routed by (unset, it uses default):

herdbot new <name> [--cwd DIR] [--class CLASS]

A bot’s cwd defaults to its own folder; pointing it at a checkout is how you get a bot that works on a repository:

herdbot new herdbot-dev --cwd ~/Code/herdbot

It prints created …/herdbot-dev (edit BOT.md for its instructions) and leaves BOT.md empty for you to fill in. Then open the workspace in herdr:

herdbot up herdbot-dev

up starts the bot’s main agent and prints the agent name, workspace id and root pane. It is not strictly required before the first message: the daemon brings a bot up when it finds work for it, and the workspace opens in herdr the first time a message arrives. herdbot down <bot> stops it again.

herdbot list shows every bot with its title, whether it is up, how many schedules are on, and whether it came from Grok Bot or was created locally.

The routing table is routing.toml in the herdbot home, written from the repository default on first use and free to edit. Every candidate is harness:model[:effort]. For each task herdbot tries, in order:

1. an explicit model argument on task
2. the bot’s override in [bots.<slug>]
3. [classes.<subagent_type>], an ordered list of harness:model[:effort]
4. [default]

The first available candidate wins. A harness is available when its binary is on PATH and it isn’t cooling down after a quota or auth failure. Every launched agent gets an explicit effort: the candidate’s own, then the class’s, then [default], then medium.

Task classes are Grok Bot’s subagent types (explore, shell, bash, browser_use, computer_use, debug, media_review, custom) plus code, review, plan, research, and compact for a memory bot’s compactor runs. Ask what a class resolves to right now:

herdbot route explore
herdbot route code --bot herdbot-dev

The shipped table lists candidates for claude, codex and pi only. Its model IDs were listed by the installed CLIs on 2026-10-19, and which model suits which task is the author’s judgement — the table says so itself and expects tuning.

Cooldown and failover. When a subagent settles or blocks, and when a main agent finishes a turn, the daemon scans the last 15 non-empty lines of its pane for that harness’s failure text. A match writes .state/cooldown/<harness>.json, and routing skips that harness until the reset time plus a minute — or for an hour when the text gives no time. A subagent that failed this way is closed and its task re-queued on the next route. Deleting the cooldown file lifts it early.

Those failure strings were checked against claude 2.1.304, codex 0.163.0 and cursor-agent 2026.10.16. Cursor’s quota text comes from its server and the pattern comes from one real capture, so other wordings may slip through.

A message goes to the bot’s main agent. The daemon delivers it, so send needs the daemon running; a prompt sent to a busy agent waits in a queue instead of interrupting its turn.

herdbot send herdbot-dev "What does this repo do?"

A task starts a subagent in a new pane instead. The class decides the route:

herdbot task herdbot-dev explore "Which file defines the CLI usage string?"

task returns the run id once the agent has taken the work, usually within a few seconds, and the pane appears to the right of the bot’s own. When the run finishes, the bot that asked gets the result — through report_result, through the harness’s turn-end hook, or from the last lines of the pane. A run that needs your approval is reported as blocked, once, with its pane.

Watch it, or read it afterwards:

herdbot status --json
herdbot runs
herdbot history herdbot-dev --json --limit 5
herdbot focus herdbot-dev

Approvals. The default is "ask", which adds no flags and leaves each harness’s prompts alone. Only herdbot’s own tools are pre-approved. A bot can be switched to automatic review with approvals = "auto" in its bot.toml, or [approvals] mode = "auto" in herdbot.toml for every agent; full bypass flags (--yolo, --dangerously-skip-permissions) are never used. A prompt stuck behind a modal becomes a card: herdbot card list, then herdbot card answer <card-id> <option-id>, which re-checks the live screen before answering.

If a bot should work on a repository rather than in its own folder, that is the --cwd from step 4. Schedules, rooms, memory and computer use all sit on top of this one loop; none of them are needed for a first bot.

The README is unusually direct about what has and hasn’t been seen working, and these are its qualifications, kept as written.

• Early, and macOS only for now.
• Grok Bot’s schedules and skills are not imported, because Grok Bot keeps them server-side. The roster import is one-way and writes nothing back.
• cursor-agent launches, but its tools haven’t been seen working end to end — the test account hit its weekly limit. Whether cursor asks for each tool call under --approve-mcps is untested.
• Quota detection reads the pane, so claude’s quota detection is unverified; only cursor’s has been seen working on a real limit.
• While a trust or warning modal is up, herdr can report the agent as idle and a queued message is lost. When fm is available the daemon holds the delivery instead, but the README’s author hasn’t seen that hold fire on a real modal.
• The retry that re-sends a prompt when a subagent didn’t start a turn has been seen once, with codex, and not reproduced, so that path is untested.
• For computer use, the ask approval flow end to end and any remote host are not verified.

None of this is a reason to wait, as long as you read it the way it is written: a local tool, early, on one platform, whose author tells you which parts were watched live and which were not.