How to Build a PR Review Agent with the Cursor Agent SDK

This article walks through a real production pattern: an automated Bitbucket PR reviewer built on the Cursor Agent SDK, with local repo clones, Jira requirements context, structured verdicts, and cost tracking. The snippets are condensed from that system — adapt the host-specific parts to GitHub or GitLab.

Why automate the mechanical pass

Human review time is the bottleneck of every merge pipeline, and a large share of review work is mechanical: checking that the diff matches the ticket, that it follows the repo's conventions, that nothing unrelated snuck in, that obvious correctness and security traps were avoided. That pass is well-defined enough for an agent — and automating it frees the people who review for the parts that actually need judgment: architecture, trade-offs, product semantics.

The goal is not to replace the reviewer. It is to give every PR a competent first pass within minutes of being opened, with the same standards every time, and to re-check it when the branch moves. A bot that catches the regression before a human looks at the PR is worth more than one that argues about style after a human has already read it.

What the Cursor Agent SDK gives you

The SDK turns the Cursor agent — the same one that works inside the editor — into a library you call from a script. The core is a bridge process that attaches to a workspace folder, plus a handful of RPCs: CreateAgent spawns an agent with a model, credentials, and optional MCP servers; Send hands it a prompt; then you stream status, tool calls, thinking, and usage messages until the run finishes and returns the result.

The pipeline at a glance

Getting the diff right: review the change, not the branch

The diff is the agent's primary input, so it has to be the change — not the full divergence between two long-lived branches. The reliable way is the three-dot diff: compute the merge-base of the destination and source branch tips, then diff that base against the source tip. Everything the source branch adds, edits, or removes relative to where it forked is exactly what the PR is.

# merge-base of the two tips, then diff base...source
base=$(git merge-base origin/main origin/feature)
git diff --stat "$base" origin/feature
git diff "$base" origin/feature          # unified diff for the prompt

# fallback when history is shallow and no merge-base exists:
# deepen (or unshallow) the clone first, then retry; last resort:
git diff origin/main origin/feature      # tip-to-tip

Two practical traps matter in automation. First, shallow clones often hide the merge-base — deepen the clone when git merge-base comes back empty before falling back to tip-to-tip. Second, cap the diff: a 30-file refactor as a single 50,000-line prompt is both expensive and a worse review. Truncating at a line budget and noting the truncation keeps the agent's attention on the meaningful parts.

Context is what makes the review specific

A raw diff review reads like a linter. To get findings a team can act on, the prompt needs the same context a human reviewer collects before commenting: what the PR claims to do, what the ticket requires, and how this codebase is supposed to be written.

Lock the reply shape

An agent is only as useful as its output format. The prompt pins the reply to three sections, demands CRITICAL and MAJOR issues only (no nits, no style commentary), and specifies a one-line verdict. Structured output is what makes the result postable, comparable across PRs, and machine-readable for the state machine.

Reply in markdown with ONLY these sections:
### Summary
2-4 sentences: what changed, and whether it matches the Jira requirements.
### Issues
CRITICAL/MAJOR only. Each bullet: `[SEVERITY] file/symbol — problem; fix`.
### Verdict
One line: `approve` / `request changes` / `needs discussion` — brief reason.

If the verdict is approve, end the reply with this exact line:
![APPROVED](https://example.com/approved.png)

The SDK call itself

With the diff and the prompt ready, the agent call is small: launch the bridge into the repo, create an agent with a model and the repo as its workspace, send the prompt, stream the run, and read the final result. Optional MCP servers (for example an LSP bridge so the agent can resolve symbol definitions and references instead of grepping) attach at creation time.

from cursor_sdk import Client, AgentOptions, LocalAgentOptions
from cursor_sdk_helpers import cursor_agent_model

local = LocalAgentOptions(cwd=str(repo_dir))
client = Client.launch_bridge(workspace=str(repo_dir), local=local)
try:
    agent_options = AgentOptions(
        model=cursor_agent_model("composer-2.5", default="composer-2.5"),
        api_key=api_key,
        local=local,
        mcp_servers=mcp_servers or None,   # optional LSP bridge
    )
    with client.create_agent(agent_options) as agent:
        run = agent.send(prompt)
        for message in run.messages():     # status / tool_call / thinking / usage / assistant
            log(message)                   # progress + token usage as it streams
        result = run.wait()
        review = str(result.result)
finally:
    client.close()

The model matters less than the context: the same prompt shape that works on the default model also works on cheaper and faster ones, which is exactly the knob you want for cost control (more on that below). The cursor_agent_model helper normalizes a model name with a fallback so a typo or a retired model never silently downgrades your reviews.

Robustness: what makes it run unattended

Error handling is where the SDK surface matters most. The library distinguishes retryable failures — NetworkError, RateLimitError, internal 5xx states, and anything marked retryable on the exception — from definite ones like authentication errors:

from cursor_sdk import CursorAgentError, NetworkError, RateLimitError

def should_retry(exc):
    if isinstance(exc, (NetworkError, RateLimitError)):
        return True
    if isinstance(exc, CursorAgentError):
        return getattr(exc, "is_retryable", False)   # 5xx, upstream, unavailable
    return False

# on retryable failure: sleep (retry_after if present) and re-run the agent;
# on anything else: mark the PR as error and move on.

Cost control: know what every review costs

A review bot burns tokens on every run, so cost visibility is not optional. The SDK reports token usage per run (input, output, cache reads and writes); the pipeline converts that into an estimated dollar cost using published per-model rates, and logs it with every review. Two levers keep the bill sane: model choice and diff budget.

What to ship in the first version

A minimal v1 is about two hundred lines: load open PRs, verify them on origin, three-dot diff with truncation, build the prompt from PR + Jira + preferences, call the agent, post the comment, save state. Start without the LSP bridge and without follow-up re-review, then add them once the baseline is stable:

Common mistakes

Where LogNroll fits

A PR review agent answers is this code right; session replay answers what did users actually experience. The two belong together. When the bot flags a checkout-path change as a CRITICAL regression risk, the fastest way to size the blast radius is to watch real sessions: replay the users who hit that flow, open the network tab for the failed calls, and check whether error groups on the same code path started growing. A review finding becomes actionable the moment you can see its effect on real users.

That is why we built LogNroll the way we did: recordings, error tracking, and network timelines live in one place, so a verdict from an automated reviewer — or a human one — can be validated against production behavior instead of argued about. For the capture pipeline behind it, see our session replay architecture guide; for turning a flagged regression into a debugging session, read When Error Logs Lie: Reproducing Production Failures with Session Replay, and for tracing the network side of a suspected regression, Network Tab + Replay: Debug Failed API Calls in Context.

Conclusion

Building a PR review agent on the Cursor Agent SDK is a small project with an outsized payoff. The pieces are simple once you see them: load and verify the PRs, compute the merge-base diff, assemble context from the ticket and your code preferences, lock the reply shape, and wrap the SDK's four-call loop in retries, state, and cost tracking. The result is a reviewer that is fast, consistent, and always available — one that takes the mechanical pass off your team's plate and leaves the judgment calls to the people who should be making them.