Review Process¶
The bot fetches the PR diff, runs an AI agent with read-only tools, and posts a structured inline code review.
How to Trigger¶
Mention the bot by its configured username in a PR/MR comment:
You can optionally include specific instructions:
The bot can also run automatically on PR lifecycle events — see Auto-Trigger.
What It Does¶
- Clones the repository (or updates an existing workspace) to the PR's head branch.
- Concurrently fetches the full PR diff and existing comments.
- Builds a prompt that includes the diff, existing discussion context, and any user instructions.
- Runs the agent in the cloned workspace with restricted tools.
- Parses the agent's JSON output into a structured review.
- Posts the review as native inline comments on the PR/MR.
Restricted Tool Set¶
The bot runs with bypassPermissions mode but is limited to these tools:
| Tool | Purpose |
|---|---|
Read |
Read file contents |
Glob |
Find files by pattern |
Grep |
Search file contents |
Bash(git clone*) |
Clone private dependencies into .deps/ |
The bot cannot modify files, run arbitrary commands, or push commits. See Security — Tool Restrictions.
JSON Output and Retry Logic¶
The agent must output strict JSON matching this format:
{
"summary": "Overall review summary",
"comments": [
{
"path": "src/main.py",
"line": 42,
"body": "This variable is unused."
}
]
}
If the agent's output is not valid JSON, the bot retries up to 2 times with a corrective prompt. If all retries fail, the raw output is posted as a plain comment.
When findings exist, they are posted as a native code review with inline comments on the specific lines. If there are no findings, only the summary is posted as a plain comment.
Cross-File Review¶
The reviewer is not limited to the lines changed in the PR. It actively checks for knock-on effects elsewhere in the repository — for example, callers that were not updated after a function signature change, or stale references to a renamed config key.
Findings that target lines within the diff are posted as native inline comments. Findings that reference files or lines outside the diff are automatically folded into the general review body under an Additional notes (not in diff) section, since the GitHub/GitLab API only supports inline comments on diff lines.
This means no review feedback is lost, regardless of where in the codebase the issue is found.
Existing Discussion Context¶
Before running the agent, the bot fetches all existing comments on the PR to avoid duplicating previously raised issues:
- Comments authored by the bot itself are filtered out.
- Only the 50 most recent non-bot comments are included.
- Resolved threads are tagged as such — the agent is instructed to skip them.
- On GitHub, both conversation comments and inline review comments are fetched.
- On GitLab, all discussion notes are fetched (excluding system notes).
Running in Different Modes¶
The bot is available in all three modes: