One file configures a factory: bees.toml, in the root of a git clone of the
project being built, or elsewhere with project.dir naming the clone (see
[project] below). Without --template, bees init writes it with every
option listed and the optional ones commented out at their default, so
configuring is uncommenting and editing lines; see
config templates for the alternative. bees config validate
checks the file and bees config show [role] prints the settings each role
ends up with.
The file starts with a version key, followed by these tables:
| Table | Purpose |
|---|---|
[project] |
The git remote, repository, default branch and state directory |
[filter] |
Which GitHub issues and pull requests the factory can see |
[github] |
The GitHub account the factory acts as |
[scheduler] |
Concurrency, polling, retries, budgets and the review loop |
[logging] |
Console log format and level |
[notes] |
Where a role’s notes live: files, or Neo4j Agent Memory |
[global] |
Prompt, skills, MCP servers, profile selection and environment for every role |
[roles.<name>] |
The same keys per role, plus a few that only one role takes |
[profiles.<name>] |
Agent, model, effort and sandbox settings selected by [global] or a role |
An unknown key anywhere in the file is a load error, so a typo cannot pass as a default. Every validation error names the key and what to change.
Durations are written the way Go reads them: "30s", "5m", "1h30m".
bees review reads none of this file. Its settings are
~/.config/bees/config.toml and the project’s context.toml, with
defaults.toml below the first; Reviewing a pull
request describes all three.
Jev review settings
Set OPENROUTER_API_KEY for the bees process to enable the optional
Jev boost. With the variable unset or empty, reviews
make no Jev request and add no record or log line. The factory uses
agentcore’s default settings and one Judge per process across developer
reviews, requested reviews and all project schedulers, including projects
added or restarted through reload. A cooldown in one project applies to
the others. There is no bees.toml key for Jev.
For bees review, put overrides in ~/.config/bees/config.toml:
[jev]
url = "https://openrouter.ai/api"
model = "~typesafe/jev-latest"
api_key_env = "OPENROUTER_API_KEY"
timeout = "10s"
These are the defaults. The factory does not read this table. url is an
HTTP(S) base URL without credentials, query or fragment; the endpoint is
<url>/v1/systemone. model is at most 128 characters without whitespace.
api_key_env is an environment variable’s name, never its secret value.
timeout bounds each request, must be positive and cannot exceed "1m".
Unknown keys and invalid values fail with an error naming the key, even
with the boost off.
Jev sees a guide, the brief’s change description, acceptance criteria,
style rules and touched areas, changed-file paths and line counts,
generated-file exclusions, reviewer-notes rules and complete findings.
It never receives the diff, diff.patch or checkout file contents. Text
quoted in findings is sent as written. The key goes only to the configured
endpoint as a bearer credential.
Findings with a probability below 0.3 are removed; the rest reach triage
or the factory’s judge session in descending probability order, preserving
ties. jev.json in the review artifact records the outcome, fallback reason
and detail, models, probabilities, kept and full eliminated findings, usage,
request count, duration, version and threshold. The progress or factory log
reports ranked and eliminated counts, or the fallback reason.
Invalid settings, oversized or rejected requests, timeouts, rate limits, outages, unusable responses, cooldowns and cancellation of the Jev request alone leave the unboosted list intact. A timeout or outage allows one retry. Cancelling the review itself retains ordinary cancellation handling. Reviewing a pull request describes context shortening, recording and shared cooldowns.
User-level profile defaults
Every project load also reads defaults.toml beside that review configuration:
$XDG_CONFIG_HOME/bees/defaults.toml when XDG_CONFIG_HOME is an absolute
path, otherwise ~/.config/bees/defaults.toml. The file is optional. It lets a
machine with several projects define agent profiles, their role mappings and
the GitHub account once:
version = 5
[profiles.fast]
agent = "claude"
model = "sonnet"
effort = "low"
[global]
profile = "fast"
profile_by_size = { xs = "fast", s = "fast" }
[roles.reviewer]
brief_profile = "fast"
angle_profiles = { docs = "fast" }
angles = { xs = ["quick_general"] }
[github]
login = "busybees[bot]"
app_id = 123456
private_key = "~/.config/bees/busybees.pem"
The file accepts only version, [profiles.<name>], global.profile,
global.profile_by_size, every role’s profile and profile_by_size, the
reviewer’s brief_profile, angle_profiles, judge_profile and angles,
and [github] with every key it has in bees.toml. Any other key is an
error. It has its own migration history, begins
at the current version shown above, and must include that version.
The project bees.toml is the nearer layer and wins. A same-named profile in
the project replaces the user profile whole. Map settings merge entry by
entry: a project entry replaces the user entry for that size or angle, while
the remaining user entries stay. [github] is one account and is taken whole
or not at all: a project whose bees.toml has a [github] table takes
nothing from the user one. An empty [github] table makes that project act
as your own gh login. Validation happens after this merge, so the
two files may refer to each other’s profiles; an error names the file that set
the bad key. Invalid values and refused keys in defaults.toml are still
errors even when the project would replace them.
bees config show names the file beside every value it took from
defaults.toml, per entry for the map selectors, so a role running on a
profile the project file never mentions says where both came from. See
the config show section for the shape.
SIGHUP, the live view’s r key, and every other operation that reloads a
project read both files again. A machine config itself does not inherit these
defaults, but every project it lists does. bees review reads the same file
below its own config.toml and takes the reviewer’s profiles and selectors,
and [github], from it; Reviewing a pull request lists what it
takes.
One bees process managing several projects reads a
machine config instead, which lists the
bees.toml of each project.
Machine config: several projects
A machine config is a separate file that lists the bees.toml files of the
projects one bees process manages, and holds the settings that span them:
projects = [
"~/src/foo/bees.toml",
"../bar/bees.toml",
"/srv/factories/baz.toml",
]
max_developers = 3
retention_period = "72h"
- A relative path is relative to the directory of the machine config. A
leading
~/is your home directory. - Every entry must name an existing file that loads as a valid
bees.toml. A missing file, a directory, an empty entry, a project listed twice, or a project file that fails to load is an error naming the entry, for exampleprojects[1] = "../bar/bees.toml": .... - The list must not be empty, and any key besides
projects,max_developersandretention_periodis a load error. Project settings stay in each project’sbees.toml, so each project keeps its own state directory, mailbox and notes. max_developerscaps the developer slots in use across every project listed: the total of what theirscheduler.max_developerspools have out at once, a requested review and every attempt of a fan-out counted like a worker. Each project keeps its ownmax_developers; the machine’s is on top of them. Unset or0is no cap across projects, and a negative value is an error. When the cap is reached and a slot frees up, it goes to the project that has waited longest for one, not to the project that just gave it up, so a busy project cannot starve the others. See Several projects in one process.retention_periodisscheduler.retention_periodfor every listed project whosebees.tomldoes not set it. A project that sets its own keeps it. Unset leaves those projects on"24h"; zero, a negative value or a string that is not a duration is an error.- The file has no
versionkey.
bees finds a machine config the same way it finds bees.toml: --config,
then $BEES_CONFIG, then a file named bees.toml in the working directory
or a parent. It reads the file’s keys to tell the two kinds apart: a file with
a top-level projects key is a machine config. bees config validate checks
either kind. A command that works on one project refuses a machine config
with an error saying which kind of file it found.
You edit the file by hand. bees run --config /path/to/machine.toml runs
every listed project. Add -d to detach; SIGHUP reloads the project list and
every project’s bees.toml.
See Running in the background.
version
version = 5
The format version of the file, not of bees. bees init writes the current
one, 5. A file without the key is version 0.
- A file newer than the running bees understands is refused with
upgrade bees. - An older file is migrated on load, one version at a time.
bees run,tick,exec,status,issue createandissue linkthen write the migrated file back, keeping the original asbees.toml.v<old>.bakand logging that they did.bees config migratedoes the same and nothing else, so the diff can be read before the factory starts;bees config validateonly reports that a migration is pending. - Migrations rewrite the text of the file, so comments and the commented-out
defaults survive. The migration from 0 to 1 adds the
versionkey and changes nothing else. The migration from 1 to 2 removesroles.reviewer.stagesand leaves a comment in its place: no stage maps onto a review angle, so the reviewer gets the defaultangles. The migration from 2 to 3 movesagent,model,fallback_model,sandbox,effortandmodel_by_sizeinto named[profiles.<name>]tables and replaces them withprofileandprofile_by_size; scopes without those settings use the implicit built-in profile. The migration from 3 to 4 converts reviewer phase model overrides to named phase profiles, cloning the ordinary reviewer fallback profile’s five fields and replacing its model. Equal profiles are reused; size-specific fallback still applies to phases with no override. The migration from 4 to 5 replacesfallback_model, a model of the profile’s own agent, withfallback, the name of another profile: each profile withfallback_model = "X"getsfallback = "<name>_fallback"and a new[profiles.<name>_fallback], the profile withmodel = "X"and no fallback of its own, so the migrated file behaves as it did. A profile that named nofallback_modelhas no fallback afterwards, where aclaudeprofile fell back tosonnetbefore; name one to keep that.
Adding an optional key never bumps the version. Renaming or removing a key, or changing what one means, does, and the release notes of the bees version that bumps it say what changed.
A bees release can also start refusing a value it accepted before, without a
migration. The file then fails to load with an error naming the key, because
the value is yours and bees cannot guess the replacement. The MCP server name
bees is one such value (see MCP servers).
[project]
| Key | Type | Default | Description |
|---|---|---|---|
remote |
string | "origin" |
Git remote the factory fetches from and pushes to. A name; spaces and / are rejected. |
repo |
string | derived | GitHub repository as owner/name. Derived from the remote’s URL when unset (https, ssh:// and git@github.com: forms). Set it when the URL is not a github.com one. |
default_branch |
string | derived | Branch developers branch from, reviewers diff against and QA tests. Read from the remote’s HEAD when unset. |
state_dir |
string | ".bees" |
Where mail, notes, session logs and scheduler state live. A relative path is resolved against the directory holding bees.toml. bees init adds it to .gitignore when it is inside the clone. |
branch_prefix |
string | "bees/" |
Prefix of developer branches: bees/issue-12. |
dir |
string | bees.toml’s directory |
The git clone the factory works in, when it differs from the directory holding bees.toml. A relative path is resolved against the directory holding bees.toml. |
What the product is and how to build, test and run it are not configuration. Every role reads the repository’s own README, CONTRIBUTING, AGENTS.md and CLAUDE.md, and keeps what it learns in its notes file.
The main checkout is dir when set, else the clone holding bees.toml.
Every session runs in a temporary git worktree cut from it, so remote has
to point at the GitHub repository.
[filter]
The filter decides which issues and pull requests the factory sees and touches.
Configured criteria are ANDed, and everything the factory creates stays
visible: it is made to match label, assignee and milestone, and the
account the factory acts as always passes creator.
| Key | Type | Default | Description |
|---|---|---|---|
label |
string | "bees" |
The factory’s label. It is the base name of every workflow label (bees:triage, bees:ready, …) and, while require_label is true, the visibility gate. Spaces and colons are rejected. |
require_label |
bool | true |
With false, assignee, milestone and/or creator alone decide visibility. The factory still puts label on everything it creates. |
assignee |
string | "" |
Only see items assigned to this GitHub login. "@me" is resolved to the machine’s own gh login at startup, even with [github] set. Everything the factory creates is assigned to this login so it stays visible. |
milestone |
string | "" |
Only see items in this milestone, by title. Also the milestone for issues the factory creates when neither --parent nor --related gives one, and the one put on the pull requests it opens. People manage milestones; bees inherit them, or pick among them for the features of an agreed design. |
creator |
string | "" |
Only see items opened by this GitHub login or by the account the factory acts as (github.login, else your own gh login). An issue or pull request the factory opens is authored by that account, so it is visible whatever creator says. |
require_label = false without assignee, milestone or creator is
rejected: it would make every open issue in the repository visible.
A factory acting as a GitHub App that should pick up only the issues one person files, plus the ones it opens itself:
[filter]
creator = "kyle"
[github]
login = "busybees[bot]"
app_id = 123456
private_key = "~/.config/bees/busybees.pem"
One person running busybees for their share of a team repository needs no special label on the issues:
[filter]
label = "kyle-bees" # still the base of the kyle-bees:* labels
require_label = false
assignee = "@me"
An issue assigned to you with no state label and neither kyle-bees:feature
nor kyle-bees:feedback gets kyle-bees and kyle-bees:feedback on first
sight and goes to the product manager as feedback; label it kyle-bees:triage
or kyle-bees:ready yourself to have it built. Because every label carries
the prefix, two people can run two factories in one repository with two
labels.
Workflow labels
Every label is derived from filter.label, shown here for bees. bees init
and bees labels sync create them in GitHub.
| Label | Meaning |
|---|---|
bees |
Visible to the factory |
bees:feature |
Feature issue owned by the product manager, which makes it detailed enough and breaks it into work items. Outside the state machine |
bees:bug |
Bug work item, filed by a developer, the reviewer, QA or a person. It says what the issue is, not where it goes |
bees:feedback |
Feature idea, product feedback or bug report for the product manager. Outside the state machine |
bees:question |
The product manager is waiting for a person to answer on a feature or feedback issue; removed by the orchestrator when they reply |
bees:proposal |
A feature issue a bee wrote. It sits next to bees:feature, and a person removes it to approve the breakdown |
bees:planning |
A person and the product manager are still agreeing a feature or feedback issue; the product manager discusses and breaks nothing down. Not a state label; only a person sets or removes it. See Planning with the product manager |
bees:planned |
A person ended planning: the scope is agreed and the product manager breaks the issue down on its next run. Not a state label; only a person sets or removes it |
bees:priority |
A person wants this next: dispatched before the rest of the bees:ready queue. Not a state label. People set it; the project manager may add it to a work item that unblocks the factory itself, and the product manager carries one from a feedback issue onto the work item it creates from it |
bees:review-requested |
On a pull request, not an issue: a person asks the reviewer for one review pass, whoever opened the pull request. Not a state label; the orchestrator removes it as the review starts. See Asking for a review of any pull request |
bees:triage |
Needs refinement by the project manager |
bees:ready |
Detailed enough for a developer |
bees:in-progress |
A developer worker owns it |
bees:blocked |
Waiting on an answer to a question |
bees:review |
Pull request open and under review |
bees:approved |
Reviewer approved; waiting for a person to merge |
bees:needs-human |
The factory gave up, or a person is holding the issue. A person may add it on top of another state label to hold the issue where it is; it wins while it is there |
An issue also carries at most one size label, independent of its state. The
project manager sets it when it moves a work item to bees:ready, and the
orchestrator adds bees:size/m to a ready issue that has none. See
Sizing.
| Label | Meaning |
|---|---|
bees:size/xs |
One file, obvious change, no design |
bees:size/s |
A few files, clear approach, existing tests cover it |
bees:size/m |
A feature slice across several packages, needs new tests |
bees:size/l |
Crosses subsystems or needs a design decision |
bees:size/xl |
Too big for one pull request; split it instead |
[github]
With the table unset, the factory acts as whatever account the machine’s gh
is logged in with, and everything it writes on GitHub looks like it came from
the person running it. [github] gives the factory an account of its own: a
GitHub App, which GitHub shows as a bot on everything the factory writes.
[github]
login = "busybees[bot]"
app_id = 123456
private_key = "~/.config/bees/busybees.pem"
git_name = "busybees[bot]"
git_email = "234567+busybees[bot]@users.noreply.github.com"
| Key | Type | Default | Description |
|---|---|---|---|
login |
string | "" |
The account the factory acts as. For a GitHub App it is the App’s slug followed by [bot]. bees init and bees doctor check it against the credential, bees status reports it, and the orchestrator reads every comment that login posts as the factory’s own. |
app_id |
int | 0 |
The GitHub App’s ID, from its settings page. Set with private_key. |
private_key |
string | "" |
The GitHub App’s private key: the path of the .pem file GitHub generated (~ is your home directory), a "$VAR" or "${VAR}" reference to a variable holding the PEM, or the PEM itself. bees reads it when it starts. A reference that expands to nothing, or a file it cannot read, fails the start with the key named. |
token |
string | "" |
In place of app_id and private_key, a token for login, passed as GH_TOKEN to every gh call the orchestrator makes and to every session. A "$VAR" or "${VAR}" value is read from the environment bees runs in. A reference that expands to nothing is a load error naming the variable. |
git_name |
string | "" |
Author and committer name for the commits developer sessions make (GIT_AUTHOR_NAME, GIT_COMMITTER_NAME). |
git_email |
string | "" |
Author and committer email for those commits (GIT_AUTHOR_EMAIL, GIT_COMMITTER_EMAIL). |
login goes with either app_id and private_key or token, and bees
refuses any other combination. To share one App across projects, put the
table in defaults.toml instead: a project
with no [github] table of its own takes it whole, and so does
bees review. git_name and git_email are an identity
rather than a credential, so each may be set alone, and whichever is unset
leaves that half of the commit identity to the machine’s own git
configuration.
Setting up the GitHub App
- On GitHub, open Settings → Developer settings → GitHub Apps → New GitHub
App. The name you give it becomes its slug, the last part of
https://github.com/apps/<slug>. Any homepage URL will do. Clear Webhook → Active: bees polls and needs no webhook. -
Under Repository permissions, set:
Permission Access Contents Read and write Issues Read and write Pull requests Read and write Checks Read-only Commit statuses Read-only Workflows Read and write, only if developers may change files under .github/workflowsMetadata is read-only and always granted. Issues cover labels, comments, milestones and sub-issues.
- Create the App. On its settings page, copy the App ID into
app_id, then Generate a private key. GitHub downloads a.pemfile: move it somewhere only you can read, such as~/.config/bees/, and pointprivate_keyat it. - Install App, on the account that owns the repository, with access to
the repository
project.reponames. - Set
loginto the slug followed by[bot]. For commits GitHub attributes to the App, setgit_nameto the same login andgit_emailto<id>+<login>@users.noreply.github.com, with the id fromgh api 'users/busybees[bot]' --jq .id.
bees init checks the App before the factory uses it: GitHub accepts the App
ID and key, login is the App’s, the App is installed on the repository, and
a token it mints can read the repository. bees doctor asks the same
questions, and two more: that the App can write an issue and that it can push
a branch.
Tokens
The bees process that runs sessions holds the private key, and no session
does. From it, bees mints the
App’s installation tokens, each restricted to project.repo and good for an
hour. It mints one when it first needs one, and the next only once that one
has two minutes left, however many calls come in between.
Sessions never get the key. A session with gh and git access gets the App’s
gh first on its PATH and a git credential helper, both of which read the
current token from <state_dir>/github/token. When that token has expired,
they ask the bees process that started the session for a new one and wait
for it, so a session that runs for hours keeps working. The same goes for the
bees commands a session runs. This works the same way on the host and in a
container or sbx sandbox, which mount the state directory.
A session with sandbox = "none" can read any file your user can, the .pem
included. To keep the key out of its reach, hold it in a variable instead,
which no session is given:
private_key = "$BEES_GITHUB_APP_KEY"
export BEES_GITHUB_APP_KEY="$(cat ~/.config/bees/busybees.pem)"
The tokens reach only project.repo, so leave
scheduler.report_factory_errors off with a GitHub App: the
reports go to kpenfound/busybees.
A token
token in place of app_id and private_key makes the factory act as the
account the token belongs to, and login is that account’s login. Use a
fine-grained personal access token scoped to the one repository: read and
write on Issues, Pull requests and Contents, read on Metadata. A classic token
with the repo scope also works. With scheduler.report_factory_errors on,
the token also needs issue write on kpenfound/busybees.
bees init checks the token before the factory uses it: GitHub accepts it, it
belongs to login, and it can read the repository. bees doctor asks the same
questions, and whether the account can write an issue and push a branch.
Repository access does not imply either. A fine-grained token’s permissions
sit on top of the repository role, so a token can read the repository as an
admin and still be refused every label edit or every push.
A session runs with GH_TOKEN set to the token and git configured to answer
https pushes through gh auth git-credential. When token is a "$VAR"
reference the session is also given that variable, holding the resolved
token, because the bees commands a session runs load bees.toml
themselves. It goes into the session’s environment and never into a file.
What the account covers
The account covers everything the factory does on GitHub: polling, label
edits, review requests, the escalation comment, bees init’s label creation,
bees doctor’s checks, bees issue, the built-in MCP tools, and a session’s
own gh pr create, gh api and git push. With git_name and git_email
set, its commits are the factory’s as well.
Your own credential helper is reset for a session’s pushes, so it cannot
answer them, and your stored credentials are neither read nor written. The
helper only steers https remotes: on an ssh:// or git@github.com: remote
the commits are the factory’s but the push authenticates with the machine’s
ssh key. The full list of what a session is given is under
Exported into every session.
Comments the factory posts still end with the
comment marker, because [github] is optional and
with it unset every comment arrives under your own login. With it set, the
orchestrator reads a comment as the factory’s when it carries the marker or
when login wrote it, so the escalation comment, which carries no marker, is
not mistaken for a person’s. People mention a GitHub App as @busybees, by
its slug, and the factory reads that as a mention of busybees[bot].
filter.assignee = "@me" still means you. It says whose work the factory picks
up, and is resolved with the machine’s own gh login before any token is used,
in the orchestrator, the MCP server and bees doctor alike. GitHub does not
assign issues to a GitHub App, so leave filter.assignee unset or name a
person.
[scheduler]
| Key | Type | Default | Description |
|---|---|---|---|
poll_interval |
duration | "5m" |
How often GitHub is polled. A poll costs two API calls (gh issue list, gh pr list); see API budget. Also the minimum gap between two runs of one singleton role. |
rate_limit_backoff |
duration | "15m" |
How long to pause polling after a poll fails with a GitHub rate-limit error, instead of retrying after poll_interval. Also how long the whole factory pauses when a session hits the claude session limit and no usable reset time came with it; see The claude session limit. |
max_developers |
int | 1 |
Concurrent developer workers. Each owns one issue and runs its developer, reviewer and checks stages one after another, so reviewer concurrency follows developer concurrency. 0 means the default; a negative value is rejected. |
max_review_rounds |
int | 3 |
Developer and reviewer rounds before an issue is escalated with bees:needs-human. 0 means the default; a negative value is rejected. |
retries |
int | 1 |
Extra attempts a session gets after failing for infrastructure reasons: it timed out, ran out of turns, hit an API error or rate limit, or the agent crashed. A session that ran and reported with bees done, failed included, is not retried, and neither is one that hit the claude session limit. 0 disables retrying; 0 to 5. See Escalation. |
retry_delay |
duration | "10m" |
Wait before a retry. "0s" retries at once; a negative value is rejected. |
retry_with_fallback |
bool | true |
Run the retry on the profile the role’s resolved profile names as its fallback, agent included; a second retry runs on that profile’s own fallback, and so on down the chain. A profile without one reruns as it was. |
triage_batch_size |
int | 5 |
Most issues handed to the project manager in one session. 0 means the default. |
notes_consolidate_every |
int | 10 |
Sessions a role runs between two in which it is also asked to consolidate its notes. 0 means the default; a negative value is rejected. |
notes_max_bytes |
int | 32768 |
Ask for consolidation early, whatever the session count, once a role’s notes are larger than this. Measured in the backend notes.backend names. 0 means the default; a negative value is rejected. |
dispatch_order |
string | "small-first" |
Which bees:ready issue a free developer takes next: small-first, oldest or large-first. Ties go to the older issue, and an issue without a size ranks as m. Issues carrying bees:priority come first whatever this says, and issues already in flight (bees:in-progress, bees:review, a bees:ready issue with an open pull request, a bees:approved issue whose checks were interrupted) are resumed before new work. See Sizing. |
max_large_in_flight |
int | 1 |
How many bees:size/l issues developer workers may hold at once. A large issue over the cap is skipped and the worker takes the next issue that fits. 0 means no cap; a negative value is rejected. |
pr_fix_conflicts |
bool | true |
Hand an open pull request that conflicts with the default branch back to its developer: the developer is mailed from orchestrator to merge, resolve, test and push, and an approved issue goes back to bees:ready ahead of new work. See Conflicts with the default branch. |
pr_keep_updated |
bool | false |
Do the same when a pull request is merely behind the default branch. |
stacked_prs |
bool | false |
Build a blocked_by chain of work items under the same feature as a stack of branches and pull requests, each depending on its predecessor’s, instead of independently. false keeps every work item branching from the default branch on its own, as it does today. See Stacked features. |
review_assigned_prs |
bool | false |
Ask the reviewer for one pass over every open pull request in the filter whose head branch does not start with project.branch_prefix, without waiting for bees:review-requested. With filter.assignee set, that is the pull requests assigned to the factory. A new push to one earns another review. See Asking for a review of any pull request. |
report_factory_errors |
bool | false |
Let a role record a draft issue about an error the factory itself caused: a tool that misbehaved, a prompt that contradicted the code, an orchestrator mislabel it had to work around. The report_factory_error tool writes the draft, scrubbed by the role of repository names, tokens, paths and people, to <state_dir>/feedback/<id>.json, and every full pass files the queue against the busybees repository: a report that looks like an issue already there is a comment on it, one that looks like nothing is a new issue with no label and no assignee. Off, the tool records nothing, says so, and nothing is filed. |
feature_proposals |
bool | true |
A feature issue a bee creates is a proposal: it carries bees:proposal and a person approves it by removing the label. false lets a bee break its own features down without a person’s approval: bees issue create --feature writes no bees:proposal, and --parent and bees issue link do not refuse a parent for carrying one. See Feature issues. |
notify |
string list | [] |
GitHub logins and org/team slugs the factory turns to when it needs a person. No leading @, at most one /. See Notifying a person. |
product_manager_interval |
duration | "1h" |
Minimum time between product manager runs. Unread mail in its inbox starts one earlier. |
qa_interval |
duration | "30m" |
Minimum time between QA runs. QA runs when something was merged since its last run (the first run always happens); mail in its inbox starts one earlier. The merged-PR query runs at most once per interval. |
max_cost_per_issue |
float | 0 |
USD one work item may cost across every session run for it. 0 is unlimited; a negative value is rejected. See Cost budgets. |
max_cost_per_day |
float | 0 |
USD the whole factory may spend over a rolling 24 hours. 0 is unlimited; a negative value is rejected. |
max_cost_per_day_resume_percent |
float | 100 |
How far the rolling 24 hours has to fall back before dispatch starts again, as a percentage of max_cost_per_day: at 80 a factory paused at $100.00 stays paused until the window is under $80.00, rather than resuming at $99.99 and going straight over again. 100 (the default) resumes as soon as the window is under budget, 0 means that default, and a value outside 0-100 is rejected. See Cost budgets. |
max_cost_per_session |
float | 0 |
USD one session may cost. 0 is unlimited; a negative value is rejected. |
keep_workspaces |
bool | false |
Leave temporary worktrees on disk after a session, for debugging. |
workspace_root |
string | "" |
Directory temporary worktrees are created under. Empty means bees under the system temp directory. |
retention_period |
duration | "24h" |
How long the state directory keeps data after it goes stale: the session directories and issues/work-<hash>.json of a closed issue, counted from its pull request merging or, without one, the issue closing, and ledger.jsonl lines older than this, never within the last 24 hours, which max_cost_per_day reads. Retention is always on: zero or a negative value is rejected. Unset, the machine config’s retention_period applies when there is one. |
work_hours |
string | "" |
Daily window during which GitHub is polled every poll_interval, as "HH:MM-HH:MM" on a 24-hour clock. Empty polls around the clock, and the three keys below are ignored. See Work hours. |
off_hours_poll_interval |
duration | "1h", or poll_interval when that is longer |
How often GitHub is polled outside work_hours. Must be at least poll_interval. |
work_days |
string list | ["mon","tue","wed","thu","fri"] |
Days the window applies to, as lowercase three-letter names from mon to sun. At least one, and each must be a known day. |
timezone |
string | "" |
IANA name the window is read in, such as "America/New_York". Empty means the machine’s local time. |
Notifying a person
By default the factory and the people it works for share one GitHub account, so
nothing it writes notifies anybody: you wrote the comment, and GitHub sends no
mail for your own. notify says who to reach:
[scheduler]
notify = ["kpenfound", "myorg/bees-team"]
- The
bees:needs-humanescalation comment starts with@kpenfound @myorg/bees-team. See Escalation. - The product manager’s
bees:questioncomments start with the same line. - A pull request the reviewer moved to
bees:approvedis waiting for a person to merge it, so a review is requested from every entry.
The review request is best effort: a failure is logged and the pull request
still reaches bees:approved. GitHub refuses to request a review from a pull
request’s own author, and with a shared account the configured login usually
is the author, so a login often gets the mention and not the request. Teams
are always accepted; list one if you want the request too.
Work hours
Most polling exists to notice what people did: new issues, feedback, reviews,
merges. Outside working hours that is rare, so work_hours polls GitHub less
often then:
[scheduler]
poll_interval = "5m" # inside the window
off_hours_poll_interval = "1h" # outside it
work_hours = "09:00-18:00"
work_days = ["mon", "tue", "wed", "thu", "fri"]
timezone = "America/New_York"
Only the GitHub polling cadence changes. The scheduler still ticks every
poll_interval, and a finished session wakes it in between; a tick that is not
due for a poll runs a local pass over the last poll’s issue and PR lists (see
The scheduler loop). Everything driven by
the local mailbox, which is the developer and reviewer loop, the checks stage
and an answered question moving bees:blocked back to bees:ready, runs at
full speed at every hour. bees tick and bees exec ignore the window.
The poll before the window opens is scheduled for the moment it opens, so the
first poll of the day is at 09:00, not an interval later.
A rate limit never speeds polling up. After a rate-limited poll the next one is
due after the longer of rate_limit_backoff and the interval in force, so off
hours with off_hours_poll_interval = "8h" that is 8h.
A window whose start is later than its end wraps midnight and belongs to the
day its start falls on: "22:00-06:00" with work_days = ["fri"] covers
Friday 22:00 through Saturday 06:00 and nothing else. A window whose start
equals its end is rejected, as is a window that is not "HH:MM-HH:MM", an
unknown or empty work_days, a timezone the zoneinfo database does not know,
and an off_hours_poll_interval shorter than poll_interval.
bees status prints a work hours: line either way, with the cadence in force
and when the next poll is due. See bees status.
API budget
The orchestrator is frugal with the GitHub API, because the sessions call gh
freely on top of it:
| What | Cost | When |
|---|---|---|
| A poll | 2 calls (gh issue list, gh pr list) |
every poll_interval, or every off_hours_poll_interval outside work_hours |
| Human PR feedback | 3 calls per PR (reviews, review comments, comments) | only for PRs whose updatedAt moved since the last look |
| Human issue comments | 1 call per issue | only for issues whose updatedAt moved since the last look: bees:in-progress, bees:review, bees:approved and bees:blocked unconditionally, and, once [github] names an account to mention, bees:triage, bees:ready, bees:feature and bees:feedback too, to look for an @-mention. A pass with no [github] login configured, or one that sees an issue with no recorded time, records the time and fetches nothing |
| Product-manager has-work check | 1 issue view per feedback or feature issue |
only for issues whose updatedAt is newer than the last product manager run. Noticing that a feature’s sub-issues have all closed costs nothing: it compares the numbers recorded on the last run with what the poll found open |
| Product-manager run | 1 issue view per open feedback or feature issue, 1 REST call per open feature (sub-issue progress) and 1 GraphQL call per open work item (parent feature) |
every run |
| Planning mode | 1 extra issue view per bees:planned issue the has-work check did not already fetch |
every product manager run while an issue is agreed and not yet acted on |
| QA merged-PR check | 1 call | at most once per qa_interval |
| Checks | 1 call per poll of a checks stage, 2 when the branch requires no check | every roles.reviewer.checks_poll_interval while waiting |
| Visibility backstop | 2 list calls | after every session |
| Refreshing what a session changed | 1 issue view per issue |
after a session, for each issue it created or relabelled through the MCP server; none when it changed no issue |
| The marker audit | 1 comment read per issue or pull request | after a session, for its issue, the pull request it was given or opened, and each issue it changed, only with [github] set, and nothing at all without it |
| Parent feature lookup | 1 GraphQL call per triage item, per open work item and per developer session | per project manager run, product manager run, developer session |
bees issue create --parent |
3 calls (parent details, create, attach as sub-issue); --related 2; plain 1 |
whenever a role files an issue |
| Worker stage transitions | a few issue view, pr view and issue edit calls |
per transition |
An idle factory costs two calls per poll. When GitHub does rate-limit the
process, polling pauses for rate_limit_backoff and tries again.
What the factory spends on Anthropic is a separate budget, capped by the three
max_cost_* keys.
Cost budgets
All three budgets are 0 by default, which is unlimited. They are spent
against the session ledger, the numbers
bees cost reports,
so a retried session counts like any other:
[scheduler]
max_cost_per_issue = 25.00 # every session run for one work item
max_cost_per_day = 100.00 # whole factory, rolling 24 hours
max_cost_per_session = 10.00 # a single session
A running session is never interrupted on cost. Each budget is enforced at the first moment the factory can act on it:
- Per issue, between the stages of a developer worker. The session that took
the issue over budget finishes and its work stays on the branch; the worker
then stops and the issue is escalated with what it spent (“Issue #12 has
cost $26.40 across 7 sessions, over the
max_cost_per_issuebudget of $25.00”). - Per day, before anything is dispatched. At or over the budget the scheduler
keeps polling and reconciling labels but starts no session; workers already
running finish their loop. Dispatch starts again once the window has fallen
back to
max_cost_per_day_resume_percentof the budget, by default the budget itself, so at80a factory paused at $100.00 resumes under $80.00 rather than at $99.99. The pause is logged once, the release names the threshold it crossed, andbees statusnames the pause while it lasts. - Per session, after the session ended. An over-budget session is treated as
failed whatever it reported, so it is retried once, on the resolved
profile’s
fallbackwhenretry_with_fallbackis on. Two over-budget sessions in a row for one work item escalate it: the role’smax_turnsortimeoutis the wrong shape for that work.
Budgets are money, not turns: max_turns already caps how long one session may
go on.
The ledger is read fail-closed. A session whose agent reported no cost (a
codex session, or one killed before its result event) is entered with
cost_unknown set: it counts as a session, adds nothing to the dollars, and
while the last 24 hours hold one the budget’s log line, bees status and the
live view say how many the sum leaves out (“daily budget: $42.10 / $100.00,
2 sessions of unknown cost”). A ledger line that does not parse anywhere but
at its end fails every read of the ledger with the file and the line, and
that, with max_cost_per_day set, pauses dispatch like a budget reached:
nothing the daily budget gates starts until the ledger reads again, and
bees status shows paused: ledger unreadable: <file> line <n> does not
parse. With max_cost_per_issue set, an issue whose spend has to be seeded
from the ledger at that moment is escalated the same way an issue over the
budget is, with the escalation naming the line. With neither set the line
fails bees cost and the today: line of bees status alone. Remove or
repair the line to resume; a torn final line, what a crash mid-write leaves,
is ignored. See
bees cost.
The claude session limit
Every role shares one Anthropic account, so when one session runs out of
capacity the whole factory has. claude reports it two ways and either counts:
a rate_limit_event in the session’s stream whose status is neither allowed
nor allowed_warning, or, from a session that failed without reporting an
outcome, a result text naming a session or usage limit (“You’ve hit your
session limit · resets 11:50pm (America/Detroit)”). The text is only read this
way when the session reported nothing, because it is the session’s own prose.
A session that ends that way is not retried, since every attempt would hit the same wall, and its issue is not escalated, since the limit says nothing about the work: the issue keeps its state label and is picked up afterwards. The scheduler pauses all dispatch, developers and singletons alike, until the limit resets. Running sessions finish on their own, and polling and label reconciliation carry on.
The pause lasts until the reset time the event carried, with two limits: a
reset that is missing or already past falls back to rate_limit_backoff, and
one more than 8 hours ahead is clamped to 8 hours. The pause is logged when it
starts and when it lifts, and bees status names the time it lifts. It is held
in memory only, so restarting bees run clears it and the first session
re-learns the limit.
[logging]
[logging]
format = "text" # text | json
level = "info" # debug | info | warn | error
| Key | Type | Default | Description |
|---|---|---|---|
format |
string | "text" |
Console log format: text or json. |
level |
string | "info" |
Console log level: debug, info, warn or error. |
Logging is a property of the bees process, so the table is top-level and
applies to every command. It is the lowest-priority source: a flag beats an
environment variable, which beats bees.toml, which beats the default. So
bees run --log-format text gives a readable terminal in a project whose file
says json, and -v wins over level = "info".
Commands that never read bees.toml, such as bees version and bees done,
and any command run against a file that fails to load, use the flag,
environment and default settings only.
There is no quiet key. --quiet is a shorthand for one invocation; level =
"warn" is the service-shaped equivalent, and it also drops the one-line
session summaries that --quiet keeps.
bees run in a terminal draws the live view instead of logging and silences
console logging while it is up; --no-tui, a redirected stdout and every
other command log as this table says. The bees.log file in the state
directory is not configurable: it gets every record at debug level, in JSON.
See bees run.
[notes]
[notes]
backend = "file" # file | neo4j
# neo4j_url = "https://memory.neo4jlabs.com/v1"
# neo4j_api_key = "$BEES_NEO4J_API_KEY"
| Key | Type | Default | Description |
|---|---|---|---|
backend |
string | "file" |
Where the notes_read and notes_write tools keep a role’s notes: file (the state directory) or neo4j (Neo4j Agent Memory). |
neo4j_url |
string | "" |
The base URL of the Neo4j Agent Memory REST API, including its version segment: the hosted service’s (https://memory.neo4jlabs.com/v1) or a self-hosted deployment’s. Required, and must be an http(s) URL, with backend = "neo4j". |
neo4j_api_key |
string | "" |
An API key for neo4j_url, written as a "$VAR" reference so the secret is not in this file. Required with backend = "neo4j"; a reference that expands to nothing fails to load, naming the variable. Redacted as written in bees config show. |
bees neither runs nor embeds Neo4j Agent Memory; with backend = "neo4j"
the notes tools talk to the REST API at neo4j_url, and so do bees status
and the scheduler consolidation trigger when they measure a
role’s notes. neo4j_url and neo4j_api_key are ignored with
backend = "file", so they can stay in the file across a switch.
bees notes show|edit|reset|add are the exception: they always act on the
state directory’s file, whatever backend is.
[global] and [roles.<name>]
[global] and each [roles.<name>] table take the same keys. The role name
is one of product_manager, project_manager, developer, reviewer, qa,
release_manager. The CLI accepts aliases such as pm, dev and release;
the TOML keys do not. release_manager is disabled by default. Explicitly opt
in before using it because it can publish a GitHub release:
[roles.release_manager]
enabled = true
| Key | Type | Default | Description |
|---|---|---|---|
prompt |
string | "" |
Text appended to the role’s built-in prompt. |
prompt_file |
string | "" |
Path, relative to bees.toml, whose contents are appended after prompt. The file must exist when the file loads. |
skills |
string list | [] |
Skills by git URL. See Skills. |
pi_packages |
string list | [] |
Pi packages a pi session loads with pi -e on top of pi-mcp-adapter, which it always loads: npm:<name>[@version], git:<repo>[@ref], a URL, or a path (a relative one from the session’s worktree). [global] and role lists are unioned. Sessions of other agents ignore it. An empty entry, one starting with - and one naming pi-mcp-adapter are load errors. See Pi. |
skills_refresh |
string | "24h" |
[global] only. How stale a skill clone may get before it is pulled when a session needs it: never, always or a duration. |
mcp.<name> |
table | MCP servers keyed by name. See MCP servers. | |
profile |
string | "" |
Profile name. Under [global], the default profile for every role; under a role, that role’s profile override. An empty value uses the implicit built-in profile. |
profile_by_size |
table | {} |
Profile name per work item size, keyed by xs, s, m, l or xl. Accepted under [global] and every role. |
max_turns |
int | 200 |
Agentic turns per session (claude --max-turns). 0 means the default. Codex, opencode and pi have no such limit and a codex, opencode or pi role ignores it. |
timeout |
duration | "45m" |
Wall-clock limit for one session; the session’s process group is killed when it expires. "0s" means the default. |
allowed_tools |
string list | [] |
Passed as claude --allowedTools. A codex, opencode or pi role ignores it. |
disallowed_tools |
string list | [] |
Passed as claude --disallowedTools. A codex, opencode or pi role ignores it. |
shell |
string | the shell bees runs under | Exported into sessions as $SHELL. Claude Code discovers its Bash tool’s shell from $SHELL, so this is the lever, without being a guarantee. Must be an existing file. |
sandbox_image |
string | "" |
The image a container session runs in: it must hold the role’s agent, git and gh. A container role without one or container_use_environment is refused at bees run. See The container mode. For an sbx session it is the sandbox’s template instead, an image built on sbx’s image for the agent (docker/sandbox-templates:claude-code, :codex or :opencode); empty selects sbx’s own. See The sbx mode. |
container_use_environment |
string | "" |
Path, relative to the project repository root, to a dagger/container-use environment definition to build the container profile’s image from, instead of sandbox_image. Requires the resolved profile’s sandbox = "container" and is a load error together with sandbox_image on the same resolved role. See Building from container-use. |
sandbox_dagger_engine |
string | "" |
The host’s Dagger engine an sbx session is given, unix://<socket path>, tcp://<host>:<port> or docker-container://<container name>, with the Dagger CLI installed in the sandbox. Empty gives neither. Requires the resolved profile’s sandbox = "sbx" at every size and sandbox_dagger_version. See Dagger in the sandbox. |
sandbox_dagger_version |
string | "" |
The Dagger CLI release installed in the sandbox for sandbox_dagger_engine, the engine’s own, such as "v0.20.5". Requires sandbox_dagger_engine. |
env |
table | {} |
Environment variables exported into every session: the agent, its shell tool and git see them, and so do MCP servers under claude, opencode and pi (codex starts a server with only the variables its entry names). A $VAR value is expanded from the bees process environment when the session starts. A name may not be empty or contain = or a space. See Exported into every session for how it meets the variables bees sets itself. |
enabled |
bool | true (false for release_manager) |
Roles only. false takes a role out of the rotation. release_manager must be explicitly enabled because it can publish a GitHub release. Disabling reviewer makes a developer’s pull request count as approved the moment it is opened, and with auto_merge it goes straight to the checks stage. Under [global] the key is an error. A named set of these decisions is a config template. |
[profiles.<name>]
A profile bundles the agent, model, fallback, effort and sandbox for a
session. Profiles are named globally, then selected by [global] or a role.
Values omitted from a profile use its built-in defaults; a profile configured
for codex, opencode or pi has no default model. fallback names the profile
a retry runs on instead after a session on this one failed: that profile’s
agent, model, effort and sandbox, which can be a different agent entirely.
[global]
profile = "bar"
[profiles.foo]
agent = "claude"
model = "fable"
fallback = "bar"
effort = "max"
sandbox = "claude"
[profiles.bar]
agent = "opencode"
model = "ollama/qwen3.8:27b-mlx"
effort = "high"
[roles.developer]
profile = "foo"
profile_by_size = { xs = "bar", s = "bar", l = "foo", xl = "foo" }
| Key | Type | Default | Description |
|---|---|---|---|
agent |
string | "claude" |
CLI a session runs as: claude (claude -p), codex (codex app-server), opencode or pi (pi -p, see Pi). An unknown value is a load error. See Running a session. |
model |
string | "opus" for claude, "" otherwise |
Model alias or full id, passed to the selected agent (provider/model for opencode and pi). An empty value lets codex, opencode or pi use its own configured model. |
fallback |
string | "" |
The profile a retry runs on instead, agent included: a session that failed for infrastructure reasons (a timeout, exhausted turns, a crash, a rate limit) is retried on it when scheduler.retry_with_fallback is on, the next retry on that profile’s own fallback, and so on; a brief or angle review session refused for want of capacity runs again on it. Must name a profile; a profile that names itself, or a longer cycle (a → b → a), is a load error. When both profiles run claude, the fallback’s model is also passed as claude --fallback-model, so claude switches to it within a session; codex and opencode have no such flag, and a fallback on another agent is a new session. A fallback in a sandbox other than sbx runs without the role’s Dagger engine. |
effort |
string | "" |
Passed as claude --effort when set: low, medium, high or max. Codex receives it as model_reasoning_effort; max maps to high. Opencode receives it as the default build agent’s variant; variants are names the model defines, not levels. Pi receives it as --thinking. |
sandbox |
string | "none" |
How much of the machine a session can reach: none, claude, container or sbx. A pi profile runs with none or container: any other mode is a load error. See Sandboxing. |
The effective profile follows this order for a work item size:
role profile_by_size[size], role profile, global
profile_by_size[size], global profile, then the implicit built-in profile.
An unknown profile name or size is a load error.
[roles.reviewer] only: checks and auto-merge
The reviewer owns the checks and the merge. These keys are accepted only under
[roles.reviewer]; under [global] or another role they are a load error.
| Key | Type | Default | Description |
|---|---|---|---|
auto_merge |
bool | false |
Merge a pull request the reviewer approved once its checks are green. Off means people merge. A named set of these decisions is a config template. |
merge_method |
string | "squash" |
squash, merge or rebase (gh pr merge --<method> --delete-branch). |
checks_wait |
duration | "1m" |
Wait after approval before polling the checks, because some take a moment to report they started. |
checks_poll_interval |
duration | "2m" |
How often the checks are polled while waiting. One API call each, two when the branch requires nothing. |
checks_timeout |
duration | "30m" |
How long to wait for the checks before escalating with bees:needs-human. |
max_check_fix_rounds |
int | 2 |
Rounds of the reviewer diagnosing and the developer fixing a failed check before escalating. |
pre_review_checks |
bool | true |
Read the pull request’s checks before the first review, so the reviewer starts from a green pull request or is told it is not. Independent of auto_merge. |
pre_review_checks_timeout |
duration | "10m" |
How long that pre-review read waits for pending checks before reviewing anyway. |
[roles.reviewer]
auto_merge = true
merge_method = "squash"
checks_timeout = "20m"
With pre_review_checks on, a developer worker reads the pull request’s
checks once, between opening it and the first review: checks_wait, then a
poll every checks_poll_interval, bounded by pre_review_checks_timeout.
Green, and the review starts with the checks listed in the reviewer’s prompt.
A failure goes to the reviewer in checks mode and then to the developer for a
fix round first, sharing max_check_fix_rounds with the post-approval stage,
and the review happens once the pull request is green. Still pending at the
timeout, no check reported at all, or a read that fails, and the review
happens anyway with the reviewer told nothing was verified. Later review
rounds go straight to the reviewer with no second read. bees status shows
the worker in the pre-review checks stage while it waits.
With auto_merge on, after approval the worker waits checks_wait and polls
the checks every checks_poll_interval. All green merges. A failing check
gets the reviewer a checks-mode session to find the main error and mail it to
the developer, who pushes a fix, and the checks are polled again, up to
max_check_fix_rounds. Still pending at checks_timeout, or a merge GitHub
refuses (branch protection that needs a human review, say), escalates with
bees:needs-human. See Merging.
Which checks are the gate: the required checks (gh pr checks --required)
whenever the default branch requires any, and only those. A repository with no
branch protection requires nothing, and gating on nothing would merge with
nothing green, so there every check the pull request reports is the gate: a
failing one blocks and a pending one is waited for. To take a check out of the
gate, mark the ones that must block as required in the default branch’s
protection rules; bees never reads those rules to change them. With no check
reported at all, it merges after two consecutive empty polls and logs that no
check was reported. bees doctor says which of the three is in force, and
bees status shows it in the worker stage (checks (required), checks
(reported), checks (none)).
[roles.reviewer] only: the review pipeline
The reviewer’s review runs a brief, then one session per angle, then a
judge that merges what they found; these keys choose angles and execution
profiles for each step.
Like the checks keys, they are accepted only under [roles.reviewer].
| Key | Type | Default | Description |
|---|---|---|---|
angles.<size> |
string list | the built-in list for that size | The angles a pull request of that size is reviewed from. <size> is xs, s, m, l or xl; one or more of quick_general, general, docs, test_coverage, acceptance_criteria, side_effects. An unknown size or angle, or an empty list, is a load error. A size this does not name keeps the built-in list. |
brief_profile |
profile name | size-resolved reviewer profile | Execution profile for the brief. Its agent is one the review sessions can run as (claude, codex, opencode or pi); sandbox is ignored. |
angle_profiles.<angle> |
profile name | size-resolved reviewer profile | Execution profile for that angle. Same agent rule as brief_profile, and its whole fallback chain with it. Unknown profile or angle names fail loading with the complete key path. |
judge_profile |
profile name | size-resolved reviewer profile | All five execution fields, including sandbox, for the reviewer session that posts findings and decides the verdict. |
| Size | Built-in angles |
|---|---|
xs, s |
quick_general, docs |
m, l |
general, docs, test_coverage, acceptance_criteria |
xl |
general, docs, test_coverage, acceptance_criteria, side_effects |
Phase overrides resolve through [profiles.*] after ordinary role and
profile_by_size selection. An unspecified angle uses the size-resolved
reviewer profile. Brief and angle sessions select agent, model,
fallback and effort, subject to backend support (Codex maps max effort
to high). They ignore the profile’s sandbox and run under the shared
restricted execution’s read-only floor: no commands, writes, web/network
tools, inherited MCP, factory identity, or writable or shared VCS access. Claude,
codex, opencode and pi are the supported host agents, on every profile of
the fallback chain too: a brief or angle session refused for want of
capacity runs again as its fallback, under the same policy, and a chain
that reaches an agent a review session cannot run as is a load error.
The judge applies all five profile fields, including sandbox, through an
ordinary factory reviewer session. Its prompt, tools, permissions and ability
to post the verdict belong to the reviewer workflow. Profiles contain no
prompts, MCP, skills, environment, sandbox image, container environment,
shell, timeout, turn limit or VCS settings; those remain role/phase-owned.
An angle that fails is named in the judge’s task and the rest are judged;
a review where the brief or every angle failed escalates the issue instead.
The standalone bees review configuration is a separate file: it takes the
same [profiles.*] tables, selected by top-level brief_profile,
angle_profiles and judge_profile; see Review configuration.
[profiles.review_quick]
agent = "claude"
model = "haiku"
effort = "low"
[profiles.review_judge]
agent = "claude"
model = "sonnet"
sandbox = "claude"
[roles.reviewer]
angles.xs = ["quick_general"]
brief_profile = "review_quick"
angle_profiles.docs = "review_quick"
judge_profile = "review_judge"
See Review pipeline for what each angle looks at.
[roles.product_manager] only: minimum issue size
This key describes the product manager, so it is accepted only under
[roles.product_manager].
| Key | Type | Default | Description |
|---|---|---|---|
min_issue_size |
string | "" |
The smallest work item the product manager aims for when it breaks a feature down: xs, s, m, l or xl. Unset, it splits at whatever boundaries the work has. See Sizing. |
[roles.product_manager]
min_issue_size = "m" # fewer, larger work items per feature
It is a hint on the split, not a rule: nothing checks the size of an issue that gets created, and the project manager still sizes a work item as it finds it during triage. Work that is genuinely smaller still gets its own issue, whoever files it, so a bug found mid-implementation is unaffected.
[roles.developer] only: commit flags and max size
These keys describe the developer, so they are accepted only under
[roles.developer].
| Key | Type | Default | Description |
|---|---|---|---|
commit_flags |
string | "" |
Extra flags for every git commit the developer makes, appended to its prompt verbatim. |
max_size |
string | "l" |
The largest work item a developer takes: xs, s, m, l or xl. A bees:ready issue sized above it is moved back to bees:triage for the project manager to split; the project manager is told the limit. See Sizing. |
[roles.developer]
commit_flags = "--gpg-sign --signoff"
max_size = "m" # anything bigger goes back to triage to be split
Signing (--gpg-sign, -S) happens inside a headless session on the machine
running bees, so a signing key and agent must work for that user without a
prompt. --signoff needs user.name and user.email, as any
commit does.
[roles.developer] only: best of N
Best of N runs several developer sessions on the same issue, each on its own branch, and has an assembler session pick the pull request that goes to review. It is off until a size names a count.
| Key | Type | Default | Description |
|---|---|---|---|
best_of_n_by_size |
table | {} |
Attempts per work item size, keyed by xs, s, m, l, xl. An unknown key, or a value below 1, is a load error. A size with no entry, and an issue with no size label, gets one attempt. |
best_of_n_model |
string | "" |
The model every attempt runs when a size fans out. Empty: an attempt resolves its model the way a single session does, through its selected profile_by_size or profile. |
best_of_n_prompt |
string | "" |
The prompt every attempt runs with. Empty: the developer’s own prompt. |
assembler_model |
string | "" |
The model the assembler session runs. Empty: the developer’s resolved profile model. |
assembler_prompt |
string | "" |
The prompt the assembler session runs with. Empty: the developer’s own prompt. |
[roles.developer]
best_of_n_by_size = { l = 3 } # three attempts on a large issue
best_of_n_prompt = """
Do not read the other attempts. Solve the issue your own way.
"""
An entry of 1 is one attempt, the same as leaving the size out, so a table
that names no size above 1 is best of N off. A size above 1 runs that many
developer sessions at once for the issue’s first round, each on the branch
<branch_prefix>issue-<n>-attempt-<i> and each in a max_developers slot of
its own, so the count is clamped to max_developers. When every attempt has
ended, one assembler session runs on the issue’s own branch with the attempt
branches listed in its task, puts the result there (one attempt as it stands,
or a synthesis) and opens the pull request from it, which goes to review as
any developer’s does; the attempt branches are then deleted. An attempt that
pushed no commits is listed as not a candidate; when none did, the issue is
handed to a person, bees:needs-human.
[roles.developer] only: mixture of experts
A mixture of experts runs several developer sessions on the same issue, each one to a brief of its own, and has an assembler session combine their work into the pull request that goes to review. It is off until a size names its experts.
| Key | Type | Default | Description |
|---|---|---|---|
moe_experts_by_size |
table | {} |
The experts a work item of that size fans out to, keyed by xs, s, m, l, xl, each an ordered list of names from moe_experts. An unknown size, an empty list, a name moe_experts does not define, or a size that is also in best_of_n_by_size, is a load error. A size with no entry, and an issue with no size label, runs a plain developer round. |
moe_experts |
table | {} |
The experts themselves, one sub-table per name. prompt is what that expert’s session runs with in place of the developer’s own prompt, model the model it runs. Both are optional: an expert that names neither runs the developer’s prompt and resolves its model the way a single session does, through its selected profile_by_size or profile. |
moe_assembler_model |
string | "" |
The model the assembler session runs. Empty: the developer’s resolved profile model. |
moe_assembler_prompt |
string | "" |
The prompt the assembler session runs with. Empty: the developer’s own prompt. |
[roles.developer]
moe_experts_by_size = { xl = ["backend", "frontend"] }
moe_assembler_model = "opus"
[roles.developer.moe_experts.backend]
prompt = """
Solve it in the server code.
"""
model = "opus"
[roles.developer.moe_experts.frontend]
prompt = """
Solve it in the interface.
"""
A size that names two or more experts runs that many developer sessions at
once for the issue’s first develop round, one per name and in the order the
list gives them: expert i works on the branch
<branch_prefix>issue-<n>-attempt-<i>, with that expert’s prompt and model,
in a max_developers slot of its own, so the count is clamped to
max_developers and the experts past the clamp do not run. A size that names
a single expert runs the plain developer session that leaving the size out
would run, so that expert’s prompt and model go unused.
When every expert has ended, one assembler session runs on the issue’s own
branch. Its task lists each expert branch and the expert it came from; it
combines their work into one implementation on that branch and opens the pull
request from it, which goes to review as any developer’s does. The expert
branches are then deleted. An expert that pushed no commits is listed as not
a candidate; when none did, the issue is handed to a person,
bees:needs-human.
Sandboxing
sandbox in a profile says how much of the machine a session can reach. Select
different profiles when roles that run untrusted code need a harder box than
roles that only read the repository:
[profiles.unboxed]
sandbox = "none"
[profiles.boxed]
sandbox = "container"
[roles.developer]
profile = "boxed"
| Mode | What a session can reach |
|---|---|
none |
Everything the user running bees can: the home directory, credentials, the network and every other checkout on the machine. |
claude |
Claude Code’s own sandbox: writes to the worktree and the state directory, network to GitHub. See The claude mode and Security. |
container |
A container holding the worktree, the repository’s .git and the state directory, and nothing else of the host. See The container mode and Security. |
sbx |
A Docker Sandbox: a microVM holding the same three directories and nothing else of the host, its network held to the sbx policy, the agent’s credential injected by the sbx proxy. See The sbx mode and Security. |
none is the default. bees run checks before it starts that every role in
the rotation can have the box it asks for (the programs a claude box needs
on Linux, an agent that runs under it, a container role’s image,
credentials and engine, and an sbx role’s CLI and GitHub credential) and
refuses to start while one cannot, naming the role: a factory that fell back
to running that role unboxed would give it exactly what it was configured to
be kept away from. bees exec and bees tick refuse the same session for
the same reason.
bees config show prints the resolved mode per role, and
bees status the mode of the session each worker
is running right now.
See Security for what each mode protects and what it does not, filesystem, network and credentials in turn, including what a sandboxed session’s own GitHub credentials mean for it.
The claude mode
A session in claude mode runs under
Claude Code’s sandbox, with a
settings block bees writes for it. Every shell command, and every process it
starts, runs inside a box the operating system enforces: Seatbelt on macOS,
bubblewrap on Linux. The built-in file and web tools run in the claude
process itself, outside that box, so Claude Code’s permission rules hold them
to the same boundary, and anything those rules would ask a person about is
refused instead.
What the session can reach:
- Writes: the worktree, the state directory, the session’s own temporary
directory and the repository’s shared
.gitdirectory, sogit commitworks in a linked worktree. Anything else is refused,~/.zshrcand a toolchain’s cache under the home directory included, and Claude Code protects its own configuration inside the writable directories too (.claude/,.mcp.json,.git/hooks,.git/config), so a session cannot loosen its own box. - Reads: everything the user running
beescan read, credentials included. The mode fences writes and the network, not reads. - Network:
github.comand*.github.comonly, from shell commands and from theWebFetchtool alike, soghandgit pushover https work. Every other host is refused: a module proxy, a package registry, an ssh remote (no host name resolves inside the box), Docker and Dagger. - Tools: the built-in
beesMCP server and every MCP server of the role run on the host, outside the box, so the mail, issue, outcome andgh-backed tools work unchanged. The[github]token and the role’senvreach the shell inside the box.WebSearchis refused.
On macOS nothing needs installing. On Linux the box needs bubblewrap and
socat on PATH, which bees run checks before it starts. The box is
Claude Code’s, so a role whose resolved profile’s agent is codex or
opencode cannot use it: bees run refuses to start, naming the role. A
profile with agent = "pi" and sandbox = "claude" does not load.
Commit signing
through gpg does not work inside the box, because gpg writes under
~/.gnupg.
To widen the box for one project, commit a .claude/settings.json to the
repository: Claude Code merges its sandbox lists with the ones bees writes.
A Go project on macOS needs its build cache and module proxy, for example:
{
"sandbox": {
"filesystem": { "allowWrite": ["~/Library/Caches/go-build"] },
"network": { "allowedDomains": ["proxy.golang.org", "sum.golang.org"] }
}
}
The settings of the user running bees (~/.claude/settings.json) merge the
same way, and an excludedCommands entry there runs that command outside the
box.
The container mode
A container session is the agent’s command line, unchanged, run inside
docker run. It needs docker on PATH with a daemon that answers, and the
image sandbox_image names on the machine: pull or build it yourself, bees
never pulls. bees run checks all three ahead of the doctor, whatever
--skip-doctor says, and refuses to start naming the role that fails. A role
with container_use_environment instead of sandbox_image has its image
built at session start, and docker build pulls the definition’s
base_image then; see
Building from container-use.
The container sees three things of the host, each bind-mounted at its host
path so every path in the prompts and the environment means the same inside:
the worktree, the repository’s .git (a linked worktree’s .git file points
into it, and commits write there) and the state directory (mail, notes, the
session directory). A role with skills also gets the skills cache,
read-only. Nothing else: no home directory, no other checkout, no credential
store. The session runs as the user running bees (claude refuses to skip
permissions as root), with a HOME of its own on a tmpfs that is gone when
the session ends; a settings directory baked into the image is reached by
setting CLAUDE_CONFIG_DIR in the role’s env.
Its environment is built from nothing rather than from the one bees runs
in, and holds, in this order: the agent’s credential forwarded from the bees
environment when it is set there, the role’s env (which may name the
credential itself), SHELL, the BEES_* variables, the
[github] token and git identity, the git
configuration every session runs with plus safe.directory = * and an
insteadOf that pushes an ssh remote over https (the container has no ssh
keys), and HOME. Values reach the engine by variable name, never on a
command line. A container role therefore needs [github] (or GH_TOKEN in
its env) and a credential for its agent; bees run refuses the role
without them, because inside the container there is no other gh login and no
keychain.
The credential is the agent’s own: ANTHROPIC_API_KEY or
CLAUDE_CODE_OAUTH_TOKEN for claude, OPENAI_API_KEY or CODEX_API_KEY
for codex, and for opencode and pi the key of whichever provider the model
names. opencode reads ANTHROPIC_API_KEY, OPENAI_API_KEY,
GEMINI_API_KEY, GOOGLE_API_KEY, OPENROUTER_API_KEY, GROQ_API_KEY,
MISTRAL_API_KEY, XAI_API_KEY and DEEPSEEK_API_KEY; pi’s keys are
listed under Pi. Every one of them that is set is forwarded.
The bees binary is not in the container. The built-in MCP server runs on the
host as bees mcp serve --listen, with the environment a session on the host
would have started it with, and the session reaches it over HTTP at
host.docker.internal with a bearer token of its own, passed through the
container environment. The backend configuration references that variable;
the token value stays out of configuration files and command arguments. The
tools work unchanged; the session’s prompt does not offer the bees commands.
A stdio MCP server configured in bees.toml starts inside the container, so
its command must be in the image; a remote one is
reached as configured (host.docker.internal reaches a server on the host).
The image must hold the agent, git and gh. A Dockerfile that does:
FROM node:22-bookworm
RUN apt-get update \
&& apt-get install -y --no-install-recommends git curl ca-certificates \
&& curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg \
-o /usr/share/keyrings/githubcli-archive-keyring.gpg \
&& echo "deb [arch=$(dpkg --print-architecture) \
signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] \
https://cli.github.com/packages stable main" \
> /etc/apt/sources.list.d/github-cli.list \
&& apt-get update && apt-get install -y --no-install-recommends gh \
&& rm -rf /var/lib/apt/lists/*
RUN npm install -g @anthropic-ai/claude-code
A role that runs the product (QA, most often) names an image carrying the
product’s toolchain too, under [roles.qa].
While the session runs, <session>/container-id holds the container’s id
and <session>/mcp-server-pid the pid of the built-in MCP server bees
started on the host for it, and the container is named
bees-<session>-<random> and labelled
bees.session=<session directory>, so docker ps --filter
label=bees.session lists a factory’s sessions. Stopping the session (its
timeout, or bees run stopping) removes the container. So does stopping it
from outside: bees kill
and the live view’s k key find a container session through that label and
remove its container, which is what stops the agent: it runs in the
container, not on the host, and killing the docker run client alone
leaves it running. They stop the MCP server too, from its pid file: it runs
on the host in a process group of its own, so a crash that takes bees down
would otherwise leave it holding its port and serving the factory’s tools.
What the box holds: the session cannot read or write anything of the host
outside the three mounts, and cannot reach the host’s credentials or its
other checkouts. What it does not: the session has the network, the bot’s
GitHub token, the Neo4j Agent Memory API key with the neo4j notes backend,
its agent credential, and everything in the image; and the mounted state
directory holds every role’s mail and notes, not only its own.
On Linux the container runs as the user running bees so what it writes stays
theirs, and reaches the host at the docker bridge gateway; the mode has been
exercised on macOS with Docker Desktop.
Building from container-use
sandbox_image is the way to run a container session: point it at an
image you built and published yourself, and bees runs it unchanged. This is
a niche opt-in for a project that already keeps a declarative, buildable
environment definition in the
dagger/container-use format, and
would rather bees build from that than from a hand-built image. Most
projects should keep using sandbox_image instead.
Setting container_use_environment to a path builds the image from
<path>/.container-use/environment.json in the project repository, at
session start, instead of requiring sandbox_image. bees reads only that
file’s format: it does not depend on container-use’s Go package, the
Dagger SDK, or a running Dagger engine. Of the definition’s fields, bees
uses:
base_image: the image the build startsFROM.env:KEY=VALUEentries, set before any command runs.setup_commands, theninstall_commands: oneRUNeach, in that order.container-useitself runssetup_commands, copies its environment’s source tree in, then runsinstall_commands, so an install command there can see a checked-in file such aspackage.json. bees has no such copy step. The worktree is bind-mounted when the container runs, not baked into the image, so the two lists run back to back. An install command that depends on source files being present must tolerate their absence, or move to a role’s own session-start mechanism instead.
workdir, secrets and services are read and ignored, without an error.
The container always runs at the worktree’s host path regardless of
workdir. secrets names Dagger secret-provider URIs bees has no pipeline
to resolve, and services describes more than one container, which the
sandbox does not support.
The built image must still hold the agent, git and gh, the same
requirement a hand-built sandbox_image has. Providing them is the
definition’s setup_commands/install_commands job. The image is tagged
after a hash of the resolved build inputs (base_image, env,
setup_commands, install_commands, in that order), so a definition whose
formatting changes but whose build inputs do not reuses the image already
built for it, and a change to any of those inputs builds a new one.
docker build runs once per definition, the first time a session needs it.
A missing or malformed environment.json, or a failing build, fails that
session with an error naming the path or the build command, not a
bees.toml load error.
The sbx mode
An sbx session is the agent’s command line, unchanged, run inside a
Docker Sandbox: a microVM with its
own kernel, filesystem, Docker daemon and network, which the sbx CLI
creates and removes. It needs sbx on PATH and signed in (sbx login),
and runs claude, codex and opencode; sbx has no template for pi, and
a pi profile with sandbox = "sbx" does not load. bees run checks that sbx
answers ahead of the doctor, whatever --skip-doctor says, and
bees doctor reports it when a role uses the mode.
The sandbox is given the same three directories a container is, as its
workspaces, each mounted at its host path: the worktree, the repository’s
.git and the state directory (mail, notes, the session directory), and the
skills cache read-only for a role with skills. Nothing else of the host:
the shared skills store sbx mounts by default is switched off. The session
runs as the sandbox’s own user, with the sandbox’s own home directory, and
inside it the agent has sudo, package managers and a private Docker
daemon: everything it installs stays in the sandbox, which is removed when
the session ends.
[profiles.sandboxed]
agent = "codex"
sandbox = "sbx"
[roles.developer]
profile = "sandboxed"
sandbox_image = "ghcr.io/acme/widgets-sbx-codex:1" # optional template
The sandbox is created for the role’s agent (sbx create <agent>), from
sbx’s own template for it unless sandbox_image names one. sbx’s own is
the -docker variant of the agent’s image below, which adds the private
Docker daemon:
| Agent | Image | Credential to store once |
|---|---|---|
claude |
docker/sandbox-templates:claude-code |
sbx secret set anthropic |
codex |
docker/sandbox-templates:codex |
sbx secret set openai (--oauth for a ChatGPT sign-in) |
opencode |
docker/sandbox-templates:opencode |
sbx secret set <provider> for each provider its model uses (anthropic, openai, google, …) |
sandbox_image is passed as sbx create --template: an image built FROM
the agent’s image in that table, or its -docker variant to keep the
Docker daemon, with the product’s toolchain added. sbx requires a template
built for the agent it runs. sbx’s own templates hold the agent, git and
gh. container_use_environment is a load error
alongside sbx.
Its environment is built from nothing and holds the role’s env, SHELL,
the BEES_* variables, the [github] token and git identity,
and the git configuration every session runs with plus safe.directory = *
and the https insteadOf. Values reach sbx by variable name, never on a
command line. The agent’s own credential is not forwarded: store it once
with sbx secret set, as the table says, and the sandbox’s proxy injects
it into the agent’s requests without the value entering the sandbox. An
sbx role therefore needs [github] (or GH_TOKEN in its env), because
inside the sandbox gh and git push have no other credentials, and no
agent credential in the bees environment; bees run refuses the role
without the former. Do not also store a github secret with
sbx secret set: the proxy would replace the bot’s token with it on every
request to GitHub. The sandbox does not read the operator’s ~/.codex or
~/.config/opencode; bees passes a session’s MCP servers and settings on
the command line (codex) or in the session’s own opencode.json
(opencode), as it does on the host.
The bees binary is not in the sandbox. The built-in MCP server runs on the
host as bees mcp serve --listen on the loopback, and the session reaches
it over HTTP at host.docker.internal with a bearer token of its own, the
way a container session does. The sandbox’s proxy forwards that name to the
host’s localhost and checks it against the network policy, which denies
it unless a rule allows it. Bees adds that rule for each session, once the
sandbox exists and the server has its port, and removes it before it
removes the sandbox:
sbx policy allow network --sandbox <sandbox> localhost:<port>
sbx policy rm network --sandbox <sandbox> --resource localhost:<port> --force
The rule names one sandbox and one port, so no other sandbox reaches the
server and the session reaches nothing else on the host’s loopback. If sbx
refuses the rule, the session does not start and bees removes the sandbox.
You do not need a global localhost rule; see Security.
The same policy decides which other hosts the session reaches: the
Balanced preset allows GitHub and the AI provider APIs; add a module proxy
or a package registry with sbx policy allow network.
A stdio MCP server configured in bees.toml starts inside the sandbox, so
its command must be in the template; a remote one is reached as configured,
and sbx mcp add registrations are not used.
Written to the sbx CLI reference and not run for this page: the sandbox is
created with sbx create --no-progress --name <session> --skills off <agent>,
the command runs through
sbx exec --interactive --workdir <worktree> --env <name>... with the
prompt on stdin, and sbx rm --force removes the sandbox when the session
ends, or when sbx create fails, since sbx can fail after it has made the
sandbox. <session>/sandbox-name holds the sandbox’s name while it exists.
bees kill
does not remove a sandbox a crash left behind; sbx rm --force <name> does.
Dagger in the sandbox
sandbox_dagger_engine gives an sbx session the host’s Dagger engine, and
sandbox_dagger_version the Dagger CLI release installed in the sandbox to
reach it, so that a developer session can run dagger check. It is off
unless set, and valid only when the role’s resolved profile, at every size,
selects sbx; one key without the other is a load error. A fallback or
judge_profile that selects another sandbox loads, and its sessions run
without the Dagger CLI or the engine.
[roles.developer]
profile = "sandboxed"
sandbox_dagger_engine = "unix:///run/dagger/engine.sock"
sandbox_dagger_version = "v0.20.5"
The engine is one bees can reach on this machine:
unix://<path>: the engine’s socket. A sandbox cannot mount a socket, so for each session bees listens on a port of the host’s loopback and forwards every connection to the socket until the session ends.tcp://<host>:<port>: an engine listening on TCP. One on the loopback (127.0.0.1,localhost,::1) is reached athost.docker.internal; any other host as written.docker-container://<name>: an engine running in a Docker container, such as thedagger-engine-<release>container the Dagger CLI starts for itself. For each session bees listens on a port of the host’s loopback and runsdocker exec -i <name> buildctl dial-stdiofor every connection, until the session ends. The sandbox gets no Docker socket.
The engine must be running and of sandbox_dagger_version’s release: the
Dagger CLI refuses an engine it is not compatible with. Start one on a
socket, for example:
docker run -d --name dagger-engine --privileged \
-v /run/dagger:/run/dagger registry.dagger.io/engine:v0.20.5 \
--addr unix:///run/dagger/engine.sock
On macOS the socket stays inside Docker Desktop’s VM. Give the container
instead, sandbox_dagger_engine = "docker-container://dagger-engine", or
publish a TCP port (-p 127.0.0.1:1234:1234 and
--addr tcp://0.0.0.0:1234) and set
sandbox_dagger_engine = "tcp://127.0.0.1:1234".
Once the sandbox exists, bees runs dagger version in it. When the
sandbox’s template reports the role’s release (v0.20.5 and 0.20.5
match), the CLI is used as it is. Otherwise, the CLI missing, another
release or the probe failing, bees installs the CLI into /usr/local/bin
with the install script at https://dl.dagger.io/dagger/install.sh, as
root, before the agent starts; the sbx network policy must allow
dl.dagger.io. A failed install fails the session and removes the sandbox.
To skip the install, give the role a sandbox_image
that has the CLI on its PATH at the role’s release.
The session reaches the engine through _EXPERIMENTAL_DAGGER_RUNNER_HOST,
which bees sets to the address above. For an engine on the host’s loopback,
through the socket forward or on TCP, bees adds a rule allowing that port
for the session’s sandbox, the same way it does for the built-in server.
An engine on another host needs a rule of your own.
This widens what a session reaches: the engine runs containers outside the sandbox, with the engine’s own network and cache, not the sandbox’s policy. See Security. Written to the sbx CLI and Dagger references and not run for this page.
How global and role settings merge
| Setting | Rule |
|---|---|
prompt, prompt_file |
Concatenated, separated by blank lines: global prompt, global prompt_file, role prompt, role prompt_file. The result is appended to the role’s built-in prompt under an “Additional instructions from bees.toml” heading, followed by the repository’s project prompt files. |
skills |
Union, global first, order kept, duplicates dropped. |
mcp |
Union by name; a role server replaces a global one of the same name. |
env |
Union by name; the role wins. |
max_turns, timeout, shell, sandbox_image, container_use_environment, sandbox_dagger_engine, sandbox_dagger_version |
Role value if set, else global, else the built-in default. |
profile, profile_by_size |
For a work item size: role profile_by_size[size], role profile, global profile_by_size[size], global profile, then the implicit built-in profile. |
allowed_tools, disallowed_tools |
Global list followed by the role list. |
enabled |
Role only. |
skills_refresh |
Global only. |
min_issue_size |
roles.product_manager only. |
commit_flags, max_size, best_of_n_by_size, best_of_n_model, best_of_n_prompt, assembler_model, assembler_prompt, moe_experts_by_size, moe_experts, moe_assembler_model, moe_assembler_prompt |
roles.developer only. |
auto_merge, merge_method, checks_wait, checks_poll_interval, checks_timeout, max_check_fix_rounds, pre_review_checks, pre_review_checks_timeout, angles, brief_profile, angle_profiles, judge_profile |
roles.reviewer only. bees config show reviewer prints the resolved policy. |
bees config show <role> prints the result.
Only the contents of prompt_file are re-read for every session. Everything
else, prompt included, comes from the bees.toml and user-level profile
defaults that bees run loaded when it started or last reloaded: r in the
live view, or SIGHUP, reads both files again and the
next session dispatched
runs on it; a few keys, listed there, take a restart. The built-in role
prompts are compiled into the bees binary and need a
rebuild as well as a restart. bees status names the build the running
scheduler was started from, and bees doctor warns when
that build is behind the commit the repository has checked out.
Project prompt files
A project can keep role instructions in the repository instead of in
bees.toml, so they are versioned and reviewed like code, and a branch can
carry its own.
bees/prompts/common.md every role
bees/prompts/developer.md the developer
bees/prompts/product_manager.md the product manager
bees/prompts/common.md is appended to every role’s prompt and
bees/prompts/<role>.md to that role’s. Nothing is configured; a repository
without the directory renders the prompt it would render anyway. The sources
land on the built-in prompt in this order, each under a heading naming where it
came from, so a bees.toml override still wins over what the repository says:
[global]promptandprompt_file[roles.<name>]promptandprompt_filebees/prompts/common.mdbees/prompts/<role>.md
The directory is bees/, without a dot. bees init adds /.bees/ to
.gitignore, so files under .bees/prompts/ would be untracked, the opposite
of instructions reviewed like code.
Sessions read the files from their own worktree at session start, so a session
sees the files on the branch it is working on, and an edit takes effect on the
next session with no rebuild and no restart. bees prompts show <role>
--rendered has no worktree and reads the main checkout (project.dir, else
the checkout bees.toml sits in); it says so when it finds any.
A file bees cannot use, unreadable or larger than 64 KiB, never stops a
session: the session warns, skips that file and runs with the rest. bees
doctor fails on such a file, and on a file no role reads (a misspelled name
such as bees/prompts/develloper.md).
Anyone who can land a commit on a branch can change what the sessions on that
branch are told to do. That is the point of the feature, and it is the same
trust boundary as a CI configuration in the repository: review changes to
bees/prompts/ as you would review a workflow file.
Skills
Skills are referenced by git URL and cloned into a cache directory,
~/.cache/bees/repos on Linux (~/Library/Caches/bees/repos on macOS)
unless BEES_CACHE_DIR says otherwise. They reach Claude
Code as plugin directories (claude --plugin-dir), so the worktree is never
modified. Skills in the repository’s .claude/skills/ and in
~/.claude/skills/ are available without being listed.
skills = [
"https://github.com/acme/skills", # whole repository
"https://github.com/acme/skills#skills/tdd", # one directory inside it
"https://github.com/acme/my-plugin@v1.2.0", # pinned tag or branch
"git@github.com:acme/private-skills.git", # ssh works too
]
The URL is <git-url>[@<ref>][#<sub/dir>]. The selected directory is one of
three layouts, checked in this order:
- A Claude Code plugin, with
.claude-plugin/plugin.json. Used as-is. - A single skill, with
SKILL.mdat its root. Wrapped in a generated plugin exposing that skill. - A skills collection, with a
skills/directory. Wrapped in a generated plugin exposing every skill in it.
Anything else is an error. Clones and wrappers are reused; a wrapper is
rebuilt only when it is missing or its #sub/dir changed, because a session
may be running with it.
A clone is pulled (git pull --ff-only) when a session needs it and it was
last fetched more than skills_refresh ago, 24h by default. "always" pulls
before every session, "never" never pulls. A failed pull is logged as a
warning and never stops a session; a reference pinned with @tag is a
detached checkout and cannot be pulled, which is the point of pinning.
bees skills list shows the cache and
bees skills update pulls everything now, whatever the policy says.
MCP servers
A claude session is given the servers in a per-session --mcp-config file
loaded with --strict-mcp-config, so it sees the servers configured here plus
the built-in one, and none of your own. A codex session is given the same
servers as -c mcp_servers.<name>.<key>=<value> overrides on its command
line, next to whatever ~/.codex/config.toml configures. Codex filters a
stdio server’s inherited environment. Bees forwards the built-in server’s
GitHub credentials and configured notes API key through env_vars, which
names variables to read from the session’s environment. Their values stay
out of the generated MCP configuration and command arguments. Configured
servers receive their entry’s env values. An opencode session is given
the same servers as the mcp table of a per-session opencode.json, handed to it
through OPENCODE_CONFIG, next to whatever its global configuration and
the project’s own opencode.json name. A pi session is given the same
servers in a per-session pi-mcp.json that pi-mcp-adapter reads alone;
see Pi.
bees is reserved. Every session gets a server called bees carrying the
factory’s own tools; see bees mcp serve.
It needs no configuration and cannot be turned off. Defining
[global.mcp.bees] or [roles.<role>.mcp.bees] fails to load with
mcp server name "bees" is reserved for the built-in server.
| Key | Description |
|---|---|
type |
stdio, http or sse. Defaults to stdio when command is set, http when only url is. |
command |
Executable of a stdio server. |
args |
Arguments for command. |
env |
Environment of the server process. $VAR and ${VAR} are expanded from the bees process environment. |
url |
Endpoint of an http or sse server. |
headers |
HTTP headers for a remote server; $VAR expansion applies. |
Either command or url is required.
[global.mcp.github]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]
env = { GITHUB_PERSONAL_ACCESS_TOKEN = "$GITHUB_TOKEN" }
[roles.qa.mcp.browser]
type = "http"
url = "https://mcp.example.com/browser"
headers = { Authorization = "Bearer $BROWSER_MCP_TOKEN" }
Pi
A profile with agent = "pi" runs its sessions as
pi. Pi has no MCP support of its own, so every
pi session loads the third-party
pi-mcp-adapter extension,
which gives it the bees tools and the role’s MCP servers:
pi -p --mode json --no-extensions \
-e npm:pi-mcp-adapter [-e <pi_packages entry>]... \
--mcp-config <session>/pi-mcp.json --name bees-<session name> ...
--no-extensionskeeps pi from loading the packages in its ownsettings.jsonand the extensions it would discover: a session loads the adapter and the role’spi_packages, nothing else.- The adapter is not installed with
pi install. Pi installsnpm:pi-mcp-adapterand everynpm:orgit:entry ofpi_packagesinto its own extension cache the first time a session loads it, which needsnpmand network access.bees doctorloads them the way a session does and installs what is missing; to do it by hand, runpi --no-extensions -e npm:pi-mcp-adapter --helpand look for--mcp-configin the output. <session>/pi-mcp.jsonholds thebeesserver and the role’s servers, each connected at startup and with its tools registered as pi tools of their own.PI_MCP_CONFIG_MODE=exclusivemakes it the only MCP configuration the adapter reads: no~/.config/mcp/mcp.json, no project.mcp.json.
[profiles.pi]
agent = "pi"
model = "anthropic/claude-sonnet-5"
effort = "high"
[roles.developer]
profile = "pi"
pi_packages = ["npm:@acme/pi-tools@1.2.3"]
Pi runs every tool without asking and has no sandbox of its own, and sbx has
no template for it: it runs with sandbox = "none" or "container". In a container its home directory is a
fresh tmpfs, so pi installs the adapter and the packages again at every
session: the image needs pi, npm and access to the npm registry (and to
the git hosts of git: packages), next to git and gh. Add pi to the image
of The container mode:
RUN npm install -g --ignore-scripts @earendil-works/pi-coding-agent
A container session is handed its provider key from the bees environment
when one of these is set there: ANTHROPIC_API_KEY, ANTHROPIC_OAUTH_TOKEN,
OPENAI_API_KEY, GEMINI_API_KEY, OPENROUTER_API_KEY, GROQ_API_KEY,
XAI_API_KEY, MISTRAL_API_KEY, DEEPSEEK_API_KEY or CEREBRAS_API_KEY.
Another provider’s key goes in the role’s env.
Examples
Solo project, two developers
version = 4
# repo and default_branch are derived from the origin remote.
[filter]
label = "bees"
[scheduler]
max_developers = 2
qa_interval = "1h"
[global]
prompt = """
Use conventional commits. Never add a dependency without a comment saying why.
"""
[profiles.reviewer]
model = "sonnet"
[roles.developer]
commit_flags = "--signoff"
[roles.reviewer]
profile = "reviewer"
prompt = "Be strict about error handling and test coverage."
auto_merge = true
checks_timeout = "20m"
[roles.qa]
skills = ["https://github.com/anthropics/skills#skills/webapp-testing"]
timeout = "30m"
Team repository, only work assigned to me
version = 4
[project]
remote = "upstream" # my origin is a fork; the team repository is upstream
[filter]
label = "kyle-bees" # the kyle-bees:* labels are mine
require_label = false
assignee = "@me"
[scheduler]
product_manager_interval = "4h"
[global]
prompt_file = "docs/engineering-conventions.md"
[roles.product_manager]
enabled = false # the team's own product manager owns the roadmap
[roles.developer]
prompt = "Only touch files under services/billing unless the issue says otherwise."
Requirements
bees run, tick, exec, status, issue create and issue link check
the tools they drive before doing anything and refuse to start when one is
missing or too old; bees init checks gh.
| Tool | Minimum | Why |
|---|---|---|
gh |
2.50.0 | gh pr checks --json (2.50.0) and gh api --slurp (2.49.0). |
Claude Code (claude) |
2.1.76 | claude --name (2.1.76); --append-system-prompt-file, --effort, --plugin-dir, --strict-mcp-config and --fallback-model are older. |
The Claude Code check only runs when at least one enabled role resolves to an
agent profile whose agent is "claude", the default (see
[profiles.<name>]). A factory where every enabled role
resolves to "codex", "opencode" or "pi" never runs it, so claude
does not need to be installed. Pi needs the
pi-mcp-adapter package, which pi installs itself.
Set BEES_SKIP_VERSION_CHECK=1 to run with an unsupported version anyway.
Environment variables
Honoured by the bees command
| Variable | Effect |
|---|---|
BEES_CONFIG |
Path of bees.toml when --config is not given. Set inside sessions. |
BEES_CLAUDE_BIN |
The claude executable to run. Default claude on PATH. |
BEES_CODEX_BIN |
The codex executable to run for a role whose agent is codex. Default codex on PATH. |
BEES_OPENCODE_BIN |
The opencode executable to run for a role whose agent is opencode. Default opencode on PATH. |
BEES_PI_BIN |
The pi executable to run for a role whose agent is pi. Default pi on PATH. |
BEES_CACHE_DIR |
Cache directory for skill clones and generated plugins. Default ~/.cache/bees on Linux, ~/Library/Caches/bees on macOS. |
BEES_SKIP_VERSION_CHECK |
When non-empty, skip the gh and claude version checks. |
BEES_STATE_DIR |
bees mail and bees notes use this state directory without loading bees.toml, unless --config is given, in which case that file’s state directory wins. Set inside sessions. |
BEES_SESSION_DIR |
Where bees done writes outcome.json; bees done refuses to run without it. Set inside sessions. |
BEES_ROLE |
Default --from of bees mail send, and the role whose bees done statuses are validated. Set inside sessions. |
BEES_ISSUE, BEES_PR |
Defaults for the --issue and --pr flags of bees mail send and bees done. Set inside sessions. |
BEES_LOG_FORMAT, BEES_LOG_LEVEL |
Fallbacks for --log-format and --log-level. A flag beats them, and they beat [logging]. |
The variables marked set inside sessions are the only ones a session
inherits. BEES_CLAUDE_BIN, BEES_CODEX_BIN, BEES_OPENCODE_BIN,
BEES_PI_BIN, BEES_CACHE_DIR, BEES_SKIP_VERSION_CHECK, BEES_LOG_FORMAT and
BEES_LOG_LEVEL configure
the bees process you start
and are not passed on, so a bees command a session runs itself sees their
defaults. To give sessions one of them, put it in
[global.env].
Exported into every session
A session inherits only the variables of the bees process environment its
role is granted, never a BEES_* one:
- the shell’s own and the toolchains’:
PATH,HOME,USER,LOGNAME,SHELL,TMPDIR,TMP,TEMP,TERM,COLORTERM,LANG,LANGUAGE,LC_*,TZ,XDG_*,__CF_USER_TEXT_ENCODING, the proxy variables (HTTP_PROXY,HTTPS_PROXY,NO_PROXY,ALL_PROXY, upper and lower case),SSL_CERT_FILE,SSL_CERT_DIR,NODE_EXTRA_CA_CERTS,REQUESTS_CA_BUNDLE,GOPATH,GOROOT,GOBIN,GOFLAGS,GOPROXY,GOPRIVATE,GONOPROXY,GONOSUMDB,GONOSUMCHECK,GOSUMDB,GOINSECURE,GOCACHE,GOMODCACHE,GOTMPDIR,GOTOOLCHAIN,GOWORK,GOENV,GOOS,GOARCH,GOEXPERIMENT,GODEBUG,GOAMD64,GOARM,GOARM64,GOTELEMETRY,GOGC,GOMAXPROCS,CGO_*,DOCKER_*,DAGGER_*,NODE_*,NPM_CONFIG_*,NVM_*,CARGO_*,RUSTUP_*,JAVA_HOME,PYTHON*,VIRTUAL_ENV,HOMEBREW_*,SDKROOT,DEVELOPER_DIR; - its agent’s provider variables:
ANTHROPIC_*,CLAUDE_*,AWS_*,GOOGLE_*,CLOUD_ML_REGION,VERTEX_*,DISABLE_*,MAX_THINKING_TOKENSandMCP_*for claude;OPENAI_*andCODEX_*for codex;OPENCODE_*and the provider keys opencode reads for opencode;PI_*,MCP_*and the provider keys pi reads (ANTHROPIC_*,OPENAI_*,GEMINI_*,GOOGLE_*,AWS_*,OPENROUTER_*,GROQ_*,MISTRAL_*,XAI_*,DEEPSEEK_*,AZURE_*,CEREBRAS_*) for pi; - gh’s, git’s and the SSH agent’s:
GH_*,GITHUB_*,GIT_*,GCM_*,SSH_AUTH_SOCK,SSH_AGENT_PID,SSH_ASKPASS,SSH_ASKPASS_REQUIRE.
Any other variable reaches a session only through its role’s env:
[global.env]
NPM_TOKEN = "$NPM_TOKEN"
On top of those, a session gets:
| Variable | Value |
|---|---|
configured env |
Every [global.env] and [roles.<name>.env] entry, $VAR-expanded. Set first, so everything below wins over it. |
BEES_ROLE |
The role name (developer, reviewer, …). |
BEES_SESSION_DIR |
This session’s directory: prompts, transcript, outcome.json. |
BEES_STATE_DIR |
The state directory. |
BEES_CONFIG |
Path of bees.toml. |
BEES_REPO |
owner/name. |
BEES_LABEL |
filter.label. |
BEES_ISSUE |
The issue the session works on, when any. |
BEES_PR |
The pull request, when any. |
BEES_BRANCH |
The checked-out branch, when any. |
BEES_BIN |
Path of the bees executable. Its directory is also prepended to PATH, so a session can run bees mail and bees done. Not set in a container session, which has no bees binary. |
PATH |
With a GitHub App and gh and git access, <state_dir>/github/bin first, holding the App’s gh, which runs yours with the App’s current token. |
BEES_REVIEW_MODE |
checks in a reviewer session that diagnoses failed checks; unset otherwise. |
SHELL |
The configured shell, when set. |
GH_TOKEN |
github.token, when set, so the session’s gh acts as the factory. Empty with a GitHub App, whose gh fetches its own token. |
the variable github.token names |
When github.token is a "$VAR" reference, that variable, holding the resolved token. The bees commands a session runs load bees.toml themselves, and a reference that expands to nothing is a load error, so the name has to survive the BEES_* strip. It is set in the environment only; nothing writes it into the session directory. |
the variable notes.neo4j_api_key names |
The same, for a "$VAR" notes.neo4j_api_key, with notes.backend = "neo4j": the value the scheduler resolved, so the session’s own notes_read and notes_write can load [notes]. |
GIT_AUTHOR_NAME, GIT_COMMITTER_NAME, GIT_AUTHOR_EMAIL, GIT_COMMITTER_EMAIL |
github.git_name and github.git_email, when set. |
GIT_CONFIG_COUNT, GIT_CONFIG_KEY_n, GIT_CONFIG_VALUE_n |
push.autoSetupRemote=true and push.default=current, so a plain git push works on a fresh branch without touching the clone’s git config; with github.token set, also an empty credential.helper followed by credential.helper=!gh auth git-credential, so an https push authenticates as the factory rather than through your stored credentials. With a GitHub App the second helper is <state_dir>/github/credential.sh, which answers with the App’s current token. Left alone when GIT_CONFIG_COUNT is already in the bees environment. |
BEES_* variables are always set by bees for each session and never inherited,
so a session started from inside another one, by a nested bees run or bees
exec, never sees a stale issue, PR or branch. The BEES_* names bees puts
back after the strip are the ones a "$VAR" github.token and a "$VAR"
notes.neo4j_api_key read.