cpython-review-toolkit

Comprehensive CPython C code exploration and analysis using specialized agents

Quick health dashboard — all agents in summary mode

Find cleanup targets — complexity hotspots, refcount issues, and error handling bugs

Quick include graph mapping — understand CPython C file structure and dependencies

Use this agent to track deprecated C API usage within CPython's own code. Finds usage of deprecated APIs like PyModule_AddObject, PyUnicode_READY, Py_UNICODE, old buffer protocol, and other APIs that have newer replacements. <example> Context: The user wants to find deprecated API usage. user: "What deprecated C APIs are still used in the codebase?" assistant: "I'll use the api-deprecation-tracker to scan for deprecated API usage." <commentary> CPython deprecates its own APIs over time. This agent finds internal usage of deprecated APIs. </commentary> </example>

Use this agent to find overly complex C functions in CPython source and suggest simplifications. Measures line count, nesting depth, cyclomatic complexity, parameter count, goto count, and switch-case count. Uses measure_c_complexity.py for metrics. <example> Context: The user wants to find the most complex functions in CPython. user: "What are the most complex functions in Python/?" assistant: "I'll use the c-complexity-analyzer to find complexity hotspots in Python/." <commentary> Complexity analysis identifies functions that are hardest to maintain and most likely to harbor bugs. </commentary> </example>

Use this agent to find error handling bugs in CPython C source code — missing NULL checks, return NULL without setting an exception, error path cleanup issues, and inconsistent error conventions. Uses scan_error_paths.py for candidate detection. <example> Context: The user wants to check error handling in a CPython module. user: "Check Modules/_io for error handling bugs" assistant: "I'll use the error-path-analyzer to scan for error handling issues in Modules/_io." <commentary> Error handling bugs cause SystemError exceptions and crashes. This agent finds them systematically. </commentary> </example> <example> Context: The user is reviewing a specific C file. user: "Does dictobject.c handle errors correctly?" assistant: "I'll use the error-path-analyzer to check dictobject.c for error handling issues." <commentary> Single-file error path analysis is useful for reviewing changes. </commentary> </example>

Use this agent to find GIL (Global Interpreter Lock) usage errors in CPython C source code — mismatched BEGIN/END_ALLOW_THREADS, Python API calls without the GIL, blocking I/O with the GIL held, and PyGILState balance issues. Uses scan_gil_usage.py for detection. <example> Context: The user wants to check GIL safety in a CPython module. user: "Check Modules/_ssl for GIL discipline" assistant: "I'll use the gil-discipline-checker to scan for GIL usage issues in Modules/_ssl." <commentary> I/O-heavy modules like _ssl commonly need careful GIL management. </commentary> </example>

Use this agent for temporal analysis of the CPython C codebase — finding similar bugs via git history, prioritizing review by churn patterns, and detecting incomplete migrations (Argument Clinic, API modernization). Its most valuable capability is similar bug detection — when a bug is fixed, it searches the entire codebase for unfixed instances of the same pattern. <example> Context: A user just fixed a NULL check bug and wants to know if similar bugs exist. user: "We just fixed a missing NULL check in _elementtree.c — did we miss any similar bugs elsewhere?" assistant: "I'll use the git-history-analyzer to find structurally similar code that might have the same vulnerability." <commentary> Similar bug detection (fix propagation) searches the codebase for analogous patterns. </commentary> </example> <example> Context: The user wants to understand recent change patterns before diving in. user: "Before I start working on this module, what's been happening recently?" assistant: "I'll use the git-history-analyzer to analyze recent commits, churn patterns, and change velocity." <commentary> The agent provides a quick temporal overview of the project's recent activity. </commentary> </example> <example> Context: The user wants to check if an API migration is complete. user: "Has the PyModule_AddObject to PyModule_AddObjectRef migration been completed?" assistant: "I'll use the git-history-analyzer to find migration commits and check for remaining unconverted call sites." <commentary> CPython-specific: tracking API modernization progress across the codebase. </commentary> </example>

Use this agent to map the

Use this agent to review C macro definitions for common pitfalls — missing parentheses, multiple evaluation, statement macros without do-while, naming conventions, header guards, and macro scope issues. <example> Context: The user wants to audit macro safety. user: "Check macros in Include/ for hygiene issues" assistant: "I'll use the macro-hygiene-reviewer to review macro definitions in Include/." <commentary> Unhygienic macros cause subtle bugs. This agent catches common pitfalls. </commentary> </example>

Use this agent to find memory management bugs beyond reference counting — mismatched alloc/free, buffer overflows, use-after-free, double-free, and integer overflow in allocations. Analyzes raw memory allocation patterns in CPython C code. <example> Context: The user wants to audit memory safety. user: "Check for memory management bugs in Modules/" assistant: "I'll use the memory-pattern-analyzer to scan for memory management issues in Modules/." <commentary> Memory bugs beyond refcounting include mismatched allocators, buffer overflows, and integer overflow in sizes. </commentary> </example>

Use this agent to find NULL pointer dereference risks in CPython C source code — unchecked allocations, dereference before NULL check, and PyArg_Parse issues. Uses scan_null_checks.py. <example> Context: The user wants to audit NULL safety. user: "Scan Modules/ for NULL pointer dereference risks" assistant: "I'll use the null-safety-scanner to check for NULL safety issues in Modules/." <commentary> NULL dereferences cause segfaults. This agent finds them before they crash. </commentary> </example>

Use this agent to check adherence to PEP 7 (C style guide for CPython). Checks indentation, line length, brace style, keyword spacing, operator spacing, trailing whitespace, missing braces, and header guards. Uses check_pep7.py. <example> Context: The user wants to check style compliance. user: "Check if Objects/ follows PEP 7" assistant: "I'll use the pep7-style-checker to scan for PEP 7 style violations in Objects/." <commentary> PEP 7 compliance is important for CPython contributions and code consistency. </commentary> </example>

Use this agent to find reference counting errors in CPython C source code — the