# `bees` command reference

`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`](#bees-mcp-serve-sessions) 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](configuration.md#machine-config-several-projects). 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](#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`](configuration.md#logging). |
| `--log-level <debug\|info\|warn\|error>` | Console log level. Default `info`; `$BEES_LOG_LEVEL`, then [`logging.level`](configuration.md#logging). |
| `-h, --help` | Help for any command. |

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

With [the live view](#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](configuration.md#github), 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`](#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](templates.md) 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](configuration.md).

```sh
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](configuration.md#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]`](configuration.md#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`](#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:

- It never touches an item that does not carry the base label. That is the
  safety rule that makes bees usable in a repository shared with people, and
  it is enforced on selection and again per item before any write. Selection
  is on the label alone, never on who wrote the issue: a feature issue a
  person filed with the `bees` label and no assignee is adopted exactly like
  one the factory created.
- It never adds or removes a label, and it never edits `bees.toml`. `--fix`
  moves items into the filter; deciding what the filter should be is yours.
- With `filter.require_label = false` it does nothing at all and says so in
  one line. Without a base label there is no way to tell the factory's work
  from everyone else's, and "assign every issue in the repository" is not a
  repair. If you run with an assignee-only filter, bring items into it by
  hand.
- One item it cannot repair is reported on its own line and does not stop the
  others.

### `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](configuration.md#machine-config-several-projects), 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`](configuration.md#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](configuration.md#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.

```sh
bees config show
bees config show developer
```

```json
{
  "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](templates.md): 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](configuration.md#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.

```sh
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](configuration.md#machine-config-several-projects) 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](#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`](#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](configuration.md#sandboxing) 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](#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. |

```sh
bees run
bees run --roles dev,reviewer
bees -v run --once
bees --log-format json --quiet run
```

#### Running in the background

```sh
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`:

- `bees.pid`: the child pid, removed after graceful shutdown.
- `bees-daemon.log`: appended stdout and stderr, including startup errors.

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

- `bees-machine.pid`: the child pid, removed after graceful shutdown.
- `bees-machine-daemon.log`: appended stdout and stderr for the whole process.

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):

```sh
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:

```sh
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](#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:

```sh
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](#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](configuration.md#machine-config-several-projects), selected
by `--config`, then `$BEES_CONFIG`, then the upward `bees.toml` search. A
project config is refused. Bare `bees machine` prints help.

```sh
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](#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](#watching-one-session) 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](architecture.md#running-a-session) 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](configuration.md#cost-budgets) 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`](#bees-kill---dry-run---scheduler---grace-5s) 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](#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`](#bees-status---json) 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:

```json
{"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](workflow.md#releases); 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. |

```sh
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](workflow.md#sizing), 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]`](configuration.md#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`](#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](roles.md#customising-a-role) 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`](#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](configuration.md#rolesreviewer-only-checks-and-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](architecture.md#the-developer-worker).

`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`](configuration.md#global-and-rolesname) 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](roles.md#notes-files) 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`](configuration.md#notes) 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](#bees-cost---since-24h---by-roleissueday---json) (`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`](configuration.md#cost-budgets) 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](configuration.md#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](workflow.md#sizing)
(`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`](configuration.md#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:

```json
"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](workflow.md#dependencies) 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](#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](configuration.md#sandboxing) 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](configuration.md#the-sbx-mode) 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](#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. |

```sh
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>)`.

```sh
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.md#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](workflow.md#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](workflow.md#from-an-agreed-design-to-several-features)).

```sh
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
```

### `bees issue link --parent N --child M`

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.

```sh
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](configuration.md#the-container-mode) 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`](configuration.md#scheduler) 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](workflow.md#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](workflow.md#asking-for-a-review-of-any-pull-request). 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](workflow.md#what-the-factory-can-see), 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](review.md) 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](#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.

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

[Evals](evals.md) 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`](configuration.md#scheduler) 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](releasing.md) | `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).
