Skip to the content.

bees review reviews one GitHub pull request, any pull request your gh login can read. It runs without a factory: it reads no bees.toml, no state directory and no mailbox. Several read-only agent sessions review the change, each from one angle, bees merges what they found into one list, and you decide about each finding before the review ends.

cd ~/src/widgets
bees review 7

The commands and their flags are in the CLI reference. This page covers what a review does, where it keeps what it found, and the files that configure it.

How a review runs

context  ->  brief  ->  angles  ->  findings  ->  triage  ->  end
  1. Context. bees gathers the pull request’s context from the sources context.toml enables: the diff, the pull request’s conversation, the issues it links, the project’s style files and the callers of what it changed. Generated files are taken out of the diff before anything reads it. A source that cannot read something records what it missed, and the review goes on.
  2. Brief. One session, the distiller, reads everything gathered and writes the brief: what the change does, its size (xs, s, m, l or xl, judged from how many files and lines it touches and which parts of the project those are), its acceptance criteria with the issue or text each came from, the style rules that apply to it with the file each is written in, the parts of the project it touches, the generated files taken out of the diff with the lines each added and removed, and what the sources could not read.
  3. Angles. One session per angle the brief’s size calls for and context.toml enables reads the brief and the diff, and answers with findings. The angles run at the same time, and at a terminal the command shows each one’s progress while they do. An angle that fails is skipped, and so is one whose session answers that it could not read the diff or a file it needed: it is named as not reviewed, never counted as having found nothing. The review stops only when every angle fails.
  4. Findings. bees merges the angles’ answers into one list, in code and not in a session (see Findings), then applies the rules in your reviewer notes: a finding you dismissed before is dropped or ranked down. The optional Jev boost then ranks findings and removes those below its threshold.
  5. Triage. You take each finding in turn and select, dismiss, defer or ask about it. With --agent, an agent session does it instead: see factory mode.
  6. End. What you selected is posted as one review, printed as a report, or discarded: see How a review ends.

Every session is read-only, held there by the agent’s own settings rather than by the prompt. A claude session may use Read, Grep, Glob, LS and NotebookRead and nothing else. A codex session runs in Codex’s read-only sandbox with its command, fetch, plugin and image generation features off, and an inventory of the MCP servers it inherits is taken first so every one of them can be disabled. That leaves Codex no way of its own to read a file, so bees serves the session one MCP server of its own for the length of the turn, over loopback with a token only that session has: read_file, list_directory and search_files, which read the directory the session runs in and refuse any path or link outside it. An opencode session runs in pure mode as a private agent whose only tools are read, grep and glob, and the configuration it resolves is checked to have taken them before the model runs. It is refused when there is any file in tool/ or tools/ under ~/.config/opencode, $XDG_CONFIG_HOME/opencode, ~/.opencode, $OPENCODE_CONFIG_DIR or a .opencode directory from the repository checkout up to /: opencode would load it as a custom tool. Remove the file to review the pull request. A pi session loads no extension, skill, prompt template or context file, and gets only its read, grep, find and ls tools. No session runs the tests, builds the change or writes to the repository, and none inherits your factory’s identity: BEES_* and Git variables are dropped.

The sessions run as the agent provider or a profile names — claude, codex, opencode or pi — and an effort maps to each one’s reasoning setting: claude’s --effort, codex’s model_reasoning_effort (its levels stop at high, so max goes as high), the opencode agent’s variant and pi’s --thinking. Codex reports no cost, so a codex session’s cost is unknown rather than zero; claude, opencode and pi report one. An ask in triage reopens the angle’s session; codex has no resume, so a question about a finding a codex angle made is refused.

As the context is gathered, bees checks out the pull request’s head, in a container: an Alpine image with git, built the first time and kept, clones refs/pull/<number>/head of the pull request’s repository over HTTPS into the review’s checkout/ directory, fetches the base branch beside it, and exits. That is the head as it is on GitHub, whatever your working tree has checked out, and a fork’s pull request as much as one from a branch of the repository. The diff source reads the diff from that checkout, with your machine’s git, as the head against its merge base with the base branch, the diff GitHub shows: GitHub’s own diff is refused for a pull request that changes more than 300 files, and this one is not. When the head and the base branch have no merge base, the diff is against the base branch’s tip and the review lists that among the context it skipped. The angle sessions run in that same directory, on your machine, with the same read-only tools; nothing runs in the container after the clone. github.token authenticates the clone when it is set, handed to the container as an environment variable; without it the clone is anonymous, which a private repository refuses.

