The `codereview` Tool

Relevant source files

The following files were used as context for generating this wiki page:

• tools/codereview.py
• systemprompts/codereview_prompt.py
• simulator_tests/test_codereview_validation.py
• README.md
• systemprompts/clink/default_codereviewer.txt
• systemprompts/analyze_prompt.py

The codereview tool provides a structured, multi-step workflow for conducting comprehensive code analysis. It guides an AI agent through a systematic investigation of a codebase, ensuring thorough examination of code quality, security, performance, and architecture. The workflow is designed to enforce methodical analysis with forced pauses between steps, culminating in an optional validation by an external "expert" model.

This tool is a core component of the Zen MCP server's code analysis capabilities, often working in conjunction with other tools like planner and precommit. It can be invoked directly or through sub-agents via the clink tool, allowing for specialized and isolated reviews.

Sources: tools/codereview.py:5-16, README.md:154-156, systemprompts/clink/default_codereviewer.txt

Architecture and Core Components

The codereview tool is implemented as the CodeReviewTool class, which inherits from the base WorkflowTool. This inheritance provides the fundamental multi-step workflow management, while CodeReviewTool customizes the behavior for code analysis tasks.

Sources: tools/codereview.py:120-129

Class Structure

The diagram below shows the relationship between the main classes involved in the codereview workflow.

This diagram illustrates that CodeReviewTool extends WorkflowTool and utilizes the CodeReviewRequest data model to manage state during the review process.

Sources: tools/codereview.py:65-117, 120-129

System Prompt

The behavior of the AI agent when using the codereview tool is governed by the CODEREVIEW_PROMPT. This prompt instructs the agent to act as an expert code reviewer, combining the knowledge of a principal engineer with a static analysis tool.

Key instructions from the prompt include:

• User-Centric Analysis: Align the review with the user's goals.
• Scoped & Actionable Feedback: Focus strictly on the provided code and offer concrete fixes.
• Pragmatic Solutions: Avoid suggesting over-engineered solutions.
• Severity-Based Reporting: Classify issues as Critical, High, Medium, or Low.
• Holistic Evaluation: Assess architecture, maintainability, performance, and security.
• Structured Output: Provide findings in a specific format: [SEVERITY] File:Line – Issue description → Fix: Specific solution.

Sources: systemprompts/codereview_prompt.py:5-103

The Code Review Workflow

The tool operates as a stateful, multi-step workflow. The agent is guided through distinct phases of investigation, preventing rushed analysis and ensuring all aspects of the code are considered.

This flowchart shows the logical progression of the codereview tool's workflow.

1. Initiation: The user invokes the codereview tool, providing files/directories to review.
2. Step 1 (Investigation): The agent receives instructions to perform an initial analysis of the code, examining structure, patterns, and obvious issues.
3. Subsequent Steps: The agent calls the tool again for each subsequent step, reporting its findings. The tool provides further instructions for deeper analysis (e.g., security, performance).
4. Completion: When next_step_required is False, the investigation phase ends.
5. Expert Validation: If review_validation_type is external (the default), the tool consolidates all findings, relevant code, and context, then calls a high-capability "expert" model for a final validation pass.
6. Final Report: The workflow concludes, and the agent presents a final, comprehensive report to the user, incorporating its own findings and the expert analysis.

Sources: tools/codereview.py:206-229, 275-289, 321-330

Request Data Model: CodeReviewRequest

Each call to the codereview tool uses the CodeReviewRequest Pydantic model to pass state and findings. The table below details the key fields.

Field	Type	Description
step	str	A narrative of the review strategy and findings for the current step.
step_number	int	The current step number in the review process, starting at 1.
total_steps	int	The total number of planned review steps.
next_step_required	bool	True if another review step is planned. False triggers the finalization phase.
findings	str	A summary of both positive and negative findings for the current step.
files_checked	list[str]	Absolute paths of all files that have been reviewed.
relevant_files	list[str]	In Step 1, all files to be reviewed. In the final step, only files with key findings.
issues_found	list[dict]	A list of dictionaries, each detailing an issue with its severity.
review_validation_type	Literal	external (default) for expert model follow-up, or internal for a local-only review.
review_type	Literal	The focus of the review: full, security, performance, or quick.
severity_filter	Literal	The lowest severity level to report: critical, high, medium, low, or all.

Sources: tools/codereview.py:20-63, 65-117

A validator ensures that the relevant_files field is provided in the first step to initiate the review.

# tools/codereview.py:113-117
    @model_validator(mode="after")
    def validate_step_one_requirements(self):
        """Ensure step 1 has required relevant_files field."""
        if self.step_number == 1 and not self.relevant_files:
            raise ValueError("Step 1 requires 'relevant_files' field to specify code files or directories to review")
        return self

Sources: tools/codereview.py:113-117

Review Types and Validation

The tool supports different modes of operation to tailor the review to specific needs.

Review Types

The review_type parameter allows the user to focus the agent's analysis on particular aspects of the code:

• full: A comprehensive review covering all aspects.
• security: Focuses on vulnerabilities, auth flaws, and other security risks.
• performance: Focuses on bottlenecks, algorithmic complexity, and resource usage.
• quick: A high-level overview to spot obvious issues.

Sources: tools/codereview.py:102-105

Validation Types

The review_validation_type parameter controls whether an external expert model is consulted:

• external (default): After the agent completes its investigation, its findings are sent to a high-capability model for validation and a second opinion. This is the standard, recommended flow for ensuring high-quality reviews.
• internal: The workflow completes after the agent's investigation without consulting an external model. This is faster but relies solely on the primary agent's analysis.

The decision to call an expert model is made in the should_call_expert_analysis method, and expert analysis is skipped if review_validation_type is set to internal.

Sources: tools/codereview.py:90-93, 275-289, 321-330

Conclusion

The codereview tool is a powerful and systematic feature for ensuring code quality within the Zen MCP Server ecosystem. By enforcing a structured, multi-step workflow, it encourages deep and methodical analysis over superficial checks. Its integration with expert models for validation provides a robust mechanism for catching a wide range of issues, from simple bugs to complex architectural flaws. The tool's flexibility, with configurable review types and validation modes, makes it adaptable to various development scenarios, from quick checks to in-depth security audits.