code-review-toolkit

Comprehensive codebase exploration and analysis using specialized agents

Quick health dashboard — all agents in summary mode

Find cleanup targets — complexity hotspots, dead code, and tech debt

Quick architecture mapping — understand project structure and dependencies

Use this agent to review the public API surface of a Python project — naming consistency, parameter conventions, return type patterns, and whether the API is predictable and learnable from a user's perspective. Especially valuable for tools and libraries that have both a CLI interface and a programmatic API. This agent evaluates whether a user who learns one part of the API can predict how other parts work. <example> Context: The user is preparing a release and wants the API to be polished. user: "Before the release, can you review our public API for consistency?" assistant: "I'll use the api-surface-reviewer to evaluate naming, parameter conventions, and API predictability." </example> <example> Context: The user wants to understand how intuitive the API is. user: "If someone new picks up this library, will the API make sense?" assistant: "I'll use the api-surface-reviewer to assess learnability and consistency from a newcomer's perspective." </example>

Use this agent to map the structure, dependencies, and module boundaries of a Python codebase. This is the foundational analysis agent — its output feeds into other agents as context for richer analysis. Use it when exploring an unfamiliar codebase, before running other code-review-toolkit agents, or when you need to understand how modules relate to each other. The agent builds a dependency graph from Python imports, identifies module boundaries and layering, detects circular dependencies, and produces a structural summary. The agent needs to know the scope of the analysis. By default it analyzes the entire project. You can narrow scope to a directory, file, or glob pattern. <example> Context: The user wants to understand the structure of a Python project before making changes. user: "I need to understand how this codebase is organized before I start refactoring" assistant: "I'll use the architecture-mapper agent to map the module structure and dependencies." <commentary> Use architecture-mapper as the first step in codebase exploration. Its output gives a mental model of the project. </commentary> </example> <example> Context: The user wants to run a comprehensive codebase review. user: "Run a full code review on this project" assistant: "I'll start by running the architecture-mapper to understand the project structure, then feed that into the other review agents." <commentary> When running multiple agents, architecture-mapper should run first so its output can enrich other agents' analysis. </commentary> </example> <example> Context: The user suspects there are circular dependencies causing import issues. user: "I keep hitting circular import errors — can you map out the dependency structure?" assistant: "I'll use the architecture-mapper agent to build a dependency graph and identify circular dependencies." <commentary> Architecture-mapper directly addresses structural questions about how modules depend on each other. </commentary> </example>

Use this agent to find the most complex code in a Python codebase and suggest simplifications. This agent combines hotspot detection (finding where complexity concentrates) with simplification analysis (how to reduce it). It measures multiple dimensions of complexity — nesting depth, function length, parameter count, cognitive load — and produces a ranked list of hotspots with concrete simplification strategies. Use after architecture-mapper for module-aware analysis. The agent needs scope and optionally architecture-mapper output as context. <example> Context: The user wants to find and simplify the most complex parts of their codebase. user: "Where are the most complex parts of this codebase? I want to simplify them." assistant: "I'll use the complexity-simplifier to identify complexity hotspots and suggest simplifications." <commentary> This is the core use case: find what's complex, explain why, and suggest how to simplify. </commentary> </example> <example> Context: The user is planning a refactoring sprint and wants to prioritize. user: "I have a week for refactoring — where should I focus?" assistant: "I'll run the complexity-simplifier to rank the codebase by complexity so you can prioritize your refactoring effort." <commentary> The ranked hotspot output directly answers prioritization questions. </commentary> </example> <example> Context: A specific module feels hard to work with. user: "The runner module is really hard to modify — can you analyze why?" assistant: "I'll use the complexity-simplifier focused on the runner module to identify what's making it complex and how to simplify it." <commentary> Narrowing scope to a specific module for targeted analysis. </commentary> </example>

Use this agent to scan a Python codebase for inconsistencies in coding patterns, style, and conventions. Unlike a PR code-reviewer that checks changes against rules, this agent compares how different parts of the codebase handle the same concerns and identifies divergence. It works both inductively (discovering implicit conventions from the majority pattern) and deductively (checking against CLAUDE.md rules). Best used after architecture-mapper has run, so it can analyze consistency within and across module boundaries. The agent needs scope and optionally architecture-mapper output as context. <example> Context: The user wants to find inconsistencies across a codebase. user: "This codebase has grown organically — can you find where our patterns diverge?" assistant: "I'll use the consistency-auditor to scan for pattern divergence across your codebase." <commentary> The consistency-auditor is designed for exactly this: finding where organic growth has led to inconsistent patterns. </commentary> </example> <example> Context: Architecture-mapper has already run and the user wants deeper analysis. user: "Now that we have the architecture map, let's look at code consistency" assistant: "I'll feed the architecture-mapper output into the consistency-auditor for module-aware consistency analysis." <commentary> Using architecture-mapper output lets the consistency-auditor distinguish intentional variation between modules from unintentional divergence. </commentary> </example> <example> Context: The user has established coding standards and wants to verify the codebase follows them. user: "Check if the codebase actually follows what CLAUDE.md says" assistant: "I'll use the consistency-auditor to compare the codebase against the documented standards in CLAUDE.md." <commentary> The auditor does both inductive (pattern discovery) and deductive (rule checking) analysis. </commentary> </example>

Use this agent to find unused code in a Python codebase — unused imports, unreferenced functions, orphan files, unreachable branches, and stale feature flags. Dead code creates noise, increases maintenance burden, and can confuse developers into thinking unused code paths are important. This agent uses static analysis (import/reference scanning) to identify candidates, with careful attention to Python's dynamic dispatch patterns that can cause false positives. <example> Context: The user wants to clean up the codebase. user: "I think there's a lot of dead code in this project — can you find it?" assistant: "I'll use the dead-code-finder to scan for unused imports, unreferenced functions, and orphan files." </example> <example> Context: Before a major refactoring effort. user: "Before we refactor, let's remove anything that's not actually used" assistant: "I'll run the dead-code-finder to identify safe removal candidates." </example>