Build an AI Code Review Agent with the Claude Agent SDK — A Complete Tutorial

Why Build Your Own Code Review Agent?

The AI code review market is growing fast — tools like CodeRabbit, Sourcery, and GitHub Copilot's built-in review all compete for your attention and your budget. But they all share a fundamental limitation: they are black boxes. You cannot see the prompts, customize the review logic, or audit what happens to your code.

When I built CodeSentri, an open-source AI code review bot, I proved that you can build a production-grade reviewer in a single day. The architecture was straightforward — Express.js server, GitHub webhooks, Anthropic API, PostgreSQL for billing. But the core review engine was a direct API call with a handcrafted prompt.

The Claude Agent SDK changes the equation. Instead of managing the tool loop yourself — sending prompts, parsing tool calls, executing tools, feeding results back — the SDK handles all of that automatically. You define what tools the agent can use, write a system prompt, and let the agentic loop do the rest.

In this tutorial, you will build a code review agent from scratch using the Claude Agent SDK in Python. By the end, you will have a working agent that:

1. Reads code files and analyzes them for bugs and vulnerabilities
2. Classifies findings by severity (Critical, Warning, Suggestion)
3. Provides specific fix recommendations with code suggestions
4. Outputs structured JSON for integration with GitHub, GitLab, or any CI/CD pipeline

This is the same architecture that powers CodeSentri's review engine, simplified for learning. If you have read our foundational Agent SDK tutorial, this builds on those concepts with a focused, real-world application.

Prerequisites

Before starting, make sure you have:

• Python 3.10+ installed
• An Anthropic API key from platform.claude.com
• Basic familiarity with Python async/await
• A code editor (VS Code, Cursor, or similar)

If you have never used the Claude Agent SDK before, the official quickstart is a good five-minute primer. But this tutorial is self-contained — you can follow along without prior SDK experience.

Step 1: Project Setup

Create a new project directory and install the Claude Agent SDK.

mkdir code-review-agent && cd code-review-agent
python3 -m venv .venv && source .venv/bin/activate
pip install claude-agent-sdk

Create a .env file with your API key:

ANTHROPIC_API_KEY=your-api-key-here

Step 2: Your First Review Agent

The simplest possible code review agent needs three things: a prompt telling Claude to review code, tools to read files, and the agentic loop to execute the review.

Create reviewer.py:

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ResultMessage


REVIEW_PROMPT = """
Review all Python files in this directory for:
1. Security vulnerabilities (SQL injection, XSS, command injection)
2. Bugs (off-by-one errors, null references, race conditions)
3. Missing error handling

For each issue found, report:
- File path and line number
- Severity: CRITICAL, WARNING, or SUGGESTION
- Description of the issue
- Recommended fix with code example
"""


async def main():
    print("Starting code review...\n")

    async for message in query(
        prompt=REVIEW_PROMPT,
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Glob", "Grep"],
        ),
    ):
        if isinstance(message, AssistantMessage):
            for block in message.content:
                if hasattr(block, "text"):
                    print(block.text)
        elif isinstance(message, ResultMessage):
            print("\nReview complete.")


asyncio.run(main())

This agent uses three built-in tools:

• Read — reads file contents
• Glob — finds files by pattern (e.g., **/*.py)
• Grep — searches file contents with regex

Notice what you did not need to implement: file reading logic, a tool execution loop, context management, or retry handling. The Agent SDK handles all of that. You just define the tools and the prompt.

Test It

Create a test file with intentional vulnerabilities. Create sample_app.py:

import sqlite3


def get_user(db_path, username):
    conn = sqlite3.connect(db_path)
    cursor = conn.cursor()
    query = f"SELECT * FROM users WHERE username = '{username}'"
    cursor.execute(query)
    return cursor.fetchone()


def process_items(items):
    for i in range(0, len(items) + 1):
        print(items[i])


async def fetch_data(url):
    import aiohttp
    async with aiohttp.ClientSession() as session:
        response = await session.get(url)
        data = response.json()
        return data

Run the agent:

python3 reviewer.py

Claude will find all three bugs: the SQL injection in get_user, the off-by-one error in process_items, and the missing await on response.json(). This is the same class of vulnerabilities that CodeSentri catches on every pull request — but here you can see exactly how the agent reasons about them.

Claude's detection rates across common vulnerability categories when given appropriate system prompts and file access tools.

Step 3: System Prompt Engineering

The basic agent works, but the output is unstructured text. To build a production-quality reviewer, you need a system prompt that produces consistent, structured findings. This is the most important piece of any AI code review tool — the prompt is the product.

Replace the REVIEW_PROMPT with a production-grade system prompt:

SYSTEM_PROMPT = """You are an expert code reviewer specializing in security
vulnerabilities, bugs, and code quality. You have deep knowledge of the OWASP
Top 10, common programming pitfalls, and language-specific best practices.

Review Rules

1. ONLY review code files. Skip configuration, documentation, and generated files.
2. Focus on issues that could cause security vulnerabilities, crashes, data loss, or incorrect behavior.
3. Do NOT comment on style, formatting, or naming conventions unless they indicate a bug.
4. Every finding MUST include a specific, actionable fix.
5. Classify each finding by severity:
   • CRITICAL: Security vulnerabilities, data loss risks, crashes in production
   • WARNING: Bugs, logic errors, race conditions that affect correctness
   • SUGGESTION: Missing error handling, performance issues, better approaches

Output Format

Return your findings as a JSON array. Each finding must have:

• "file": file path
• "line": line number (integer)
• "severity": "CRITICAL" | "WARNING" | "SUGGESTION"
• "title": short title (under 80 chars)
• "message": detailed explanation of the issue and why it matters
• "suggestion": the corrected code (optional but preferred)

If no issues are found, return an empty array: []

Important

• Be precise about line numbers.
• Do not fabricate issues. Only report genuine problems.
• Explain WHY each issue matters, not just WHAT it is. """

REVIEW_PROMPT = "Review all code files in this directory for security vulnerabilities, bugs, and quality issues. Return findings as JSON."

Update the agent to use a custom system prompt:

```python
async def main():
    print("Starting code review...\n")

    async for message in query(
        prompt=REVIEW_PROMPT,
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Glob", "Grep"],
            system_prompt=SYSTEM_PROMPT,
        ),
    ):
        if isinstance(message, AssistantMessage):
            for block in message.content:
                if hasattr(block, "text"):
                    print(block.text)
        elif isinstance(message, ResultMessage):
            print("\nReview complete.")


asyncio.run(main())

The key additions in this system prompt:

• Severity classification with clear definitions for each level
• Structured JSON output for machine-readable results
• Anti-nitpick rules that prevent style comments
• Mandatory fix suggestions so every finding is actionable

This is the same prompt architecture that powers CodeSentri's review engine. The difference between a useful AI reviewer and an annoying one is entirely in the prompt — as we discussed in the AI code review landscape analysis.

Step 4: Structured Output Parsing

The agent now returns JSON in its output, but it is embedded in Claude's conversational text. You need to extract the JSON array from the response.

Create parser.py:

import json
import re


def extract_findings(text: str) -> list[dict]:
    """Extract JSON findings array from Claude's response text."""
    # Try to find a JSON array in the text
    patterns = [
        r'```json\s*(\[[\s\S]*?\])\s*```',  # ```json [...] ```
        r'```\s*(\[[\s\S]*?\])\s*```',        # ``` [...] ```
        r'(\[[\s\S]*?\])',                      # bare [...] array
    ]

    for pattern in patterns:
        match = re.search(pattern, text)
        if match:
            try:
                findings = json.loads(match.group(1))
                if isinstance(findings, list):
                    return findings
            except json.JSONDecodeError:
                continue

    return []


def format_finding(finding: dict) -> str:
    """Format a single finding for terminal output."""
    severity = finding.get("severity", "UNKNOWN")
    icons = {"CRITICAL": "🔴", "WARNING": "🟡", "SUGGESTION": "🔵"}
    icon = icons.get(severity, "⚪")

    lines = [
        f"{icon} {severity}: {finding.get('title', 'Untitled')}",
        f"   File: {finding.get('file', 'unknown')}:{finding.get('line', '?')}",
        f"   {finding.get('message', '')}",
    ]

    if finding.get("suggestion"):
        lines.append(f"   Fix: {finding['suggestion']}")

    return "\n".join(lines)

Now update reviewer.py to collect and parse the output:

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ResultMessage
from parser import extract_findings, format_finding


SYSTEM_PROMPT = """..."""  # Same system prompt from Step 3
REVIEW_PROMPT = "Review all code files in this directory for security vulnerabilities, bugs, and quality issues. Return findings as JSON."


async def review_code(target_dir: str = ".") -> list[dict]:
    """Run the code review agent and return structured findings."""
    collected_text = []

    async for message in query(
        prompt=REVIEW_PROMPT,
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Glob", "Grep"],
            system_prompt=SYSTEM_PROMPT,
            cwd=target_dir,
        ),
    ):
        if isinstance(message, AssistantMessage):
            for block in message.content:
                if hasattr(block, "text"):
                    collected_text.append(block.text)

    full_text = "\n".join(collected_text)
    return extract_findings(full_text)


async def main():
    print("🔍 Starting AI code review...\n")

    findings = await review_code(".")

    if not findings:
        print("✅ No issues found. Code looks good!")
        return

    print(f"Found {len(findings)} issue(s):\n")

    critical = [f for f in findings if f.get("severity") == "CRITICAL"]
    warnings = [f for f in findings if f.get("severity") == "WARNING"]
    suggestions = [f for f in findings if f.get("severity") == "SUGGESTION"]

    for finding in critical + warnings + suggestions:
        print(format_finding(finding))
        print()

    # Summary
    print("---")
    print(f"🔴 Critical: {len(critical)}")
    print(f"🟡 Warning: {len(warnings)}")
    print(f"🔵 Suggestion: {len(suggestions)}")

    # Exit with non-zero code if critical issues found (useful for CI/CD)
    if critical:
        exit(1)


asyncio.run(main())

Now your agent returns structured data that you can pipe into any CI/CD system. The exit(1) on critical findings means you can use this agent as a gate in your build pipeline — exactly how CodeSentri blocks PRs with critical vulnerabilities.

Typical distribution of findings when reviewing production codebases. Most findings are suggestions — critical vulnerabilities are rare but high-impact.

Step 5: Custom MCP Tool for Diff Parsing

The basic agent reviews entire files. For pull request workflows, you want to review only the changed lines — this reduces noise, saves tokens, and focuses the review on what actually changed. The Claude Agent SDK supports custom tools via the Model Context Protocol (MCP).

Create diff_tool.py:

import subprocess
from claude_agent_sdk import tool, create_sdk_mcp_server


@tool(
    name="get_git_diff",
    description="Get the git diff for staged changes or between two commits. Returns the unified diff output showing added, removed, and modified lines.",
    input_schema={
        "type": "object",
        "properties": {
            "target": {
                "type": "string",
                "description": "What to diff. Options: 'staged' for staged changes, 'head' for last commit, or a commit hash/branch name to compare against.",
                "default": "staged",
            }
        },
    },
)
async def get_git_diff(args: dict) -> dict:
    """Get git diff as a custom MCP tool."""
    target = args.get("target", "staged")

    if target == "staged":
        cmd = ["git", "diff", "--cached"]
    elif target == "head":
        cmd = ["git", "diff", "HEAD~1"]
    else:
        cmd = ["git", "diff", target]

    try:
        result = subprocess.run(cmd, capture_output=True, text=True, timeout=30)
        diff_output = result.stdout

        if not diff_output.strip():
            return {
                "content": [
                    {"type": "text", "text": "No changes found for the specified target."}
                ]
            }

        return {"content": [{"type": "text", "text": diff_output}]}

    except subprocess.TimeoutExpired:
        return {
            "content": [{"type": "text", "text": "Error: git diff command timed out."}]
        }
    except FileNotFoundError:
        return {
            "content": [
                {"type": "text", "text": "Error: git is not installed or not in PATH."}
            ]
        }


# Create the MCP server
diff_server = create_sdk_mcp_server(
    name="diff-tools",
    version="1.0.0",
    tools=[get_git_diff],
)

Now update reviewer.py to use the custom diff tool:

from diff_tool import diff_server

DIFF_REVIEW_PROMPT = """Get the git diff for staged changes, then review ONLY
the changed lines for security vulnerabilities, bugs, and quality issues.
Focus exclusively on added or modified code (lines starting with +).
Do not review deleted code or unchanged context lines.
Return findings as JSON."""


async def review_diff() -> list[dict]:
    """Review only staged git changes."""
    collected_text = []

    async for message in query(
        prompt=DIFF_REVIEW_PROMPT,
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Glob", "Grep"],
            system_prompt=SYSTEM_PROMPT,
            mcp_servers={"diff": diff_server},
        ),
    ):
        if isinstance(message, AssistantMessage):
            for block in message.content:
                if hasattr(block, "text"):
                    collected_text.append(block.text)

    full_text = "\n".join(collected_text)
    return extract_findings(full_text)

The @tool decorator defines the tool's name, description, and input schema. The create_sdk_mcp_server function wraps it into an in-process MCP server that runs directly in your Python application — no separate process, no network overhead. When the agent needs the diff, it calls get_git_diff through the MCP protocol, and the SDK handles the execution automatically.

This is the same diff-first approach that CodeSentri uses in production — reviewing only changed lines keeps the review focused and reduces API costs by 60-80% compared to reviewing entire files.

Token usage and cost comparison between full-file and diff-only review approaches. Diff-only review uses 75% fewer tokens while producing more focused results.

Step 6: Subagent Architecture

For large codebases, a single review pass may not be thorough enough. The Claude Agent SDK supports subagents — specialized agents that handle focused subtasks. You can create a security agent, a logic agent, and a performance agent, each with tailored prompts.

Create multi_reviewer.py:

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition, AssistantMessage
from parser import extract_findings, format_finding
from diff_tool import diff_server


SYSTEM_PROMPT = """You are a code review orchestrator. You coordinate
specialized review agents to provide comprehensive code analysis.

Delegate reviews to the appropriate specialist agents, collect their
findings, and present a unified report as a JSON array."""


async def multi_review(target_dir: str = ".") -> list[dict]:
    """Run multi-agent code review with specialized subagents."""
    collected_text = []

    async for message in query(
        prompt="""Review all code files in this directory using the specialized
        agents: use security-reviewer for vulnerability analysis,
        logic-reviewer for bug detection, and performance-reviewer for
        optimization opportunities. Combine all findings into a single
        JSON array.""",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Glob", "Grep", "Agent"],
            system_prompt=SYSTEM_PROMPT,
            mcp_servers={"diff": diff_server},
            cwd=target_dir,
            agents={
                "security-reviewer": AgentDefinition(
                    description="Security vulnerability specialist. Finds SQL injection, XSS, auth issues, and OWASP Top 10 vulnerabilities.",
                    prompt="""You are a security expert. Review code for:
                    - SQL injection and NoSQL injection
                    - Cross-site scripting (XSS)
                    - Authentication and authorization flaws
                    - Sensitive data exposure
                    - Command injection
                    - Path traversal
                    Return findings as JSON with severity CRITICAL or WARNING.""",
                    tools=["Read", "Glob", "Grep"],
                ),
                "logic-reviewer": AgentDefinition(
                    description="Bug and logic error specialist. Finds off-by-one errors, null references, race conditions, and incorrect logic.",
                    prompt="""You are a debugging expert. Review code for:
                    - Off-by-one errors in loops and array access
                    - Null/undefined reference risks
                    - Race conditions in async code
                    - Missing await on async calls
                    - Incorrect boolean logic
                    - Type mismatches
                    Return findings as JSON with severity WARNING or SUGGESTION.""",
                    tools=["Read", "Glob", "Grep"],
                ),
                "performance-reviewer": AgentDefinition(
                    description="Performance and efficiency specialist. Finds N+1 queries, resource leaks, and algorithmic issues.",
                    prompt="""You are a performance expert. Review code for:
                    - N+1 query patterns
                    - Resource leaks (unclosed connections, file handles)
                    - Unnecessary allocations in loops
                    - Algorithmic complexity issues
                    - Missing caching opportunities
                    Return findings as JSON with severity SUGGESTION.""",
                    tools=["Read", "Glob", "Grep"],
                ),
            },
        ),
    ):
        if isinstance(message, AssistantMessage):
            for block in message.content:
                if hasattr(block, "text"):
                    collected_text.append(block.text)

    full_text = "\n".join(collected_text)
    return extract_findings(full_text)


async def main():
    print("🔍 Running multi-agent code review...\n")

    findings = await multi_review(".")

    if not findings:
        print("✅ No issues found!")
        return

    print(f"Found {len(findings)} issue(s):\n")
    for finding in findings:
        print(format_finding(finding))
        print()


asyncio.run(main())

The orchestrator agent delegates work to three specialists, each with a focused prompt and tool set. The security reviewer looks for OWASP vulnerabilities. The logic reviewer catches bugs. The performance reviewer finds efficiency issues. The orchestrator combines their findings into a single report.

This is the same pattern used in enterprise code review platforms — and it is the direction that the AI code review industry is heading. With the Agent SDK, you can build it in under 50 lines of configuration.

Individual agent detection rates vs. combined multi-agent coverage. The multi-agent approach catches issues that any single agent might miss.

Step 7: GitHub Integration

The final step is posting review findings directly on GitHub pull requests. This turns your agent from a local tool into a CI/CD-integrated reviewer — the same workflow that CodeSentri uses in production.

Create github_poster.py:

import os
import json
import subprocess


def post_review_comments(findings: list[dict], repo: str, pr_number: int):
    """Post review findings as GitHub PR comments using the gh CLI."""
    if not findings:
        # Approve if no issues found
        subprocess.run([
            "gh", "pr", "review", str(pr_number),
            "--repo", repo,
            "--approve",
            "--body", "✅ AI Code Review: No issues found. Code looks good!",
        ])
        return

    # Build review body
    severity_icons = {"CRITICAL": "🔴", "WARNING": "🟡", "SUGGESTION": "🔵"}
    critical_count = sum(1 for f in findings if f.get("severity") == "CRITICAL")
    warning_count = sum(1 for f in findings if f.get("severity") == "WARNING")
    suggestion_count = sum(1 for f in findings if f.get("severity") == "SUGGESTION")

    body_lines = [
        "## AI Code Review Results\n",
        f"Found **{len(findings)}** issue(s):\n",
        f"- 🔴 Critical: {critical_count}",
        f"- 🟡 Warning: {warning_count}",
        f"- 🔵 Suggestion: {suggestion_count}",
        "\n---\n",
    ]

    for finding in findings:
        icon = severity_icons.get(finding.get("severity", ""), "⚪")
        body_lines.append(
            f"### {icon} {finding.get('severity', 'UNKNOWN')}: {finding.get('title', 'Untitled')}\n"
        )
        body_lines.append(
            f"**{finding.get('file', 'unknown')}:{finding.get('line', '?')}**\n"
        )
        body_lines.append(f"{finding.get('message', '')}\n")
        if finding.get("suggestion"):
            body_lines.append(f"```suggestion\n{finding['suggestion']}\n```\n")

    body = "\n".join(body_lines)

    # Post as a PR comment
    event = "--request-changes" if critical_count > 0 else "--comment"
    subprocess.run([
        "gh", "pr", "review", str(pr_number),
        "--repo", repo,
        event,
        "--body", body,
    ])

    print(f"Posted review with {len(findings)} findings to PR #{pr_number}")

To use this in a GitHub Actions workflow, create .github/workflows/ai-review.yml:

name: AI Code Review

on:
  pull_request:
    types: [opened, synchronize]

jobs:
  review:
    runs-on: ubuntu-latest
    permissions:
      pull-requests: write
      contents: read

    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: actions/setup-python@v5
        with:
          python-version: '3.12'

      - name: Install dependencies
        run: pip install claude-agent-sdk

      - name: Run AI review
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: python reviewer.py --pr ${{ github.event.pull_request.number }}

Putting It All Together

Here is the complete project structure:

code-review-agent/
├── .env                 # ANTHROPIC_API_KEY
├── reviewer.py          # Main agent entry point
├── parser.py            # JSON extraction and formatting
├── diff_tool.py         # Custom MCP tool for git diffs
├── multi_reviewer.py    # Multi-agent orchestrated review
├── github_poster.py     # GitHub PR comment integration
├── sample_app.py        # Test file with intentional bugs
└── .github/
    └── workflows/
        └── ai-review.yml  # GitHub Actions workflow

You now have a complete AI code review agent that can:

1. Review entire codebases or just staged changes
2. Classify findings by severity with structured JSON output
3. Use specialized subagents for security, logic, and performance
4. Post results directly on GitHub pull requests
5. Block PRs with critical vulnerabilities via CI/CD exit codes

Lines of code vs. features at each step. The Agent SDK keeps the code minimal while the feature set grows substantially.

From Tutorial to Production: The CodeSentri Path

This tutorial builds the same core architecture that powers CodeSentri. The differences between this tutorial agent and production CodeSentri are:

1. Webhook-driven vs. CLI — CodeSentri runs as a GitHub App that receives webhook events automatically. This tutorial uses CLI invocation via GitHub Actions.
2. Billing and rate limiting — CodeSentri includes PostgreSQL-backed usage tracking and Stripe subscription management.
3. Inline PR comments — CodeSentri posts comments on specific diff lines using the GitHub Reviews API. This tutorial posts a single review comment.
4. Model tiering — CodeSentri uses Claude Haiku for free-tier reviews and Claude Sonnet for paid-tier deeper analysis.

If you want to go from this tutorial to a production tool, the CodeSentri source code shows exactly how each of these production concerns is handled. Or just install CodeSentri on your repos and start getting AI reviews immediately — as we explain in why CodeSentri is the AI reviewer your team needs.

Cost Analysis

One of the most common questions about AI code review is cost. Here is what running this agent costs at Anthropic's current API pricing:

Cost per review vs. analysis depth by Claude model. Haiku is sufficient for catching common vulnerabilities. Sonnet provides the best balance of cost and depth for production use.

For most teams, Claude Haiku 4.5 catches the high-priority issues — SQL injection, missing awaits, off-by-one errors — at $0.03 to $0.05 per review. Claude Sonnet 4.6 adds deeper reasoning about race conditions, architectural concerns, and subtle logic errors at $0.10 to $0.20 per review. A team running 500 diff-only reviews per month spends $15 to $100 total.

Compare that to the cost of a single SQL injection reaching production — breach notification, incident response, regulatory fines — and the ROI is obvious.

What You Learned

In this tutorial, you built:

1. A basic code review agent with built-in Read/Glob/Grep tools
2. A production-grade system prompt with severity classification
3. A structured output parser for CI/CD integration
4. A custom MCP tool for diff-only reviews
5. A multi-agent architecture with specialized subagents
6. GitHub integration for automated PR reviews

The Claude Agent SDK eliminates the boilerplate that makes building AI tools tedious — tool execution loops, context management, retry logic — and lets you focus on what matters: the review prompt, the output format, and the integration points.

Whether you use this as a learning exercise, customize it for your team's specific needs, or skip straight to installing CodeSentri for a production-ready solution, you now understand exactly how AI code review agents work under the hood.

The code from this tutorial is available in a companion repository. Clone it, modify the prompts, add your own MCP tools, and build the code review agent your team needs.

---

For the full CodeSentri build story, read I Built an AI Code Reviewer in a Day. For a comparison of all AI code review tools in 2026, see Why CodeSentri Is the AI Code Reviewer Your Team Actually Needs. For the foundational Claude Agent SDK tutorial, see Building Your First AI Agent with the Claude Agent SDK.