The checkout needs docker. Without it, or when the image does not build or the clone fails, the review says so and goes on: the diff is read with gh pr diff instead, and the angles run in the current directory when it is a checkout of the pull request’s repository (its origin remote points at it), and in the empty scratch/ directory of the review anywhere else. A diff that cannot be read either way is reported as not gathered, like any other source, and the review goes on without it.

The other sessions run where the angles would without that checkout: the distiller in the current directory when it is a checkout of the repository and in an empty temporary directory anywhere else, and the triage sessions of factory mode in the current directory or in scratch/. The sources that read files (style_files, callers and the project’s own) read the current directory when it is that checkout and gather nothing anywhere else.

Context sources

Source What it gathers
diff The pull request’s diff without its generated files, read from the checkout made for the review, or with gh pr diff when there is none
pr_body The title and body, then every comment and submitted review, oldest first
linked_issues The issues the pull request closes, then the others its body mentions, at most 20
style_files AGENTS.md, CLAUDE.md, CONTRIBUTING.md, STYLE.md and .editorconfig, plus the files style_sources names
callers The lines outside the changed files that name a function the diff declares: the first 20 functions, 40 lines each

Every one of them runs unless context.toml turns it off, and a project adds sources of its own that gather the files they name. See context.toml.

Generated files

A generated file is taken out of the diff before the distiller and the angles read it, so a change that regenerates a protobuf binding is sized and reviewed by what was written by hand. A file is generated when any of these says so:

The brief lists every file taken out, with the lines the change added and removed there and which of the three said it was generated, and a finding an angle anchors in one is dropped. The first two checks read the checkout of the pull request’s head; without one (no docker, or a clone that failed) only the patterns are checked, and the brief says so under what was not gathered. Triage still shows the whole diff.

Angles

Angle What it looks for
quick_general One light pass over the change as a whole, for what a careful reader catches on one read
general A thorough pass over the change as a whole: wrong logic, a dropped error, duplicated code, and a line that breaks a rule the project wrote down
docs A comment or doc comment the change made false, and prose the change wrote that the code does not bear out
test_coverage Behaviour with no test on it, a test that would pass with the change undone, and a document the change made false
acceptance_criteria A criterion from the brief the change does not meet, or meets only in part, and a behaviour change nothing asked for
side_effects A caller the change did not update, an invariant it no longer keeps, and a claim elsewhere in the repository it made false

The brief assigns the size automatically, from the scope and the risk of the diff, and a review runs the angles that size calls for:

Size Angles
xs, s quick_general, docs
m, l general, docs, test_coverage, acceptance_criteria
xl general, docs, test_coverage, acceptance_criteria, side_effects

A project’s angles.<angle> entry in context.toml still turns an angle off entirely; the size only narrows what is left on, and never re-enables an angle the project turned off.

An angle session is also told the rules in your reviewer notes about its angle, so it reports less of what you have dismissed before.

Findings

A finding is one problem, as the review keeps it in findings.json:

{
  "id": "1a2b3c4d",
  "angle": "test_coverage",
  "session_id": "5f0c...",
  "category": "missing test",
  "severity": "high",
  "file": "internal/review/gather.go",
  "lines": [12, 14],
  "side": "new",
  "title": "Gather has no test for a source that cannot read",
  "body": "The acceptance criterion says a source that cannot read ...",
  "evidence": "gather_test.go covers only sources that succeed",
  "sources": ["#566"]
}

body is two or three sentences: what is wrong and why it matters. What the angle read that shows it is in evidence, and where a rule or a requirement comes from is in sources. Triage shows the evidence under the body; a posted comment and a report carry the body and the suggestion without it.

file, lines and side are absent on a finding about the change as a whole. side is new for the file as the change leaves it and old for lines the change removed. suggestion, present when the angle could write it, is the text that would replace the lines.

The merge is the same for every review:

Jev boost

Set OPENROUTER_API_KEY in the environment of bees to enable Jev, TypeSafe’s System One model, for reviews with findings:

export OPENROUTER_API_KEY   # set its value in your shell or secret manager
bees review acme/widgets#7

With that variable unset or empty, reviews make no Jev request, write no Jev record or progress line, and keep the ordinary findings and order. A review with no findings also makes no request.

After merging, generated-file exclusion and reviewer-notes filtering, Jev estimates the probability that each finding is a correct, specific and actionable problem the author should address. Findings below 0.3 are removed; those at or above 0.3 reach triage in probability order, highest first. Ties keep merge order. Jev preserves each finding’s text, severity, ID and anchor, and does not add findings or change reviewer notes.

