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>