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, and the context step described below needs 0.11.0 or later. If --agent or --no-scout 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 in-depth review Optibot runs on your pull requests, with context from across your repository and your team’s review memory.

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

• A lighter review. It gives up some of full mode’s depth for speed, so it can catch fewer issues.
• No review memory. It can flag something your team has already told Optibot to skip.
• Only the context it is given. It reviews the diff plus the files the CLI or you 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.

Which mode for which change size

Agent mode is up to 7.2x faster than full mode on small changes, and its advantage shrinks as the change grows. For the largest changes, use full mode, or split the change.

This page is updated as new versions ship.

Context step

On larger changes, the CLI runs a short context step before the review. It gathers the context the review needs from your working copy, so more reviews finish in one pass.

• The step and the review count as one review against your quota.
• It reads only what is safe to send. It picks only files git tracks, and it skips files git ignores, binary files, credential files, and files whose content contains a key or token. Before reading anything, the CLI names the files it picked.
• It never fails a review. If the step is unavailable or takes too long, the review runs without it.
• It runs only on larger changes, so small reviews are as fast as before.

Turn it off with --no-scout:

optibot review --agent --json --no-scout

New files

The review covers every file your change adds, including new files you have not run git add on yet. A change made only of new files is reviewed like any other change. Files git ignores are left out.

A new file whose name marks it as a credential file, such as .env, or whose content contains a private key or an API token, is not sent. Without --json, the CLI names each skipped file on stderr. Either way, it reviews the rest.

Flags

--related, --no-scout, and --max-agent-rounds only apply with --agent. Passed without it, the CLI warns that they were ignored (one JSON line on stderr under --json) and runs a full review.

Missing context

Agent mode reviews only what it receives. When the reviewer still 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. With the context step, this follow-up is the exception on larger changes rather than the rule.

The CLI never sends credentials or other sensitive files this way. Any file it skips is named on stderr, and the review runs without it.

If you already know which files matter, attach them up front:

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

Each follow-up 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. From @optimalai/optibot-mcp 1.7.0, it runs the same context step on larger changes and reviews new files. Pass scout: false to turn the step off. 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.

Shared review rules

Agent mode applies the shared review rules mapped to the repository you’re reviewing. There is nothing to turn on. Optibot finds the repository by its name:

• CLI 0.11.0 and later, and MCP server 1.7.0 and later, read the name from your origin remote.
• Older CLIs use the name of your local folder. A clone in a renamed folder, or a worktree, then runs without rules. Update the CLI to fix this.
• --diff <file> reviews have no repository, so they never apply shared rules.

To stop applying shared rules, click Disable shared rules on the Shared Review Rules page. That turns them off for every review, not just agent mode.

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
  }
}

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.

summary is a short overview of the review. When shared review rules applied, it ends with a line naming them:

Applied organization-wide rules (from engineering-standards): rules/logging.md, rules/naming.md

A file marked (cut short) was too long to use in full.

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 the total size of a diff, but a file whose own diff is longer than 100,000 characters is left out of the review. Agent mode is not the right tool for the largest changes, though: see Which mode for which change size. 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.