What Jev sees

Jev never receives the diff text, diff.patch or checkout file contents. Text an angle quotes in a finding’s body, suggestion or evidence is sent as part of that finding. The API key is sent only as the endpoint’s bearer credential; it is never written into prompts, logs or artifacts.

The request allows at most 48 KiB of state and 64 KiB on the wire. Context is shortened in this order: touched areas, excluded files, changed files, notes rules, style rules, acceptance criteria, summary, title. Each part is halved until it fits or becomes a shortening marker, before moving to the next. The guide, reference, size and complete findings are retained. If those alone cannot fit, the review falls back without a request.

Records and fallbacks

When Jev evaluates findings, jev.json beside findings.json records the outcome, fallback reason and detail, configured and answering models, probabilities, kept findings in ranked order, full eliminated findings, usage, request count, duration, policy version and threshold. A progress line says how many findings Jev ranked and eliminated, or why it fell back.

Invalid settings, oversized or rejected requests, timeouts, rate limits, provider outages, unusable responses and cooldowns all preserve the unboosted findings and order. Each request has a bounded timeout; a timeout or outage allows one retry. Rate limits and repeated outages start a cooldown shared by every review in the process. Cancelling only the Jev request also falls back. Cancelling the review itself keeps the caller’s cancellation handling; it does not complete the factory review round.

The factory’s developer-loop and requested reviews use agentcore’s default Jev settings when OPENROUTER_API_KEY is set for the bees process. One Judge serves every project scheduler, including projects added or restarted through reload, so a failure in one project can make another fall back with cooling_down without a provider request. The factory log carries the Jev line, and its judge session receives the ranked findings with eliminated ones removed. Later verification rounds use the saved findings and make no Jev request. The factory does not read the review configuration’s [jev] table; there is no bees.toml setting for the boost.

Reviewer notes

Your reviewer notes are one markdown file, reviewer-notes.md next to your config.toml unless notes_path says otherwise. Every finding you dismiss during triage appends a line to it, with the reason you gave:

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

bees review consolidate turns the dismissals that repeat into rules, written between two markers:

<!-- bees:review:rules -->
- [acme/widgets] [general] [naming] drop: receiver names are short here (3 dismissals)
- [*] [test_coverage] [*] downrank: generated files carry no tests (2 dismissals)
<!-- /bees:review:rules -->

A pattern dismissed twice becomes a downrank rule, three times or more a drop rule. Each review applies the rules to its list before triage: a matching finding is dropped, or ranked down one severity. * matches any repository, angle or category, and a rule with no text after the action matches every finding in its repository, angle and category. You can edit a rule, and consolidation keeps your wording and changes only its count. See bees review consolidate.

Triage

Triage takes the findings one at a time, most severe first:

Action What it does
select The finding goes into the review’s output, with its text as written or as you edited it
dismiss The finding is left out, and the reason is appended to your reviewer notes
defer The finding is left out of this review, and nothing is recorded
ask The angle that found it is asked a question, in its own session; a finding the answer turns up joins the queue

Every decision is written into the review’s directory as it is taken, and the latest select, dismiss or defer on a finding is the one in force. bees review triage <pr> reopens the latest review of a pull request and offers what is still undecided. See bees review triage for the keys, and factory mode for triage by an agent (--agent, --instructions).

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

How a review ends

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

--post approve|comment|reject or --report on the command line chooses. With neither, the output key of config.toml does, and its default, ask, asks you at the end. With --agent and ask, the agent chooses.

The three that post submit one review in one gh api call. A finding whose lines are all in the diff is a comment on them, with its suggestion as a suggestion block on the new side. Any other finding goes into the review’s summary, with where it points. comment and reject with nothing selected are refused; approve with nothing selected approves without comments.

The review directory

Every review is a directory under storage_path, written as the review goes:

~/.config/bees/reviews/acme/widgets/7/20260910-150405/
  brief.json            the brief, and the distiller's session id
  angles/<angle>.json   each angle's session id, directory and answer
  checkout/             the pull request's head, cloned for the diff and
                        the angles; also holds diff.patch, for every
                        angle to search
  scratch/              where the angles and triage ran without a checkout;
                        also holds diff.patch, on the same terms
  findings.json         the merged list, and what your notes hid from it
  triage.json           every triage decision, in order
  jev.json              the optional Jev judgment, including eliminated findings

