Optibot CLI Agent Review Mode

Agent mode is a fast review built for coding agents such as Claude Code and Cursor, or any automation that already has your working copy. It returns a compact list of structured findings in seconds, so an agent can check its work after every edit.

optibot review --agent --json

Agent mode needs CLI 0.8.0 or later. If --agent returns unknown option, run npm install -g @optimalai/optibot@latest. See Updating.

Agent mode vs full mode

Plain optibot review (full mode) runs the same multi-pass review Optibot runs on your pull requests. It gathers context from across your repository, runs extra passes to find more issues and confirm each one, and applies your team’s review memory.

Agent mode trades some of that depth for speed. It still applies your repository’s review guidelines and settings, with these limitations:

One review pass. It skips the extra passes full mode uses to catch more issues and double-check each finding.
No review memory. It can flag something your team has already told Optibot to skip.
Only the context you send. It reviews the diff plus any files you or the CLI attach, so it can miss issues in code it was not given.
Structured findings only. There is no prose summary or file-by-file comments.

Use agent mode when	Use full mode when
A coding agent wants quick feedback on each edit.	A person will read the review.
You need findings a program can act on.	You want the prose summary and file comments.
The change is the size of a typical agent edit.	The change is large or spans many files.

Flags

Flag	Description
`--agent`	Runs the review in agent mode.
`--json`	Prints only the JSON response to stdout. Errors go to stderr as JSON.
`--related <path>`	Attaches an extra context file, such as a caller or a test. Repeat it once per file.
`--diagnostics <file>`	Attaches local compiler or linter output (for example `tsc --noEmit` or `eslint`) so the reviewer can use real diagnostics.
`--max-agent-rounds <n>`	Caps review rounds, including automatic follow-ups for missing context. `1` to `3`, default `2`.
`--fail-on-issues`	Exits non-zero when the review does not pass, for CI or a pre-push hook.
`--sync`	Runs one blocking request instead of the default submit-and-poll. Only needed for older self-hosted backends.

Missing context

Agent mode reviews only what it receives. When the reviewer needs a file outside the diff, it lists the path in missingContext, and the CLI reads that file from your working copy and runs the review again automatically. At the default of --max-agent-rounds 2, that is the first pass plus one follow-up.

If you already know which files matter, attach them up front to skip the follow-up:

optibot review --agent --json \
  --related src/db/queryBuilder.ts \
  --related src/db/queryBuilder.test.ts

Each round is a separate review and counts once against your quota. Findings are not matched across rounds by id, so the CLI dedupes them on file, line range, and category. Do the same if you read the JSON yourself.

MCP server

The same review is available as the review_agent tool in the Optibot MCP server, for hosts such as Cursor, Claude Desktop, and Windsurf. It accepts relatedPaths and diagnosticsPath, but it does not follow up on missing context automatically: the host calls the tool again with the requested files.

Structured findings

{
  "status": "needs_changes",
  "reviewPass": false,
  "findings": [
    {
      "id": "AF-72ede9c284",
      "file": "src/app.ts",
      "startLine": 42,
      "endLine": 44,
      "inPatch": true,
      "severity": "blocker",
      "category": "security",
      "message": "User input is interpolated directly into the SQL query.",
      "suggestedFix": "Use a parameterized query instead.",
      "confidence": 9
    }
  ],
  "summary": "One blocker: a SQL injection risk in the new query builder.",
  "reviewCount": { "current": 3, "limit": 200, "remaining": 197 },
  "isOptibotInstalled": true,
  "meta": { "mode": "agent", "durationMs": 8421 }
}

Field	Description
`id`	Refers to the finding within this response. It changes between runs, so compare file, line range, and category to spot repeats.
`file`, `startLine`, `endLine`	Where the finding is.
`inPatch`	`true` when the lines are inside the changed ranges. `false` findings are still valid and are returned, not dropped.
`severity`	`blocker`, `warning`, or `nit`.
`category`	`bug`, `security`, `performance`, `refactor`, `tech-debt`, `duplicate`, `style`, `documentation`, `test`, or `other`.
`message`	The finding.
`suggestedFix`	A concrete fix, when the reviewer has one.
`confidence`	From 1 to 10.

At the top level, status is needs_changes or looks_good, reviewPass is what --fail-on-issues checks, and meta.durationMs is how long the review took. meta also carries a few informational fields about the run.

Quota

Agent reviews count toward your organization’s review allowance, the same one your pull request reviews use. There is no separate CLI limit by default.

Trial organizations use their trial allowance for agent reviews like any other review. Paid plans have no review ceiling unless one was set for your organization.
An optional daily per-user cap can be turned on for an organization as an abuse guardrail. When it runs out, the request returns a 429 with the current count and when the next review frees up. reviewCount in each response reports this cap.

Large or long reviews

There is no limit on diff size; a 3.5-million-character diff was reviewed in testing. Two limits can still stop a review, and the CLI tells you which:

Too much input to read at once. Run plain optibot review, which handles larger changes.
Over ten minutes. Run it again or review a smaller set of changes.

With --json, these arrive on stderr with an errorType of context_window_exceeded or timeout.

New to the CLI? Start with Installation & getting started, or see CLI for agents & CI/CD pipelines for headless authentication with an API key.