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
- Context. bees gathers the pull request’s context from the sources
context.tomlenables: 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. - Brief. One session, the distiller, reads everything gathered and
writes the brief: what the change does, its size (
xs,s,m,lorxl, 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. - Angles. One session per angle the brief’s size calls for
and
context.tomlenables 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. - 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.
- 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. - 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:
- a line
// Code generated ... DO NOT EDIT.in its first 64 lines (and its first 16 KiB), on the side the change leaves it (the old side for a file the change deleted); .gitattributesin the checkout marks itlinguist-generated, as git reads the file (git check-attr);- a pattern in
context.toml’sgeneratedlist matches it.
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:
- Severity is one of
info,low,mediumandhigh. The words a session uses instead are mapped onto them (criticalandblockerarehigh,nitislow,fyiisinfo), and a word bees does not know ismedium. A categorycontext.tomlpins takes the pinned severity, and a category pinnedoffis dropped. - The same problem from two angles is kept once: two findings on the
same file and side with overlapping lines, in the same category or worded
alike, or two findings about the whole change worded alike. The more
severe one is kept, with the other angle’s name in
also_from. - Order is most severe first.
- The id is a hash of the file, side, lines and title, so a finding keeps its id when the list is merged again.
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
- A guide defining what makes a finding worth raising.
- The brief’s pull request reference, title, summary, size, acceptance criteria and style rules with their sources, and touched areas.
- Changed-file paths with added and removed line counts, and the generated files excluded from the review.
- Reviewer-notes rules, when present.
- Every finding’s angle and other reporting angles, category, severity, file, line range, side, title, body, suggestion, evidence and sources.
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:
- For a built-in source (
diff,pr_body,linked_issues,style_files,callers),enabled = falseturns it off. It takes nofiles. - For a name of your own,
fileslists the paths or globs to gather, andenabled = falseturns it off without deleting the entry. A pattern that matches nothing is reported in the brief as not gathered.
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.