The directory name is when the review started, in UTC. A review that stopped partway keeps what it reached; one that stopped before the brief was written leaves no directory. bees review triage reopens the newest directory of the pull request, and an ask resumes the angle’s session from its file under angles/. When the angles ran in your machine’s own checkout instead of one made for the review, diff.patch is not written there. Either way the diff is in every angle’s prompt.

Configuration

bees review reads two files of its own, and neither is bees.toml. Both are optional: a missing file loads as the defaults. An unknown key, or a value outside the ones listed, fails the command with an error naming the key. Below config.toml it reads defaults.toml, the user-level defaults the factory’s projects read too: for each setting, a command-line flag comes first, then config.toml, then defaults.toml, then the built-in default.

config.toml

Your own settings: ~/.config/bees/config.toml, or $XDG_CONFIG_HOME/bees/config.toml when XDG_CONFIG_HOME is an absolute path. --config reads another file.

provider = "claude"
model = "opus"
brief_model = "sonnet"
notes_path = "reviewer-notes.md"
storage_path = "reviews"
output = "ask"

[angles]
xs = ["quick_general"]

[angle_models]
docs = "haiku"

[github]
token = "$REVIEW_GH_TOKEN"
Key Type Default Meaning
provider string "claude" The agent a session without a profile runs as: claude, codex, opencode or pi
model string "opus" The model a session without a profile uses, unless a key below names another
brief_model string model The model of the distiller session that writes the brief
angle_models.<angle> string model The model of that angle’s session
judge_model string none Accepted and checked, and has no effect: the judge is not a session
profiles.<name> table none A profile: agent, model, fallback, effort and sandbox, as in bees.toml
brief_profile string none The profile the distiller session runs on
angle_profiles.<angle> string none The profile that angle’s session runs on
judge_profile string none Accepted and checked, and has no effect: the judge is not a session
angles.<size> list the built-in list The angles a change of that size is reviewed from
notes_path path "reviewer-notes.md" Your reviewer notes
storage_path path "reviews" The directory review directories are created in
output string "ask" How a review ends without --post or --report: ask, approve, comment, reject, report or discard
github.token string none The token the review’s gh calls use; without it, your own gh login
github.app_id, github.private_key int, string none A GitHub App the review acts as instead of a token, with private_key in the forms bees.toml takes
jev table agentcore defaults Optional ranking settings; see below
github.login string none Accepted so a [github] table from bees.toml moves across unchanged; a review does not use it

The optional [jev] table configures the Jev boost. These are agentcore’s defaults:

[jev]
url = "https://openrouter.ai/api"
model = "~typesafe/jev-latest"
api_key_env = "OPENROUTER_API_KEY"
timeout = "10s"

url is an HTTP(S) base URL without credentials, a query or a fragment; requests go to <url>/v1/systemone. model names a model in at most 128 characters without whitespace. api_key_env names the environment variable holding the key; its value never belongs in this file. timeout is positive and at most "1m", and bounds each request. Unknown keys and invalid values fail configuration loading with the key named, even when the boost is off. There is no separate enable setting: a nonempty value in api_key_env’s variable turns it on.

A path is absolute, starts with ~, or is relative to the directory config.toml is in, which puts the defaults at ~/.config/bees/reviewer-notes.md and ~/.config/bees/reviews/.

angles.<size> replaces the list Angles gives that size; <size> is xs, s, m, l or xl, and the list names at least one angle. context.toml still turns angles off on top of it. brief_model and angle_models change the model only; a session without a profile runs as provider.

A step with a profile runs as the profile’s agent, model and effort, with its fallback chain behind it, and ignores provider, model, brief_model and angle_models. The profiles are checked the way bees.toml checks them. To reuse a bees.toml reviewer setup, copy its [profiles.*] tables unchanged and move brief_profile, angle_profiles and judge_profile out of [roles.reviewer] to the top of config.toml. The other roles.reviewer keys, profile among them, are not config.toml keys and fail as unknown:

brief_profile = "default"
judge_profile = "default"
angle_profiles = { quick_general = "review_fast", docs = "review_fast" }

[profiles.default]
agent = "claude"
model = "opus"
fallback = "spare"
effort = "high"

[profiles.review_fast]
agent = "claude"
model = "opus"
effort = "medium"

[profiles.spare]
agent = "codex"
model = "gpt-5"

The distiller and the angles run as one of the four agents above, and so does every profile of their fallback chains. sandbox is checked and not used: every review session is read-only whatever the profile says.

judge_model and judge_profile give the file the shape of roles.reviewer in bees.toml, where the judge is a session; in bees review the judge is code and uses neither.

