Skip to the content.

bees is a single binary. Most commands need a bees.toml; it is found with --config, then $BEES_CONFIG, then by searching upwards from the current directory.

Four commands — bees mail send, bees issue create, bees issue link and bees done — exist for the sessions inside the factory, though people can use them too. A session normally reaches the same operations as MCP tools, along with the GitHub operations every role performs: bees mcp serve serves them, and every session gets it automatically. Everything else is for people.

Global flags

Flag Description
-c, --config <path> Path to bees.toml or a machine config. Default: $BEES_CONFIG, else search upwards from cwd.
-v, --verbose Debug logging (same as --log-level debug). With run/tick/exec, also streams every session event to stderr — except under the live view, which owns the terminal; bees run --no-tui streams as before.
-q, --quiet Console shows only session summaries, warnings and errors. Cannot be combined with -v or --log-level debug.
--log-format <text\|json> Console log format. Default text; $BEES_LOG_FORMAT, then logging.format.
--log-level <debug\|info\|warn\|error> Console log level. Default info; $BEES_LOG_LEVEL, then logging.level.
-h, --help Help for any command.

A flag beats its environment variable, which beats the [logging] table in bees.toml, which beats the default. An unknown value is an error naming the valid ones.

With the live view up — bees run in a terminal — the console shows nothing at all: these flags describe the console, and <state_dir>/bees.log gets every record whatever they say. --no-tui turns the view off.

Setting up

bees init

Creates bees.toml in the current directory (which must be a git clone of the project), creates the state directory, adds it to the repository’s .gitignore (unless git check-ignore says it is already ignored, or it lives outside the clone) and prints a reminder to commit that, and creates the workflow labels in the GitHub repository. Refuses to overwrite an existing file. bees.toml is meant to be committed.

init validates before it writes: the current directory must be a git clone; the configuration it is about to write must parse and resolve to a repository and a default branch; and, when --github-login/--github-token gave the factory an account of its own, GitHub must accept that token, the token must belong to that login, and the account must be able to read the repository. init prints the login it will act as (acting on GitHub as busybees-bot); creating the labels is that token’s first real job. A value you stated, or init really detected, is written as an active setting; one it could only guess stays a commented placeholder, so init fails rather than write a default branch nobody confirmed. To act as a GitHub App, add it to [github] after init and run bees doctor, which asks the App the same questions. A failed init leaves no bees.toml behind and the directory exactly as it was: fix what the error reports and run init again. The one step that can fail after the local files exist is creating the labels; the error then says to run bees labels sync, not init again.

Last, init runs the full bees doctor, the expensive per-role checks included — this is where a wrong skill URL or an unreachable MCP server is worth waiting for — prints the table and points at bees doctor. A check that fails does not make init exit non-zero: bees.toml and the labels are written by then, and the table is the list of what is left to set up.

Flag Description
--remote name Git remote the factory pushes to (default origin).
--repo owner/name Write project.repo as an active setting, and project.default_branch too when it could be detected from the remote. By default both are derived from the remote at run time and only appear as commented placeholders showing the detected values.
--default-branch <name> Write project.default_branch as an active setting, as given: no detection, no check against the remote. Use it when the branch cannot be detected (a remote that cannot be reached), which is otherwise what makes init fail.
--label <name> Visibility label (default bees).
--assignee <login> Only see items assigned to this login; @me for yourself.
--github-login <login> Write github.login: the GitHub account the factory acts as. Needs --github-token.
--github-token <token> Write github.token. Pass '$VAR' (quoted, so the shell leaves it alone) to keep the secret out of bees.toml and read it from the environment instead. Needs --github-login.
--template <name> Write the bees.toml a named config template describes instead of the default file: the eight settings that template decides are written as active lines, under a comment naming it. An unknown name is an error and nothing is written.
--print Print the template to stdout instead of writing it. Writes nothing, so it works outside a git clone.
--no-labels Skip creating GitHub labels.

The default file lists every option; optional ones are commented out with their default values (#max_developers = 1), so configuring is a matter of uncommenting and editing lines. See configuration.md.

cd ~/src/my-project
bees init
bees init --assignee @me --label kyle-bees

bees doctor

Runs the preflight checks the factory otherwise only discovers mid-run, and prints what it found grouped by area:

Group Checks
toolchain git on PATH; gh on PATH, authenticated and holding the repo token scope; claude (or $BEES_CLAUDE_BIN) runnable and new enough; codex (or $BEES_CODEX_BIN) runnable, when a role is configured with agent = "codex"; opencode (or $BEES_OPENCODE_BIN) runnable, when a role is configured with agent = "opencode"; pi (or $BEES_PI_BIN) runnable, when a role is configured with agent = "pi"; sbx on PATH and answering sbx version, when a role is configured with sandbox = "sbx".
config bees.toml loads and validates; project.repo and project.default_branch are set or derivable; the remote answers; the state directory is ignored by git; the notes directory is writable; the sessions directory is writable, when a role is configured with agent = "opencode" or agent = "pi"; every configured prompt_file exists; the repository’s bees/prompts/ files are all readable and named after a role; a running scheduler is serving a build of the commit that is checked out.
github The repository is readable and writable (viewerPermission); with [github] set, that github.login is the account the credential belongs to, and for a GitHub App that the App is installed on the repository; every workflow label exists; with [github] set, that the account can actually write issues, issue comments and labels; with [github] set, that the account can actually push branches; the visibility filter matches at least one open issue; with auto_merge on, what a merge is actually gated on.
workspace A worktree can be created under workspace_root and removed again.
roles Per role: every configured skill URL clones and produces a plugin directory; every configured MCP server starts and answers an initialize request within 15s; a configured shell can be executed; for a pi role, pi --no-extensions -e npm:pi-mcp-adapter -e <pi_packages entry>... --help loads the adapter and every pi_packages entry, pi installing what is missing, within 5m (see Pi).

A failure (✗) means the factory cannot run: a missing tool, a repository it cannot push to, missing workflow labels. A warning (!) means something that will probably bite you but does not stop a session: a state directory that is not git-ignored (notes and transcripts would be committed), a filter that matches no open issue (usually a misconfigured label or assignee), a Claude Code older than bees expects, a running scheduler older than the repository it is building.

The filter check tells the two empty cases apart: when nothing matches the filter but open issues or pull requests carry the base label, it reports both counts and spells the filter out (0 match your filter (label=bees AND assignee=kyle)). That is a filter criterion hiding work the factory already owns, not an empty repository, and the fix is bees doctor --fix (below) or unsetting the criterion in bees.toml.

The auto-merge check is a warning of the same kind: with roles.reviewer.auto_merge on and no check required on the default branch, bees gates a merge on whatever checks the pull request happens to report. Requiring your CI checks in the branch protection rules is the fix, and leaving it alone is a legitimate choice. bees never enables or edits branch protection itself, and the check is silent when auto_merge is off.

The scheduler build check is the one to read after merging a change to a role prompt. The prompts are compiled into the binary, so a running bees run keeps serving the ones it was started from: the check reads the revision the scheduler recorded in status.json and asks git where it sits relative to HEAD, and warns when it is behind it, is not an ancestor of it, or is a commit this repository has never seen. The repair is to rebuild and restart the factory, which doctor will not do to a running one — hence a warning, never a failure, and never --fix. It compares against what is checked out and never asks the remote, so doctor works offline. It passes and says so whenever the question does not arise: no scheduler has run, none is running now (a status.json outlives the run that wrote it), or the binary carries no revision to compare — a release build, or one built from a tree with no VCS stamps.

The three [github] checks answer what viewerPermission cannot, and all three are silent — a pass saying so — when the table is unset, because there is then no configured account to check.

The first compares the login the credential actually authenticates as with github.login, and reports a mismatch by name. github.login is what tells the factory’s own comments from a person’s, so a login naming an account other than the one posting means a person’s comments are read as the factory’s own and answered by nobody. For a GitHub App the login is the App’s slug followed by [bot], and the check also asks whether GitHub accepts the App ID and key and whether the App is installed on the repository. For a token the login is the token’s user, written without the suffix, and a user login written with it is a mismatch named in the detail.

The second establishes that the account can write what bees writes. Repository permission does not imply it: a fine-grained token carries per-resource permissions on top of the repository role, so ADMIN and “cannot create an issue” are an ordinary pair — and then every issue_create, comment and label edit in every session fails, one session at a time. The probe is a no-op update of the base label, renaming it to the name it already has: a real write, so GitHub’s permission gate is what answers it, and it changes nothing and leaves nothing behind. A fine-grained token’s Issues grant governs issues, issue comments and labels alike, so the cheapest of them answers for the others, and the remediation names what to grant.

The third establishes the sibling permission: that the account can write the repository’s git refs, which is what every developer session’s git push needs. The probe is a no-op ref update — the default branch is read and then set to the commit it already points at. It changes nothing: no commit, no push event, nothing in the timeline and nothing to clean up. A protected branch refuses the update for a reason that is not permission, so that answer is a warning rather than a failure. Pull requests is a separate fine-grained permission and is deliberately not probed — every side-effect-free candidate perturbs something, and the Contents refusal is the earlier failure anyway, since a session that cannot push never reaches gh pr create — so the remediation names both grants together.

Every warning and failure prints the command that fixes it on the next line; doctor changes nothing unless --fix is given.

doctor exits 1 when a check failed and 0 when only warnings are present, so it can gate a deploy. Checks that need something that is missing are left out rather than reported twice: without a bees.toml only the toolchain checks run, and the GitHub and workspace checks need a resolved repository.

The roles group is the expensive half: it clones skill repositories and starts MCP servers, which takes seconds to minutes on a cold cache. bees doctor and bees init run it; the bees run preflight does not (see bees run). Each role reports one line per thing it configures, named after the role (developer skills, qa mcp), so the table says which role is broken rather than that something is. A role that configures none of the three still gets a line, and a role with enabled = false is reported as disabled rather than dropped silently. The skills are cloned into the cache a session uses ($BEES_CACHE_DIR, else the user cache directory: ~/.cache/bees on Linux, ~/Library/Caches/bees on macOS), so doctor warms it instead of duplicating the work.

$ bees doctor
toolchain
  ✓ git                         /usr/bin/git (git version 2.50.1)
  ✓ gh authenticated            logged in as kyle, token scopes: gist, read:org, repo
  ✓ claude runnable             claude 2.1.251 at /usr/local/bin/claude

config
  ✓ bees.toml valid             /home/kyle/src/proj/bees.toml (version 1)
  ✓ project repo                kyle/proj, default branch main (remote "origin")
  ✓ remote reachable            origin answers
  ! state dir ignored           .bees is not ignored by git
      → add "/.bees/" to .gitignore: notes, mail and session transcripts would be committed otherwise
  ✓ notes dir writable          /home/kyle/src/proj/.bees/notes
  ✓ prompt files exist          no prompt_file configured
  ✓ project prompt files        no bees/prompts/ directory
  ! scheduler build is current  running 4773767e3b1a, which is 6 commits behind HEAD (9f56e8a2c104)
      → rebuild and restart `bees run` to pick up prompt and code changes: the role prompts are compiled into the binary

github
  ✓ repo readable and writable  kyle/proj (ADMIN)
  ✓ github.login matches token  github.token belongs to proj-bot
  ✗ workflow labels             2 of 17 missing: bees:size/l, bees:size/xl
      → run `bees labels sync`
  ✓ can write issues            proj-bot can write issues, issue comments and labels in kyle/proj
  ✓ can push branches           proj-bot can update main in kyle/proj
  ✓ filter matches issues       12 open issues matching label bees
  ✓ auto_merge check gate       auto_merge is off: people merge pull requests themselves

workspace
  ✓ worktree                    created and removed one under /tmp/bees

roles
  ✓ product_manager             enabled, no skills, MCP servers or shell configured
  ✓ project_manager             enabled, no skills, MCP servers or shell configured
  ✓ developer skills            1 skill ready: https://github.com/acme/skills#skills/tdd
  ✗ developer mcp               sentry: fork/exec /opt/sentry-mcp: no such file or directory
      → start the server by hand or fix [roles.developer.mcp] in /home/kyle/src/proj/bees.toml: a session that cannot reach it loses those tools
  ✓ reviewer                    enabled, no skills, MCP servers or shell configured
  ✓ qa                          disabled (roles.qa.enabled = false)

25 checks: 21 passed, 2 warnings, 2 failed
Flag Description
--json Print the results as JSON (name, group, status, detail, remediation) instead of the table.
--fix Apply the repairs doctor knows how to make, then re-run the checks.

bees doctor --fix

--fix runs the checks, applies the repairs doctor knows how to make for the ones that did not pass, prints one line per action and then re-runs every check, so the table is what the repository looks like afterwards and the exit code follows the repair: --fix exits non-zero only if a check still fails. Checks doctor cannot repair are untouched, and their remediation line still says what to do by hand.

Exactly one repair exists today: the filter check. It lists the open issues and pull requests carrying the base label (filter.label) that do not match the rest of the filter, and adds filter.assignee and, when one is configured, filter.milestone to each. That is the repair for the failure this exists to catch: adding assignee = "@me" to a factory that has been running for weeks takes every issue nobody ever assigned out of the factory’s view in one commit.

$ bees doctor --fix
fixing filter matches issues
  assigned issue #92 to kyle
  assigned issue #119 to kyle
  assigned pull request #148 to kyle
  ! issue #131: assign to kyle: gh: HTTP 403 (forbidden)
...
  ✓ filter matches issues       12 open issues matching label bees + assignee kyle

What it will not do:

bees labels sync

Creates or updates every workflow label in the repository (idempotent), forcing the factory’s colour and description on the labels that already exist. Run it after changing filter.label. Labels that are merely missing need no sync: bees run creates them at start.

bees labels list

Prints the label names and what each one means.

bees skills list

Prints the skill repositories configured for the enabled roles: the cache directory and the refresh policy on the first line, then one line per reference with its commit (or not cached), how long ago it was fetched, the roles that use it and the reference itself. Reads the cache only — no session, no GitHub.

$ bees skills list
/home/kyle/.cache/bees  (refresh: 24h)
9f1c0aa     3h ago  developer,reviewer  https://github.com/acme/skills#skills/tdd
not cached  -       qa                  https://github.com/acme/qa-skills

bees skills update

Clones what is missing and pulls everything else right now, whatever skills_refresh says. With no argument (or --all) it updates every configured reference; arguments must match a configured reference verbatim.

$ bees skills update
updated https://github.com/acme/skills#skills/tdd 9f1c0aa → 2b7d431
unchanged https://github.com/acme/qa-skills 4c19e02

A reference that fails prints failed <ref>: <error> and the command exits non-zero after trying the rest. Pinned references (@v1.2.0) are detached checkouts and cannot be pulled; that failure is expected.

bees config validate

Loads bees.toml and reports errors (missing or unsupported version, unknown keys, bad repo, invalid MCP server, …).

When the file is a machine config, it loads every project listed and reports the first entry that fails, or prints how many projects the file lists.

bees config migrate

Rewrites bees.toml to the current format version (see version), keeping the original as bees.toml.v<old>.bak. Prints “already version N” when nothing needs doing. bees run, tick, exec, status, issue create and issue link run the same migration automatically on startup.

bees config show [role]

Prints the resolved configuration as JSON: project, filter, github, scheduler and — for every role, or the one given — the effective prompt, skills, MCP servers, model, fallback, limits, sandbox and enabled after merging [global] with [roles.<name>]. The global-only skills_refresh is printed under every role, since it governs how each role’s skills are refreshed. github.token is never printed resolved: a "$VAR" value is shown as written and anything else as "(set)". github.private_key is shown as written, except a PEM, which is "(set)".

The JSON keys follow bees.toml; agent settings are resolved for each role. Durations print as duration strings ("45m0s"). The role-specific keys appear on the role that owns them: the reviewer carries its merge policy (auto_merge, merge_method, checks_wait, checks_poll_interval, checks_timeout, max_check_fix_rounds) and its resolved angles, brief_profile, judge_profile and angle_profiles, and the developer its commit_flags, max_size, and the best-of-N and mixture-of-experts keys. Each role also carries profiles_by_size, the resolved agent settings for its size overrides; profiles lists the named profile definitions. Reviewer phase fields show resolved five-field profiles, with review_profiles_by_size showing each size’s effective phases. host_review_policy explains that brief/angle sandbox values are ignored: the host adapter permits no commands, writes, web/network tools, inherited MCP, factory identity or writable/shared VCS. The judge applies its sandbox through the ordinary reviewer workflow.

Values the user-level defaults.toml supplied (see User-level profile defaults) are named beside what they supplied: profile_sources follows profiles, and every role carries profile_sources naming the file for each selector it set, profile and profile_by_size on every role, the reviewer’s brief_profile, judge_profile, angle_profiles and angles besides, the map selectors per entry. A selection the project’s bees.toml made, and every value built in, appear in no source map, so a role marked there runs on a profile or a selection defaults.toml chose.

bees config show
bees config show developer
{
  "path": "/src/widgets/bees.toml",
  "version": 5,
  "filter": { "label": "bees", "require_label": true, "assignee": "@me", "milestone": "", "creator": "" },
  "github": { "login": "busybees[bot]", "token": "", "app_id": 123456, "private_key": "~/.config/bees/busybees.pem", "git_name": "", "git_email": "" },
  "scheduler": { "poll_interval": "5m0s", "max_developers": 1, "max_review_rounds": 3, "...": "" },
  "profiles": { "fast": { "agent": "claude", "model": "sonnet", "fallback": "", "effort": "low", "sandbox": "none" } },
  "profile_sources": { "fast": "/home/me/.config/bees/defaults.toml" },
  "roles": {
    "reviewer": {
      "name": "reviewer",
      "model": "opus",
      "fallback": "",
      "max_turns": 200,
      "timeout": "45m0s",
      "enabled": true,
      "sandbox": "none",
      "angles": {
        "xs": ["quick_general", "docs"],
        "s": ["quick_general", "docs"],
        "m": ["general", "docs", "test_coverage", "acceptance_criteria"],
        "l": ["general", "docs", "test_coverage", "acceptance_criteria"],
        "xl": ["general", "docs", "test_coverage", "acceptance_criteria", "side_effects"]
      },
      "brief_profile": { "agent": "claude", "model": "opus", "fallback": "", "effort": "", "sandbox": "none" },
      "judge_profile": { "agent": "claude", "model": "opus", "fallback": "", "effort": "", "sandbox": "none" },
      "angle_profiles": { "docs": { "agent": "claude", "model": "opus", "fallback": "", "effort": "", "sandbox": "none" }, "...": {} },
      "profile_sources": { "profile": "/home/me/.config/bees/defaults.toml", "angle_profiles": { "docs": "/home/me/.config/bees/defaults.toml" } },
      "review_profiles_by_size": { "...": {} },
      "host_review_policy": "brief/angles: sandbox ignored; read-only checkout; no commands, writes, web/network tools, inherited MCP, factory identity or writable/shared VCS",
      "auto_merge": false,
      "merge_method": "squash",
      "checks_wait": "1m0s",
      "checks_poll_interval": "2m0s",
      "checks_timeout": "30m0s",
      "max_check_fix_rounds": 2
    }
  }
}

bees templates list

Prints every config template: the name, then a one-line summary of how it runs the factory. Reads no bees.toml and no git remote.

$ bees templates list
contributor    one contributor among many: builds the issues in its filter, a person merges
issue-driven   a person writes feature issues, the full staff builds them, a person merges
slop-factory   the full staff with auto-merge on and no approval gate on proposed features
reviewer       reviews pull requests other people open and builds nothing
planner        the two managers scope and break down issues, nobody builds

bees templates show <name>

Prints the bees.toml the template writes, which is the file bees init --template <name> would create, headed by a comment block naming the template and saying who it is for. Reads nothing either, so it works outside a git clone and before there is anything to configure. An unknown name is an error listing the names that exist.

bees templates diff [name]

Reports the settings this project’s config and a template disagree on: the key, what the config resolves it to, and what the template sets. With no name, the template the config is closest to is reported, which places a project set up without one. Differences are reported, not gated, so the exit status is 0 either way.

$ bees templates diff
/src/widgets/bees.toml vs issue-driven (closest of 5 templates)

  roles.reviewer.auto_merge   true  (issue-driven: false)

The comparison is on the resolved values rather than the file text, so a key left commented out compares equal to a template that sets it to the same default. Only the eight settings a template decides are compared; repo, filter, models, budgets and intervals are not.

$ bees templates diff contributor
/src/widgets/bees.toml matches contributor.

bees prompts show <role> [--rendered]

Without --rendered, prints the role’s built-in base prompt (the part busybees ships). With --rendered, prints the full system prompt the role would receive for this project: common preamble, base prompt, your bees.toml additions and the repository’s own project prompt files, with placeholder values for the worktree and issue.

The project prompt files are read from the main checkout (project.dir, else the checkout bees.toml sits in), which is the only one this command has. A session reads them from its own worktree, so a branch that changes bees/prompts/ renders a different prompt; when the command finds any, it says so on stderr.

bees prompts show reviewer
bees prompts show pm --rendered | less

Running the factory

bees run

The active config selects the mode: a project bees.toml runs one scheduler; a machine config runs one for every listed project. Both stay in the foreground unless -d is given. The run flags apply to every project in machine mode. Preflight runs per project; failures are logged to that project’s bees.log and reported in the live view while the other projects continue. Without --once, a machine run stays alive for reloads even if every project fails.

Runs the scheduler until interrupted. Every poll_interval (default 5m; two API calls per poll) it lists visible issues and PRs, delivers new human reviews and comments on factory PRs to the developer as mail (sending an approved issue back to bees:ready), reconciles labels (unlabelled issues go to the product manager when it is enabled, answered questions unblock), hands ready issues to free developer workers and starts the product manager, project manager and QA when they have work. It does not wait out the interval for what happens locally: a finished session wakes it, so a freed developer slot, mail one role wrote to another and the labels a session moved on GitHub are picked up at once, without polling GitHub again. Ctrl-C — or q in the live view — stops polling, starts nothing new and waits for the work already in flight to finish. An issue a developer worker holds goes on through the stages it has left — a developer session is followed by the review that belongs with it — until it is approved, escalated, out of max_review_rounds or over max_cost_per_issue; each session is still bounded by its role’s timeout. SIGTERM requests the same graceful stop. A second Ctrl-C or SIGTERM stops the running sessions immediately.

Before each project’s first poll it runs the cheap half of bees doctor: every check except the roles group, which clones skills and starts MCP servers. In project mode, a failed check prints the doctor table and exits non-zero, having started no session. Warnings do not stop a project and are not printed, so a start that is going to work stays quiet. --skip-doctor bypasses the preflight. bees tick and bees exec never run it: they are debugging commands and must stay usable on a half-configured machine.

None of the three runs inside a session ($BEES_SESSION_DIR set): a factory a bee started from its session would run agents the live view does not show, the cost budget does not count and a stop does not reach. It exits with an error naming the session instead.

Ahead of the doctor, and not bypassed by --skip-doctor, it checks that every role in the rotation asks for a sandbox bees can build here, and refuses to start naming the role when one does not: falling back to running that role unboxed would give it what it was configured to be kept away from.

$ bees run
github
  ✗ workflow labels             2 of 19 missing: bees:size/l, bees:size/xl
      → run `bees labels sync`
...
Error: preflight: 1 of 19 checks failed — fix them, run `bees doctor --fix`, or start anyway with `bees run --skip-doctor`

At start it lists the repository’s labels once and creates any workflow label that is missing, so a repository whose labels have fallen behind needs no bees labels sync first. Labels that already exist are left untouched, colour and description included. Failing to read or create them only logs a warning; the run continues.

Flag Description
-d, --daemon Detach and print the child pid; see below.
--once Do one pass and exit when the sessions it started finish. Same scheduling as bees tick; in a terminal it draws the live view rather than logging the pass, so bees tick or --no-tui is what prints a report.
--roles a,b Only run these roles (aliases accepted: pm, pjm, dev, reviewer, qa, release).
--skip-doctor Start without running the doctor preflight.
--no-tui Log to the console instead of drawing the terminal UI. A stdout that is not a terminal turns the UI off on its own.
bees run
bees run --roles dev,reviewer
bees -v run --once
bees --log-format json --quiet run

Running in the background

bees run -d                             # one project, config found from cwd
bees run --config ~/.config/bees/machine.toml --daemon

The parent prints the child pid and exits immediately. The child starts a separate process session, reads the same config and flags, and runs the preflight and poll loops. It has no terminal UI. Startup errors and console output go to a file; each project’s bees.log still records its own events. A printed pid confirms the process was spawned, not that preflight passed.

For a project run, files are under the configured state_dir:

For a machine run, files are next to the active machine config:

A lock beside each pid file prevents duplicate detached starts. Keep machine configs in separate directories when running more than one detached machine. The lock file stays on disk; a stopped process releases its lock, so a later start can replace a stale pid left by a crash.

Stop a detached project with its pid file (use your configured state path):

kill -TERM "$(cat .bees/bees.pid)"

There is no dedicated stop or reload command for a detached project. Use the project pid file with kill; machine control does not target a project run. For a machine, select its config:

bees machine reload -c ~/.config/bees/machine.toml
bees machine stop -c ~/.config/bees/machine.toml

SIGHUP to a project run rereads its bees.toml and user-level profile defaults and hands them to the running scheduler, the same reload as r in the live view, with or without the view; a --once run ignores the signal. The log says reloaded bees.toml with the file, or gives the reason the reload was refused, the file and, for a key that cannot change while the factory runs, that a restart applies it:

kill -HUP "$(cat .bees/bees.pid)"

SIGHUP in machine mode rereads the machine config and every listed project’s bees.toml. Added projects start; removed projects stop polling and finish their work in flight; a project that stays is handed its bees.toml read again, in force from its scheduler’s next pass, the way r in the live view does for one project, and keeps the shared concurrency pool. Re-adding a project while it drains waits for that scheduler to finish before starting another. The reload is all or nothing: a malformed machine config, a project file that does not load, or one that changes a key its running scheduler cannot (the list under the live view’s keys) leaves every project and the project list untouched and logs the error naming the file. Restart to apply those keys or the machine’s max_developers. --once exits after every project’s one pass and ignores reloads. Foreground machine runs accept the same signals, and their live view runs the same reload on r.

The live selector follows successful reloads in config order, keeping the selected project and its accumulated state. Removed projects stay in the selector as draining until their work finishes; their sessions can still be watched and stopped. An open transcript stays readable until Escape, even after its project leaves the selector. Messaging is disabled once the project is removed from the active list. Invalid reloads leave the view unchanged.

bees machine

These commands require an active machine config, selected by --config, then $BEES_CONFIG, then the upward bees.toml search. A project config is refused. Bare bees machine prints help.

bees machine status -c ~/.config/bees/machine.toml
bees machine cost -c ~/.config/bees/machine.toml --since 72h
bees machine reload -c ~/.config/bees/machine.toml
bees machine stop -c ~/.config/bees/machine.toml

bees machine status

Reads each configured project’s status.json and prints its config path, snapshot timestamp, worker count and last error, in config order. Missing, unreadable or empty snapshots are shown as unavailable. A recorded snapshot can outlive its scheduler; it does not prove a project is running. No scheduler starts, and no state directory is created.

bees machine cost

Reads each project’s ledger.jsonl and prints its config path, finished session count, turns and cost, followed by a total. --since defaults to 24h and accepts a Go duration, as with bees cost. A missing ledger counts as zero; a read or scan failure (an overlong line, or a line that does not parse anywhere but at the end) fails the report with the project’s path, without printing partial costs. Sessions of unknown cost are shown as bees cost shows them, and counted under the total. The report covers retained ledger entries and starts no schedulers.

bees machine stop

Sends SIGTERM to the detached daemon named by bees-machine.pid beside the active config and waits for graceful shutdown. Work in flight finishes; the command returns when the daemon removes its pidfile after all projects stop, releases its lock, or exits. There is no forced-stop timeout; Ctrl-C cancels the wait. An absent or stale pidfile with no daemon lock is a successful no-op. Stop and reload verify the PID against the kernel owner of the daemon’s lock before signaling. During startup, before the child publishes its PID and lock ownership, they ask you to retry.

bees machine reload

Sends SIGHUP through the same pidfile. A missing daemon is an error. Success means the reload was requested; check the daemon log for the result. The daemon rereads the project list, every project’s bees.toml, and the user-level profile defaults as described under Running in the background. Stop and reload need the active file to identify a machine config, but do not load its project files, so a removed project config does not block control.

Stop and reload target detached machine runs (bees run -d). Foreground runs do not write pidfiles; use their terminal or send their process a signal directly.

The live view

In a terminal, bees run draws the factory instead of logging to it: a full-screen view, redrawn as sessions start and finish and as the queues change, with a session view behind it. It subscribes to the scheduler’s event stream in the same process and re-reads status.json; it never polls GitHub itself and the scheduler never waits for it.

busybees  acme/widgets                                                                      10:03:08
╭──────────────────────────────────────────────────────────────────────────────────────────────────╮
│ Now                                                                                              │
│   role             issue pr    stage                 elapsed  turns     cost  model              │
│ ▸ developer        #12   #31   developer r2            3m20s     61    $1.79  opus               │
│   reviewer         #14   #33   pre-review checks r1      42s      9        -  sonnet (fallback)  │
│   product manager  -     -     -                          9s      4        -  sonnet             │
╰──────────────────────────────────────────────────────────────────────────────────────────────────╯
╭──────────────────────────────────────────────────────────────────────────────────────────────────╮
│ Recent                                                                                           │
│   role             issue pr    outcome                took     cost  note                        │
│   reviewer         #12   #31   changes-requested     6m14s    $1.18  tests missing for the erro… │
│   project manager  #12   -     done                   3m2s    $0.61  refined and moved to ready  │
╰──────────────────────────────────────────────────────────────────────────────────────────────────╯
╭──────────────────────────────────────────────────────────────────────────────────────────────────╮
│ Needs human                                                                                      │
│   issue waiting   title                       why                                                │
│   #44   2d        Parser drops a token        Checks on #52 still fail after 2 fix rounds: go /… │
╰──────────────────────────────────────────────────────────────────────────────────────────────────╯
╭──────────────────────────────────────────────────────────────────────────────────────────────────╮
│ Approved PRs                                                                                     │
│   pr    issue open       title                                                                   │
│   #60   #20   1d         Retry a session that hit the account limit                              │
│   #62   #22   3h         Docs: the release workflow                                              │
╰──────────────────────────────────────────────────────────────────────────────────────────────────╯
╭──────────────────────────────────────────────────────────────────────────────────────────────────╮
│ Queues                                                                                           │
│ triage          2  ready           4  in-progress     2  review          1  approved        2    │
│ blocked         0  needs-human     1  features        5  feedback        1  open PRs        3    │
│ unread mail   product manager 1, developer 2                                                     │
│ next poll     in 2m30s                                                                           │
╰──────────────────────────────────────────────────────────────────────────────────────────────────╯
↑↓ select · enter watch · k stop session · p pause · r reload · q or ctrl-c stops (sessions finish)

Now lists running sessions and review-pipeline activity. Sessions show the role, the issue and pull request, the developer worker’s stage and round, how long the session has been going, and its model: (fallback) when a retry is running on a profile its profile names as fallback. ↑/↓ move the cursor down the list and Enter opens the session view on the session it is on.

A review pipeline has one reviewer-coloured row, starting at review: brief while it gathers context and distills the brief. Once its angles are known, its stage reads, for example, review: angles 1/3 done. Failed angles count as done. The judge session replaces that row when it starts; a failed or cancelled pipeline disappears without an entry in Recent. In a machine view, these rows belong to their project and follow the project selector.

Use o on a pipeline row to open its pull request (or issue). Enter and k do nothing on it: it has no session transcript or session-stop action.

Turns is what the work item has taken: the sessions of it that have already finished, plus the assistant messages the running session’s own transcript.jsonl holds right now, recounted every few seconds. Cost is the finished sessions only, and it is - until one of them has ended and reported a cost — claude prices a session in the event that ends its stream and says nothing before it, so a claude session that ended without reaching that event (killed by a signal, most often) leaves the cost unknown rather than a cost of zero. A codex session’s cost is never known: codex reports tokens rather than a price. An opencode session’s cost is the sum of its steps’ costs, known whenever at least one step finished, zero and known for a local model that really is free; a pi session’s is the sum of its responses’ costs the same way. A session that really did cost nothing still prints $0.00.

Recent is what just happened: the sessions that have finished, newest first, with how each ended, what it said about it, how long it took and what it cost. It is a view, not a log — bees cost reads every session out of ledger.jsonl, and <state_dir>/bees.log has every record.

Needs human is every issue carrying bees:needs-human: how long it has been waiting and why the factory gave it up, in the words the escalation comment used. An issue you labelled by hand has no recorded reason and says so.

Approved PRs is what the reviewer approved and left for a person to merge, oldest first — the queue that grows when nobody is merging.

Queues is what bees status prints, read from the same status.json rather than counted a second way: every queue, whether or not anything is in it, the unread mail per role and the countdown to the next GitHub poll.

Colour is a second way to read the same rows, never the only way: everything it tells apart is already spelled out in the row’s own words. A running session is coloured by its role, a finished one by how it ended — green for the ones that worked, yellow for the ones that want a person, red for a failure and for a session that reported no outcome at all. The two panels that hold what is waiting for you say so with their title and border while they hold anything, and look like every other panel when they are empty. The colours are the terminal’s own, so they follow whatever palette you have set and are readable on a light background and a dark one alike.

The keys:

Key What it does
↑ ↓ Move the selection through every panel’s rows in turn.
enter Watch the selected session’s transcript (below).
o Open the selected issue or pull request on GitHub.
k Stop the selected session and hand its issue to a person. It asks first, naming the session: press k again to stop the one it named.
p Pause dispatch, or resume it. Unavailable while the daily budget pause is in force.
r Reload the configuration from disk: bees.toml and user-level profile defaults, or a machine config, every project’s bees.toml, and those defaults. Running sessions keep the settings they started with.
q, ctrl-c Stop the factory: nothing new starts and the work in flight finishes. Press again to stop the running sessions now, and a third time to leave the terminal early.

q and Ctrl-C stop the factory exactly as an interrupt does without the view: polling stops, nothing new starts, and the view stays up — its footer saying what it is still waiting for — until the work in flight is done. An issue a developer worker already holds is not left mid-loop: it runs on through its remaining stages, so the review that belongs with a developer session that was running still starts, and the Now panel picks it up like any other session; the work item ends where the loop ends it — approved, escalated, out of review rounds or over its cost budget. Pressing either again stops the running sessions now, killed mid-work the way a crashed scheduler would leave them, so the next bees run resumes each issue and tells its next session what was interrupted. A third press leaves the terminal and waits out whatever is still coming down with the console back.

p pauses dispatch without stopping the factory, the way the daily cost budget does: nothing new is dispatched, the sessions already running finish, and polling, human feedback and label reconciliation go on. The footer offers p pause or p resume, the header reads ⏸ paused by hand (p resumes), and status.json carries manual_paused. In a daemon’s view p pauses every project, whichever one the selector shows. The pause is kept in memory only: a restarted bees run starts unpaused. While the daily budget pause holds the factory (every project, in a daemon’s view) p is refused and not offered; a pause by hand set before the budget pause stays set when the budget pause lifts, and dispatch waits for p.

k is the key that throws work away, and asks first: the first press names the session it would stop and the second stops that one, whatever the cursor has moved on to in between. It stops it the way bees kill stops a leftover one — the process and its group, and the container of a session in the container sandbox, with an interrupted marker left in the session directory — and then labels its issue bees:needs-human with a comment saying a person stopped it, exactly as the factory giving up would. The session’s own worker ends without retrying it. A singleton session (product manager, project manager, QA) owns no issue, so stopping one stops a session and nothing more. Nothing is recorded as run either, so a singleton the factory still has work for starts again on the next pass.

r reads the configuration again from disk and hands it to the running factory, so a profile, a timeout or a budget can be changed without a restart. For one project that is its bees.toml; for a machine run it is what SIGHUP does (see Running in the background): the machine config, every running project’s bees.toml and the project list. The new settings are in force from the scheduler’s next pass, which the reload asks for at once: the next session dispatched runs on them, and a session already running keeps the model, timeout and prompt it was started with. The footer says what came of the reload and the header keeps the time of the last one, marked when it was refused. A refused reload changes nothing: a file that does not load, or one that changes a key the running factory cannot, leaves the previous configuration in force, and the footer gives the reason and the file, wrapped over as many lines as it takes:

reload refused, previous configuration kept: project.state_dir cannot change while the factory runs
(/home/me/widgets/bees.toml); restart bees run to apply it

A --once run has no next pass: its view does not reload and its footer does not offer r.

These keys cannot change while the factory runs, because what they configure was built when it started; a reload that changes one is refused naming it, and applying it takes a restart:

Key Built at start
project.repo, project.dir, project.remote the GitHub client, the clone the worktrees are made from
project.state_dir the state directory: mailbox, notes, sessions, ledger
project.branch_prefix the branch every worker and open pull request is found by
filter.* the poll query and the labels
[github] the account the factory acts as
[notes] the notes backend
[logging] the console logger
scheduler.max_developers, scheduler.workspace_root, scheduler.keep_workspaces the developer slots and the worktree manager
global.skills_refresh the skills cache

Everything else takes effect on the next pass. The machine config’s own max_developers is the shared pool and is not reloaded either.

The view wants about 30 rows to show every panel at once. In a shorter terminal the lists shrink first, each keeping one row and saying how many entries did not fit; when even that will not fit, whole panels go, from the bottom up — Approved PRs first, then Needs human, then Recent. The header, Now, Queues and the footer are the last things to go, and Queues goes on counting whatever the panels below it stopped listing.

The footer’s hints are one line. A terminal too narrow for all of them goes without the ones that only move around the view, in this order: o, ↑↓, enter, ←→. The keys that change what the factory does (k, p, r, q) stay. The example above is 100 columns wide, so it has no o GitHub; from 111 columns the footer reads:

↑↓ select · enter watch · o GitHub · k stop session · p pause · r reload · q or ctrl-c stops (sessions finish)

Between the repository name and the clock, the header scrolls a row of 🐝.

Whenever dispatch is paused, the header says so and why, next to the clock — so a factory sitting on a full queue with an empty Now panel does not read as idle. See bees status for what the numbers mean and when each pause lifts:

busybees  acme/widgets                                 ⏸ daily budget ($101.20 / $100.00)   10:03:08

While the view is up, console logging is silenced — it would scribble over the panels — and <state_dir>/bees.log gets every record, so nothing is lost. --no-tui, a redirected or piped stdout, and bees tick log as before.

Watching one session

Enter on a session in the Now panel opens its transcript, and the view keeps reading it as the session writes: the session’s own words, the tools it called and how each one answered, the way the agent’s own output reads. It is the session’s transcript.jsonl under <state_dir>/sessions/, so nothing extra is asked of the scheduler and nothing is lost when the view is closed.

busybees  acme/widgets                                                                      10:03:08
╭──────────────────────────────────────────────────────────────────────────────────────────────────╮
│ developer · developer-issue-12-r2 · issue #12 · PR #31  —  following                             │
│ ● I'll start by reading the issue and the tests around it.                                       │
│ ● Bash(go test ./internal/scheduler/ -run TestResumeStage)                                       │
│   ⎿ ok  github.com/kpenfound/busybees/internal/scheduler  0.412s (+2 lines)                      │
│ ✻ thinking                                                                                       │
│ ● Edit(internal/scheduler/developer.go)                                                          │
│   ⎿ The file has been updated.                                                                   │
╰──────────────────────────────────────────────────────────────────────────────────────────────────╯

esc back · ↑/↓ scroll · end follow · m message · q or ctrl-c stops (sessions finish)

The view follows the tail as the session writes to it. ↑/↓, PgUp/PgDn and Home scroll; scrolling away stops it following so a line arriving does not take what you are reading away, and scrolling back to the end — or End — resumes it. A session that finishes while you are reading it stays on screen, marked ended; esc goes back to the panels.

A message goes to the next session, not to the one on screen. m opens a line to type one, and Enter queues it:

message for the next developer session on issue #12 (enter queues it, esc cancels)
…
queued for the next developer session on issue #12

It is an ordinary mailbox message from human — the same channel bees mail send --from human writes and every role’s prompt calls authoritative — addressed to the role that session is running as and carrying its issue and pull request, so it reaches whichever session picks that work item up next. Nothing reaches the session on screen: a headless session reads its prompt and works to the end of it, and a follow-up turn written to its stdin is read and then ignored. The view says “queued for the next session” because that is what happened.

While a message is being typed, q is a letter rather than a stop key — Ctrl-C still stops the factory, so nothing is lost by the exception.

With the view off, every finished session prints one summary line. In text format they are the message alone, so a run reads as a report:

✓ project manager issue #12 done: "refined and moved to ready" (34 turns, $0.61, 3m02s)
✓ developer issue #12 → PR #31 opened (87 turns, $2.41, 11m37s)
✗ reviewer PR #31 changes requested: "tests missing for the error path" (52 turns, $1.18, 6m14s)
✓ developer issue #12 → PR #31 updated (41 turns, $0.98, 5m03s)
✓ reviewer PR #31 approved: "lgtm" (23 turns, $0.47, 2m41s)
⚠ issue #14 escalated to a human: Checks on #33 still fail after 2 fix rounds: go / test

With --log-format json the same line is an ordinary record carrying its numbers as fields:

{"time":"2026-08-29T10:14:02Z","level":"INFO","msg":"✓ developer issue #12 → PR #31 opened","summary":true,"role":"developer","issue":12,"pr":31,"outcome":"pr-opened","turns":87,"cost_usd":2.41,"duration":697000000000,"note":""}

--quiet keeps the summary lines, warnings and errors and drops the rest, so a service can run the factory and still see what it did.

run, tick and exec also write every record — at debug level, whatever the console flags say — as JSON to <state_dir>/bees.log. It rotates in place at 10 MiB into bees.log.1 and bees.log.2; older generations are dropped. The log file is a diagnostic, never a reason not to start: if it cannot be opened (a read-only or full state directory) the run continues with console logging only, after one warning naming the path and the reason.

bees tick [--roles a,b]

One scheduler pass, then wait for everything it started. Useful for cron-style operation or for watching a single cycle while tuning prompts. Like bees run, it refuses to run inside a session.

bees exec <role> [--issue N] [--pr N]

Runs one session for a role right now, outside the polling loop, with the same prompts and label transitions the scheduler would apply. Like bees run, it refuses to run inside a session.

Role Arguments
pm, pjm, qa None. Polls GitHub, reconciles, then runs the role once.
release None. Polls GitHub, reconciles, then runs the release manager for the lowest-numbered finished milestone; with none, it logs so and starts no session. roles.release_manager.enabled is not consulted.
developer --issue N. Runs the full developer ↔ reviewer loop for that issue.
reviewer --issue N or --pr N (the PR’s closing issue is used). Moves the issue into review and runs the loop from the review stage, the pre-review checks read included. It is an instruction, not a resumption: any stage the worker that last had the issue recorded is forgotten.
bees exec pjm
bees exec developer --issue 12
bees exec reviewer --pr 34

bees status [--json]

Shows the scheduler’s last poll time, PID and build; queue sizes per workflow state, plus feedback and features (the open bees:feedback and bees:feature issues owned by the product manager), proposals (the subset of features still waiting for a person to approve them) and open_prs; running developer workers (issue, size, stage, round, the attempt number while a session is being retried, and whether the worker resumed); a row per role; and unread mail per role. Reads status.json from the state directory, so it works while bees run is active in another terminal.

When [github] gives the factory an account of its own, the first line names it, so it is visible whose comments and labels the repository is about to see (acting_as in --json, empty when the factory uses your own gh login):

repo: acme/widgets   state: /home/kyle/src/acme/.bees   acting as: busybees[bot]

The scheduler line ends with the build bees run was started from — what bees version prints for it (version in --json, with the untruncated commit as revision):

scheduler: pid 4711, last poll 12s ago   build dev (b24a0605c2a1 modified)

Until the scheduler’s first poll succeeds, the line says so instead of a poll age:

scheduler: pid 4711, no successful poll yet   build dev (b24a0605c2a1 modified)

status.json outlives the run that wrote it. When the pid it records is not a running process, the line marks it, and running in --json is false (true while the scheduler is up):

scheduler: pid 4711 (not running), last poll 3h0m0s ago   build dev (b24a0605c2a1 modified)

The role prompts are compiled into the binary, so a running factory serves the prompts of that build: a prompt change merged to the default branch reaches no session until bees is rebuilt and bees run restarted. bees doctor compares that build against the repository and warns when the running scheduler is behind it. The segment is absent when status.json records no build.

A worker’s stage is develop, fan-out, assembler, pre-review checks, review, stack-wait or checks. Once the checks stage knows what it is waiting for, the stage names the gate — checks (required), checks (reported) or checks (none) — so a worker sitting in a 30-minute wait says whether it is waiting on the branch’s required checks, on the checks the pull request happens to report, or on nothing at all. See auto-merge.

A worker line ends with resumed when the worker took over from a session that never finished — a killed scheduler, or a hard stop — rather than starting fresh:

developer workers:
  dev-1        issue #12    m   develop           round 1              sandbox none      since 8:22AM
  dev-2        issue #14    s   review            round 2              sandbox none      since 8:31AM   resumed

The branch of a resumed worker may already carry work nobody reported, and the session that took over is told so in its prompt — see crash recovery.

sandbox is the mode the session running right now is boxed in, not the worker’s: the stages of one worker run different roles, and a role’s sandbox is its own. A worker whose first session has not started reads -.

The roles: table covers every role with what each is doing (running or idle; - for the developer and reviewer, whose work is in the workers table above), when it last ran, and how big its notes have grown — a role whose notes are getting long is a candidate for bees notes reset:

roles:
  product_manager  idle     last run 12m0s ago    notes 4.2 KB
  project_manager  running  last run 1m0s ago     notes 2.1 KB
  developer        -        last run never        notes 31.4 KB
  reviewer         -        last run never        notes 6.0 KB
  qa               idle     last run 2h0m0s ago   notes -
  release_manager  idle     last run never        notes -

Notes sizes are measured when the command runs, not read from status.json, so they are right even when the scheduler has never run. They come from the backend notes.backend names, so with backend = "neo4j" they are the sizes the service holds. --json carries them as notes_bytes (role → bytes).

A no_state queue counts issues that are visible to the factory but carry no workflow state label yet — usually ones a person just filed from the GitHub UI. The scheduler reads them as feedback and gives them bees:feedback on its next reconcile, so the row normally disappears again within the same pass and the feedback row grows by one. A workflow-state queue is omitted while it is empty (feedback, features, proposals and open_prs are always shown).

Under the scheduler line it also reports what the factory has spent since midnight, summed from the session ledger (today in --json):

today: 23 sessions, 412 turns, $8.12
today: 23 sessions, 412 turns, $8.12 (2 sessions of unknown cost)
today: ledger unreadable: .bees/ledger.jsonl line 3 does not parse: invalid character 'c' looking for beginning of value

The last form is a ledger bees cost would fail on (error under today in --json); the rest of the status is printed as usual.

With scheduler.max_cost_per_day configured, the scheduler line itself carries the rolling 24-hour spend against that budget — a different window from today: above — and says plainly when the budget has paused dispatch:

scheduler: pid 4711, last poll 12s ago   daily budget: $42.10 / $100.00   build v0.2.0
scheduler: pid 4711, last poll 12s ago   paused: daily budget ($101.20 / $100.00)   build v0.2.0

While it is paused the scheduler keeps polling and reconciling labels but starts no new session; the workers already running finish their loop. Both numbers come from status.json (budget_paused, day_spend_usd and day_budget_usd in --json), so they are what the scheduler last computed rather than a fresh sum. Sessions that reported no cost are not in the sum, and the line says how many it leaves out (day_unknown_sessions); a ledger the scheduler could not read pauses dispatch too, and the line names why (ledger_error):

scheduler: pid 4711, last poll 12s ago   daily budget: $42.10 / $100.00, 2 sessions of unknown cost   build v0.2.0
scheduler: pid 4711, last poll 12s ago   paused: ledger unreadable: .bees/ledger.jsonl line 3 does not parse: invalid character 'c' looking for beginning of value   build v0.2.0

The claude session limit pauses the factory the same way, and is reported before the budget because it is the harder stop — it names the time it lifts (limit_paused_until in --json):

scheduler: pid 4711, last poll 12s ago   paused: claude session limit until 23:50 (in 37m)   build v0.2.0

A pause from the live view’s p key comes after both (manual_paused in --json):

scheduler: pid 4711, last poll 12s ago   paused: paused by hand (p resumes)   build v0.2.0

The ready queue also carries a breakdown by size (ready_sizes in --json); issues the scheduler has not sized yet are counted as unsized:

  ready          4  (xs 1, s 2, m 1)

A work hours: line always follows it. With scheduler.work_hours configured it reports whether the factory is inside the window, the window itself, and when the next GitHub poll is due:

work hours: yes (09:00-18:00 mon-fri, America/New_York)   next GitHub poll in 2m55s

Without it, the line says so and names the cadence in force instead, because a missing line would be indistinguishable from a factory that polls around the clock:

work hours: not configured — GitHub polled every 5m0s   next GitHub poll in 2m55s

The next-poll countdown is left out while the scheduler is not running: no poll is coming.

When scheduler.timezone is unset the window is read in the machine’s local time, which is printed as the abbreviation and offset in force right now rather than the uninformative Local:

work hours: no (09:00-18:00 sat,sun, local time (PDT -07:00))

--json reports the same answer as a work_hours object, computed when the command runs:

"work_hours": {
  "configured": true,
  "in_work_hours": false,
  "window": "09:00-18:00 mon-fri, America/New_York",
  "poll_interval": "1h0m0s",
  "checked_at": "2026-08-29T20:48:00Z"
}

in_work_hours is omitted when configured is false, and poll_interval is the cadence in force at checked_at (so off_hours_poll_interval outside the window). This is the live answer. status.in_work_hours and status.next_poll next to it are the scheduler’s own record from its last pass, and go stale as soon as the scheduler stops; both are reported so the stale one is never the only one available.

Ready issues held back by an open dependency are counted on the ready row and listed below the queues:

queues:
  ready          4  (xs 1, s 3, 2 waiting on deps)

waiting on dependencies:
  #40  blocked by #37
  #46  blocked by #44

--json carries the same information as waiting_on_deps (issue number → open blockers).

Two queue counts also have their detail in --json, though the text output prints the counts alone: needs_human names each escalated issue with the reason the factory recorded when it gave up, and approved names each pull request waiting for a person to merge, oldest first. The live view is what draws them as panels.

Degraded operations

A factory operation that keeps failing — assigning what a session created, editing a label, the poll itself — is reported under a short, stable name, so a half-broken run does not look like a healthy one. The operations failing right now are listed after the last error line:

degraded:
  assign           12 consecutive failures over 3h10m   last: GraphQL: Projects (classic) is being deprecated
  label            1 failure   last: gh: HTTP 403 (Resource not accessible by integration)

The section is absent entirely when nothing is failing. A single success clears the operation’s streak and removes its line. --json carries the same entries as status.degraded (op, count, first, last, last_error, escalated).

Three consecutive failures of one operation also print one line into the run’s output — once per streak, not once per pass:

⚠ assign has failed 3 times in a row: GraphQL: Projects (classic) is being deprecated

Nothing else happens: the scheduler does not retry, back off or stop, and no issue is commented on — there is no issue to comment on for a factory-wide operation, and no role can fix a broken credential or a missing label. This is visibility only.

The mailbox

Roles talk to each other only through the local mailbox in <state_dir>/mail. The scheduler delivers messages by including them in the prompt of the session working on the referenced issue or PR and marks them read afterwards.

bees kill [--dry-run] [--scheduler] [--grace 5s]

Cleans up after a crash: finds the agent sessions started by bees, terminates them together with their process groups (MCP servers, shells), removes stale pid files, removes the temporary worktrees bees created under the workspace root, and resets the worker list in status.json.

Sessions are found two ways: from the pid file each running session keeps in its <state_dir>/sessions/<id>/ directory, and from the process table, limited to sessions of this state directory — a claude or codex process counts only when it carries a session marker (the --name bees-… argument every claude session is started with, or the shell_environment_policy.set.BEES_SESSION_DIR= override every codex session gets; the older mcp_servers.bees.env.BEES_SESSION_DIR= marker also counts) and its command line references <state_dir>/sessions/. An opencode session carries no such marker — it is given its session directory through OPENCODE_CONFIG, which the process table does not show — and a pi session shows nothing but pi, because pi renames its process as it starts; both are found through their pid file. The scan reports no session of another project’s factory, whichever config you point bees kill at.

Pid files are cross-checked against that scan: a pid the scan did not match is kept only when the process table says it runs an agent, so a pid reused by an unrelated process after a reboot is discarded, never killed. A pid file is scoped by where it lies, though, not by what the process says: nothing in an agent’s command line names a state directory, so a reused pid that happens to be another factory’s opencode or pi session is stopped along with the session the file was written for.

A session in the container sandbox is found a third way, because its agent runs in the container rather than on the host: the engine is asked which of its running containers carry the bees.session label, whose value is the session directory, and stopping such a session removes its container. Such a session also leaves the pid of the MCP server bees runs on the host for it in mcp-server-pid, and that server is stopped with it. A container, an engine client or a server whose session is otherwise gone is stopped on its own.

A session in the sbx sandbox is found only through the MCP server bees runs on the host for it: its sbx exec client is not recognised as a session, so the pid file naming the client is discarded as a reused pid and the client is never stopped. A server still running is stopped and the session marked; the sandbox is left running either way. <session dir>/sandbox-name names it, and sbx rm --force <name> stops and removes it.

Each session it stops through a pid file or through its container is also marked as stopped, by an interrupted file in the session’s directory. The next session for that issue is then told the session before it was stopped on purpose rather than lost with the machine, and — when it was a developer session — that the branch may carry its unreported work.

It refuses to run while a bees run scheduler is alive (killing sessions under a running scheduler would corrupt its state); pass --scheduler to stop the scheduler too. To stop one session of a factory that is still running, use k in the live view: it stops the session the same way and hands that session’s issue to a person, which is what a running scheduler needs and this command does not do.

Flag Meaning
--dry-run Show what would be killed and removed, in the conditional tense (would kill, would remove worktree), and delete nothing: the stale pid, container id and MCP server pid files a real run clears away are left in place. Reading status.json still upgrades a state directory written by an older bees, as it does for every command.
--scheduler Also stop a running scheduler (found via the pid in status.json).
--grace 5s Time to wait after SIGTERM before SIGKILL.
bees kill --dry-run
bees kill
bees kill --scheduler      # the scheduler itself is hung

bees mail send (sessions)

Flag Description
--to <role> Recipient role (required).
--from <name> Sender. Default $BEES_ROLE; humans must pass one, e.g. --from human.
--subject <text> Subject line.
--body <text> Body.
--body-file <path> Read the body from a file; - for stdin.
--issue N Issue the message is about. Default $BEES_ISSUE.
--pr N Pull request the message is about. Default $BEES_PR.
--in-reply-to <id> Id of the message being answered.

Attach --issue/--pr whenever possible: that is how the scheduler routes the message to the right developer session, and how an answer unblocks a bees:blocked issue.

bees mail talks to the state directory of $BEES_STATE_DIR when it is set (that is how a session reaches its own mailbox), but an explicit --config wins over it, so bees -c other/bees.toml mail send ... inside a session reaches the other project. The confirmation line names the state directory the message landed in: sent <id> to <role> (<state dir>).

bees mail send --to project_manager --issue 12 --subject "Which auth scheme?" --body "JWT or sessions?"
bees mail send --to developer --pr 34 --issue 12 --subject "Review round 1" --body-file review.md
bees mail send --from human --to product_manager --subject "Priority" --body "Ship billing before reports."
bees mail send --from human --to developer --issue 12 --body "Keep the CLI flag names as they are."

bees mail list

Flag Description
--to <role> / --from <name> Filter by recipient or sender.
--issue N / --pr N Filter by referenced item.
--unread Only undelivered messages.
--full Print whole messages instead of one line each.

Unread messages are marked with *.

bees mail read <id>

Prints one message.

Notes

<state_dir>/notes/<role>.md is a role’s memory between sessions with the default notes.backend = "file": a session reads it with the notes_read tool and replaces it with notes_write before it finishes, and these commands are how a person reads and steers it. With notes.backend = "neo4j", notes_read and notes_write act on Neo4j Agent Memory instead; these commands still act on the file, which no session then reads. See Notes files. Roles accept the usual aliases (pm, pjm, dev, review, qa).

bees notes show <role>

Prints the notes file (nothing when the role has never run).

bees notes edit <role>

Opens the notes file in $VISUAL, else $EDITOR, else vi, creating it first if needed, and exits with the editor’s status. It needs a terminal, so it refuses to run inside a session ($BEES_SESSION_DIR set) — sessions edit their file directly.

bees notes reset <role>

Moves the notes file to <state_dir>/notes/archive/<role>-<timestamp>.md, prints that path and leaves a fresh file behind. Use it when a role has accumulated advice that no longer applies; nothing is lost, the archive stays.

bees notes add <role> [text]

Appends one bullet to the notes file, creating it when needed:

bees notes add developer "Always run dagger check before committing"
bees notes add pm --body-file vision.md

Pass --body <text> or --body-file <path> (- reads stdin) instead of the argument for longer text. A note spanning several lines keeps its line breaks; every line after the first is indented by two spaces so the whole note stays inside one bullet. Like bees mail, show, reset and add find the state directory from $BEES_STATE_DIR before falling back to bees.toml, so a session can append to its own notes without a config file.

Creating issues

bees issue create (sessions, and humans)

Creates an issue the way the factory wants it. Roles are told to use this instead of gh issue create; it is equally handy for people.

Flag Meaning
--title Required.
--body / --body-file Body text, or a file (- for stdin).
--parent N Make the new issue a native GitHub sub-issue of feature N and inherit its milestone.
--related N Inherit the milestone of issue N without attaching (a bug found while working on N, a feature distilled from feedback N). Exclusive with --parent.
--milestone T Set the milestone explicitly (overrides inheritance).
--bug Bug work item (bees:bug).
--feature Feature issue for the product manager (bees:feature, plus bees:proposal unless scheduler.feature_proposals = false; no state label).
--ready Work item is already detailed: bees:ready instead of bees:triage.
--blocked-by N Repeatable. Prefixes the body with a Blocked by #N line, so the scheduler does not build the issue ahead of N (see Dependencies). No GitHub dependency relationship is created.
--label L Extra label (repeatable).

What it always does: adds the visibility label and, when filter.assignee is set, the assignee; adds the kind label; adds bees:triage (or bees:ready) to work items — feature issues get no state label; resolves the milestone as explicit → parent/related issue’s milestone → filter.milestone; and, with --parent, attaches the issue as a sub-issue (three API calls: parent details, create, attach). Bees never create or edit milestones; release_ship closes the milestone it ships. --milestone only picks among the ones people made, and the one role that passes it is the product manager, for a feature spawned from an agreed design (From an agreed design to several features).

bees issue create --parent 12 --title "Export as CSV" --body-file body.md      # work item under feature #12
bees issue create --bug --related 34 --title "Crash on empty input" --body "…"  # bug in #34's milestone
bees issue create --feature --related 40 --title "Search" --body-file body.md   # feature from feedback #40
bees issue create --title "Fix typo in README" --ready                          # fast-tracked work item
bees issue create --parent 12 --blocked-by 37 --title "Order the queue" --body-file body.md  # waits for #37

Attaches existing issue M as a sub-issue of feature N (for example a bug filed by QA that turns out to belong to a feature in progress).

Becoming a sub-issue carries the feature’s milestone across, exactly as --parent does on bees issue create, so an issue attached after the fact lands in the same release as one created under the feature. It only ever fills in a milestone: an issue that already has one keeps it, and the command says which milestone it set, if any. Refuses a parent that is still a proposal (unless scheduler.feature_proposals = false), or that a person has put in planning (bees:planning).

Reporting outcomes

bees done <status> [-m note] [--pr N] [--issue N] (sessions)

The last command every session runs. Writes outcome.json into $BEES_SESSION_DIR; the scheduler reads it to decide what happens next. A session that ends without an outcome is treated as failed. Statuses are validated against $BEES_ROLE:

Role Valid statuses
product_manager done, idle, failed
project_manager done, idle, failed
developer pr-opened --pr N, pr-updated --pr N, question, failed
reviewer approved, changes-requested, failed
qa done, failed

pr-opened and pr-updated require a PR number (--pr or $BEES_PR). question and changes-requested are only honoured if the session actually sent the corresponding mail; otherwise the issue is escalated to a human.

bees done pr-opened --pr 34
bees done changes-requested
bees done approved -m "Clean implementation, tests cover the edge cases"
bees done failed -m "Could not get the test-suite to run: missing DATABASE_URL"

bees mcp serve (sessions)

Runs the built-in MCP server on stdio (or over HTTP, below). You never start it yourself: bees hands it to every session as the server named bees (in mcp.json for claude, as mcp_servers.bees overrides for codex, in the mcp table of the configuration file OPENCODE_CONFIG names for opencode, in the pi-mcp.json pi-mcp-adapter reads for pi), and the agent starts it as <bees binary> mcp serve with the session’s BEES_* variables. The name bees is reserved — a [global.mcp.bees] or [roles.<role>.mcp.bees] entry in bees.toml fails validation.

For a container session the runner starts it on the host itself, as bees mcp serve --listen <address> with $BEES_MCP_TOKEN set: it prints listening on <address> and serves the same tools over HTTP to a client presenting that token, which is how a session without the bees binary reaches them.

The server is backed by the same code as the commands above, so a tool and its command do exactly the same thing. Claude Code exposes the tools as mcp__bees__<name>:

Tool Arguments Same as
mail_send to, subject, body, optional issue, pr, in_reply_to bees mail send
mail_list optional unread, issue, pr bees mail list --full
issue_create title, body, optional parent, related, milestone, bug, feature, ready, labels, blocked_by bees issue create
issue_link parent, child bees issue link
done status, optional note, pr, issue bees done
notes_read none bees notes show <role> for the session’s own role; the notes are not in the prompt, so a session reads them first
notes_write text no command: replaces the role’s notes with the whole text (bees notes add appends one bullet instead); an empty text is refused
report_factory_error title, detail no command: writes a draft to <state_dir>/feedback/<id>.json when scheduler.report_factory_errors is on, and answers that nothing was recorded when it is off

The rest are GitHub operations: the same gh calls a role would build by hand, with the factory’s rules applied.

Tool Arguments Offered to Does
issue_view optional number every role Prints an issue: state/kind/size labels, milestone, parent feature, body, then every comment oldest first, marked as a bee’s or a person’s.
pr_view optional number every role Prints a pull request: title, head → base, draft flag, body, required-check summary with the failed check names, then every review and comment a person left.
comment number, body every role Comments on an issue or pull request, appending the role’s <!-- bees:<role> --> marker unless the body’s last line already is it. A marker quoted anywhere else — including as the last line, > <!-- bees:<role> --> — does not suppress it, so the marker line is always the poster’s.
issue_edit_body number, body product_manager, project_manager Replaces an issue body. Refuses a bees:feature or bees:feedback issue for anyone but the product manager.
issue_set_state number, state (ready|blocked), size (xs…xl, required for ready) project_manager Moves a work item out of bees:triage in one label edit, replacing any existing size. Refuses an issue that is in any other state, naming it.
issue_question number, waiting product_manager Adds or removes bees:question. Refuses anything that is not a feature or feedback issue.
submit_review optional number, event (approve|request-changes|comment), body reviewer Submits one GitHub review on a pull request, appending the reviewer’s marker as comment does: the findings of the review, as a comment review on a developer’s pull request (the verdict goes to the developer by mail) and with the verdict as the event on a requested review. Refuses an issue.
file_bug title, body, optional related, override qa Files a bees:bug work item as issue_create would, after scoring it against every issue in the repository, open and closed. When any of them scores high enough nothing is filed and the ranked candidates come back instead; override: true files without asking again.
release_ship milestone number release_manager Requires closed issues, no open issues or related open PRs, and a valid unused tag title; tags the current main head, creates a release with generated notes, then closes exactly that milestone. Reports completed steps on partial failure.

The issue and pull request tools refuse an item they act on when it does not match the filter, and each of their writes is a refusal or a single gh call. release_ship checks open PRs across the repository and makes three sequential writes; its response lists the steps completed if a later step fails. file_bug creates an issue rather than acting on one: its optional related only supplies a milestone, and is not checked against the filter, exactly as issue_create’s is not.

issue and pr default to $BEES_ISSUE/$BEES_PR, so a session rarely passes them (issue_view and pr_view default their number the same way). The schemas depend on $BEES_ROLE: done’s status enum is exactly the role’s valid outcomes (a developer sees pr-opened, pr-updated, question, failed; a reviewer approved, changes-requested, failed), and an unknown or empty role gets the full tool set with no enum, so the server is usable by hand.

bees mcp tools [role]

Prints the tools a role’s session sees, with the enum of every constrained parameter — the part that differs between roles:

$ bees mcp tools developer
mcp__bees__comment          Comment on an issue or pull request
mcp__bees__done             Report the session outcome
    status: pr-opened | pr-updated | question | failed
mcp__bees__issue_create     Create a factory issue
mcp__bees__issue_link       Attach an issue to a feature
mcp__bees__issue_view       Read an issue
mcp__bees__mail_list        Read the mailbox
mcp__bees__mail_send        Send mail to another role
    to: product_manager | project_manager | developer | reviewer | qa | release_manager
mcp__bees__notes_read       Read your notes
mcp__bees__notes_write      Replace your notes
mcp__bees__pr_view          Read a pull request
mcp__bees__report_factory_error Report an error the factory caused

The tool set differs too: the project manager also sees issue_edit_body and issue_set_state (state: ready | blocked, size: xs | s | m | l | xl), the product manager issue_edit_body and issue_question, the reviewer submit_review (event: approve | request-changes | comment), and QA file_bug.

Without a role argument it uses $BEES_ROLE, and without that it prints the unconstrained tool set.

Reviewing a pull request

bees review reviews a GitHub pull request from several angles at once. Its settings are ~/.config/bees/config.toml: the agent it runs as, where your reviewer notes and review artifacts live, and how a review ends when the command line does not say. Below it, ~/.config/bees/defaults.toml fills the keys it leaves out with the reviewer settings of a bees.toml. The repository’s own context.toml says which angles run there. Reviewing a pull request describes how a review runs, what it keeps, and every key of the files.

bees review <pr> [--post mode | --report] [--config path]

Reviews a pull request: a github.com URL, owner/name#123, or a bare number when the current directory is a checkout of the repository. The review gathers the pull request’s context, runs the distiller session that briefs it, runs one read-only session per angle the brief’s size calls for and context.toml enables, merges what they found into one list, most severe first, and joins the list against the rules in your reviewer notes. Each step prints a line as it goes, and while the angles run, at a terminal, one row per angle under it shows a spinner until that angle’s session ends, then a mark saying it finished or failed and how long it took. The review is written into its artifact directory as it goes too, so a review that stopped after the angles has its brief and their sessions; one angle failing is printed and skipped, and every angle failing stops the review.

$ bees review acme/widgets#7
gathering the context of acme/widgets#7
gathered 6 items from diff, pr_body, linked_issues, style_files
distilling the brief
the review is /Users/me/.config/bees/reviews/acme/widgets/7/20260910-150405
reviewing a size m change from 4 angles: general, docs, test_coverage, acceptance_criteria
  ✓ general               2m14s
  ✓ docs                  1m02s
  ✓ test_coverage         1m51s
  ✓ acceptance_criteria   1m37s
3 findings
  1 finding hidden by your reviewer notes

--no-tui, or a stdout that is not a terminal, draws nothing: each angle prints a line as it starts and one as it ends instead, which is what a script or a CI log gets. Ctrl-C at the terminal stops the sessions and waits for them to end.

Triage follows, as triage below describes it, or by an agent with --agent (see factory mode), and then the review ends one of five ways with what you selected:

End What happens
approve the selected findings are posted as review comments, and the pull request is approved
comment the same comments, as a comment-only review
reject the same comments, as a review that requests changes
report the selected findings are printed as a markdown report, and nothing is posted
discard nothing is posted and nothing is printed

--post approve, --post comment, --post reject or --report chooses; with neither, the output key of ~/.config/bees/config.toml does, and its default, ask, asks at the end:

1 selected, 1 dismissed, 1 deferred, 0 undecided of 3 findings

1 finding selected. a approve and comment · c comment only · r reject and comment · o output the report · d discard
> a
acme/widgets#7: approved with 1 comment

The three that post submit one review in one call, never one comment at a time. A finding is posted as a comment on its lines when the pull request’s diff has them, on the side of the diff it is about, with its suggestion as a suggestion block when GitHub can apply one there (the new side). A finding on lines the diff does not have, and one about the change as a whole, goes into the review’s summary instead, with where it points. A comment-only or request-changes review needs something in it: with nothing selected it is refused, and at the prompt you are asked again. An approval with nothing selected approves and says nothing. The review is posted with the authentication github.token names, or your own gh login without it.

The report is the same selections as markdown, for pasting wherever you like: the pull request, then each finding with where it points, its severity and category, its text and its suggestion as a code block.

--config reads a global configuration other than ~/.config/bees/config.toml.

bees review triage <pr> [--post mode | --report] [--config path]

Opens the latest review of a pull request and triages what is still undecided. The pull request is a github.com URL, owner/name#123, or a bare number when the current directory is a checkout of the repository.

Each undecided finding is shown in turn, most severe first: its id, severity, angle and category, the file and lines it is about, its text, its suggestion and evidence, and any question already asked about it with the answer. One key followed by return decides it:

Key What it does
s select: the finding goes into the review’s output as written
e open the comment text in $VISUAL or $EDITOR, then select it
d dismiss: leave it out, and record why in your reviewer notes
f defer: leave it out of this review, and record nothing
a ask the angle that found it a question; a finding the answer turns up joins the queue
n leave it undecided for now
q stop
$ bees review triage acme/widgets#7
acme/widgets#7: the review started 20260910-150405

[1 of 3 findings undecided] 1a2b3c4d · high · test_coverage · missing test
internal/review/gather.go:12-14

Gather has no test for a source that cannot read

the acceptance criterion says a source that cannot read something does not
fail the review, and nothing exercises it

s select · e edit and select · d dismiss · f defer · a ask · n next · q quit · ? help
> d
reason (recorded in your reviewer notes): covered by the table test in gather_test.go

At a terminal, triage opens as a full-screen view beside the diff instead of the prompts above, the same keys pressed without return. --no-tui, or a stdout that is not a terminal, keeps the console shown above.

Every decision is written into the review’s artifact directory as it is taken, so stopping loses nothing: run the command again and it offers what is still undecided. The latest select, dismiss or defer on a finding is the one that counts. An ask decides nothing; the finding is shown again with the answer under it. A dismissal needs a reason: it is the line your reviewer notes are made of. A decision that cannot be written into the artifact directory stops the command with the error, and the finding is still undecided the next time.

The review then ends the way bees review’s does, with everything selected so far, in this run or an earlier one: posted, printed as a report, or discarded, as --post, --report, the output key or the prompt at the end says.

--config reads a global configuration other than ~/.config/bees/config.toml.

Factory mode

--agent on bees review <pr> and on bees review triage <pr> hands triage to an agent session instead of you, for a review nobody sits at a terminal for. The agent takes the same four actions on the same findings: what it selects goes into the review’s output, what it dismisses is appended to your reviewer notes with its reason, and every decision is written into the review’s artifact directory as it is taken. --instructions tells it what you want from the review.

$ bees review acme/widgets#7 --agent --instructions "Hold the change to its issue. Never approve."
gathering the context of acme/widgets#7
...
3 findings
triage round 1: 3 findings undecided
  select 1a2b3c4d: Gather has no test for a source that cannot read
  dismiss 5e6f7a8b: the README is rewritten by the docs change that follows
  ask 9c0d1e2f: Does the rename reach a caller outside the package?
    No: every caller of Gather is in internal/review.
triage round 2: 1 finding undecided
  defer 9c0d1e2f: The change renames Gather, which the issue did not ask for
1 selected, 1 dismissed, 1 deferred, 0 undecided of 3 findings
the agent chose to end the review: comment
acme/widgets#7: commented with 1 comment

The agent triages in rounds. Each round is a new read-only session, run as the provider and model of ~/.config/bees/config.toml and told the brief, the findings still undecided with the answers to what it asked, the rules in your reviewer notes about the repository, and what its last answer could not do: a dismissal without a reason, a finding the review does not have. Another round follows one that asked a question, had something refused, or left findings undecided. Triage stops when nothing is undecided, when a round takes nothing, or after five rounds, and what is still undecided is there for bees review triage to offer.

The review ends as --post, --report or the output key says. Where they leave it to ask, the agent chooses one of the five ends, as the instructions say. Without instructions about it, the agent is told to request changes when a selected finding must be fixed before the change merges, to comment when anything else is selected and to discard when nothing is, and to approve only when the instructions allow it. An agent that chooses no end it can take discards: nothing is posted.

bees review consolidate [--notes path] [--dry-run]

Every finding you dismiss during triage is appended to your reviewer notes, one line per dismissal:

- [acme/widgets] [general] [naming] receiver names are short here

consolidate reads those lines and writes the patterns that repeat into rules. Dismissals of the same repository, angle and category whose reasons read alike are one pattern: dismissed twice, it becomes a rule that ranks its findings down; three times or more, one that drops them.

$ bees review consolidate
/Users/me/.config/bees/reviewer-notes.md: 7 dismissals, 2 rules

added:
- [acme/widgets] [general] [naming] drop: receiver names are short here (3 dismissals)

A review joins its findings against the rules before triage sees them. A finding a rule is about is dropped, or ranked down one severity, and the angle sessions of the next review are told what has been dismissed from their angle before. A rule with no text after the action is about every finding in its repository, angle and category, and * in any of those three matches whatever it is.

The rules live between two markers in the notes file, and that block is the only part of it bees writes. Nothing in the block is deleted or reworded: a rule you rewrote, or whose action you changed, stays as you wrote it and only its count moves. --notes works on a file other than the configured one, and --dry-run prints what consolidation would write without writing it.

Evals

bees eval [role] [--case name] [--profile name]

Runs the whole factory against each case under ./evals/, with an in-memory GitHub and a local origin, and grades the result with the case’s test. It prints one row per case (result, score, why the run stopped, cost, turns, duration, profile), writes <state_dir>/evals/<timestamp>/report.json, and exits non-zero when any case fails. The sessions are real agent sessions.

With a role, it runs that role in isolation against the cases under ./evals/<role>/, the way bees exec runs one session: the scheduler is scoped to that role and the seeded GitHub state and mailbox stand in for the rest of the factory, which stays configured so that routing does not move. Such a case is graded by the checks it declares — the outcome, labels moved, mail sent, issues created or closed, a pull request opened — and by rubrics a grader session scores, which fills the SCORE column.

--case runs one case, from evals/ or from evals/<role>/. --profile runs every role on one profile from bees.toml or ~/.config/bees/config.toml, which defaults.toml fills below itself. Without it the eval uses the profiles bees.toml selects, or the provider and model of ~/.config/bees/config.toml when there is no bees.toml, or the selection defaults.toml’s [global] and [roles] tables make when there is no config.toml either, or the built-in profile when there is no defaults.toml either. Grader sessions ignore --profile: they run on the agent the global review configuration supplies — config.toml, with defaults.toml below it — so scores stay comparable between runs. Like bees run, it refuses to run inside a session.

bees eval --case hello --profile fast
bees eval developer

Evals describes the case layout and the grading.

Misc

bees cost [--since 24h] [--by role|issue|day] [--json]

Reports what finished sessions cost, summed from <state_dir>/ledger.jsonl: one JSON line per session, appended when it ends, with its role, issue, PR, turns, cost, duration and outcome. The numbers are what the agent reported; nothing is reconciled against billing. The ledger holds scheduler.retention_period of sessions, and at least the last 24 hours, so a --since longer than that reports only what is still there.

$ bees cost --since 72h --by role
role             sessions    turns       cost
developer              12      214      $6.10
product_manager         1       11      $0.32
reviewer                9       74      $1.70
total                  22      299      $8.12

--since is a Go duration (default 24h). --by issue groups by issue number and collects sessions that belong to no issue (the singleton roles) under -; --by day groups by local calendar day. --json prints the same groups plus the total. An empty ledger prints no sessions recorded.

A session whose agent reported no cost (a codex session, or one killed before its result event) is never a $0.00: a group of nothing else reads unknown, a group that mixes them marks the sum of the rest with a +, and a line under the total counts them (unknown on each group in --json):

$ bees cost --by role
role             sessions    turns       cost
developer              12      214     $6.10+
reviewer                9       74    unknown
total                  21      288     $6.10+
10 sessions reported no cost (+): not in the totals

The ledger is read fail-closed: a line that does not parse anywhere but at the end fails the command, naming the file and the line, rather than printing a total that is short of a session. The final line is the one exception, since a crash mid-write leaves one, and it is ignored.

$ bees cost
Error: .bees/ledger.jsonl line 3 does not parse: invalid character 'c' looking for beginning of value

bees version

Prints bees <version>, resolved from the binary itself:

| Build | Output | |—|—| | A binary installed from a published Go module version | The module version Go recorded: a tag (bees v0.2.0) or a pseudo-version. | | go install ./cmd/bees in a clone | bees dev (b24a0605c2a1): the 12-character revision, with ` modified appended when the working tree has uncommitted changes. | | A build whose module version is (devel) but that carries VCS stamps | bees dev (b24a0605c2a1) — the 12-character commit, with modified appended when the working tree was dirty. | | Built with -ldflags “-X main.version=v1.2.3” | bees v1.2.3. The override wins over everything else. | | A binary from a [GitHub release](/busybees/releasing.html) | bees v0.2.0 — the tag the release was cut from, stamped through that same override. | | No build information at all | bees dev`. |

bees completion <shell>

Generates shell completion scripts (bash, zsh, fish, powershell).