github.token takes a $VAR or ${VAR} reference, expanded from the environment, so the secret stays out of the file. A reference to a variable that is not set fails the command.

With app_id and private_key, the review reads the pull request, clones it and posts its review as the GitHub App, with installation tokens for the pull request’s repository. The App needs to be installed on that repository with the permissions [github] lists:

[github]
app_id = 123456
private_key = "~/.config/bees/busybees.pem"

defaults.toml

The user-level defaults beside config.toml: ~/.config/bees/defaults.toml, or $XDG_CONFIG_HOME/bees/defaults.toml when XDG_CONFIG_HOME is an absolute path. It is the file the factory’s projects read below their bees.toml, and it holds agent profiles, the reviewer selectors of a bees.toml, and [github]. With no config.toml, or one that sets none of these keys, a review runs on the same profiles the factory’s reviewer uses and acts as the same GitHub account.

version = 5

[profiles.default]
agent = "claude"
model = "opus"
fallback = "spare"
effort = "high"

[roles.reviewer]
profile = "default"
brief_profile = "default"
angle_profiles = { docs = "review_fast" }
angles = { xs = ["quick_general"] }

The file accepts only what a bees.toml accepts there: version, [profiles.<name>], global.profile and global.profile_by_size, every role’s profile and profile_by_size, and the reviewer’s brief_profile, angle_profiles, judge_profile and angles, and [github]. It must carry the version shown. Anything else is an error, as in config.toml.

For each setting the order is: a command-line flag, then config.toml, then defaults.toml, then the built-in default. defaults.toml supplies config.toml:

config.toml taken from defaults.toml when unset
[profiles.<name>] [profiles.<name>]: a name config.toml defines replaces the user one whole
angles.<size> roles.reviewer.angles.<size>
brief_profile roles.reviewer.brief_profile
angle_profiles.<angle> roles.reviewer.angle_profiles.<angle>
judge_profile roles.reviewer.judge_profile
provider, model the agent and model of the profile roles.reviewer.profile selects, else global.profile
[github] [github], whole, when config.toml has no [github] table: login, token, app_id and private_key

notes_path, storage_path, output, brief_model and angle_models have no counterpart there and stay config.toml-only.

The nearer file wins, whatever form it uses. Within one file a step’s profile beats its flat keys. Across files, a step config.toml configures at all takes nothing from defaults.toml. For the brief and the angles that is a profile or a step model; for the base it is the flat provider or model. A config.toml that says model = "sonnet" is never overridden by a profile defaults.toml set for the same step. The angles lists merge per size, the angle_profiles per angle, and the profiles per name, whether or not the other keys are set. [github] is one account and never merges key by key: a [github] table in config.toml, an empty one included, takes nothing from defaults.toml.

Validation happens after the merge, so the two files may refer to each other’s profiles; an error names the file that set the bad key. defaults.toml is read from its own location even when --config reads another config.toml.

context.toml

The project’s settings, committed to the repository under review. bees looks for it in the current directory and then each parent, and only when the current directory is a checkout of the pull request’s repository. Without one, a review runs every angle its size calls for and every built-in source, and pins no category.

style_sources = ["docs/style/*.md"]
generated = ["*.pb.go", "vendor/**"]

[angles]
side_effects = false

[categories]
naming = "low"
"missing test" = "high"
typo = "off"

[[context_sources]]
name = "callers"
enabled = false

[[context_sources]]
name = "architecture"
files = ["docs/architecture.md", "docs/adr/*.md"]
Key Type Default Meaning
angles.<angle> bool true false turns the angle off. <angle> is quick_general, general, docs, test_coverage, acceptance_criteria or side_effects
style_sources list of paths or globs [] Style documents the style_files source gathers on top of the built-in names
generated list of paths or globs [] Files taken out of the diff as generated, on top of the ones a header or .gitattributes marks
categories.<category> string none Pins every finding in the category to info, low, medium or high, or drops them with off
context_sources list of tables none Turns a built-in source off, or adds a source of the project’s own

A [[context_sources]] entry has a name, and:

Paths and globs are relative to the directory context.toml is in and must stay inside it. A generated pattern is relative to the repository root, as the diff names files: *, ? and [...] match within one path segment and ** any number of them, a pattern with no / matches a file’s name in any directory, and a pattern that matches a directory matches every file under it.

A category is the angle’s own word for a kind of problem, lowercased: triage shows it next to the severity, and it is the third field of a dismissal in your reviewer notes. A pin matches it whatever case context.toml writes it in.