rust-ext-review-toolkit

rust-ext-review-toolkit

A Claude Code plugin for reviewing Python extensions written in Rust with PyO3 — finding soundness bugs in unsafe code, PyO3 API misuse, GIL/lifetime discipline issues, #[pyclass] trait-bound violations, panic-safety problems, and PyO3 version-migration debt.

Find the soundness bugs in your Rust extension before your users do.

What PyO3 prevents — and what it doesn't

PyO3's type system already eliminates most classic C-extension bug classes, so this toolkit does not scan for them:

• Manual Py_INCREF/Py_DECREF — Py<T> and Bound<'py, T> implement Drop
• Most NULL-pointer dereferences — fallible APIs return PyResult<T> / Option<T>
• Most use-after-free of Python objects — the 'py lifetime ties handles to the interpreter
• Memory safety in safe Rust — the borrow checker

What PyO3 does not prevent — and what this toolkit is for:

• Soundness bugs inside unsafe (raw pyo3-ffi, transmute, manual buffer protocol, C-library FFI)
• #[pyclass] trait-bound violations — non-Send/Sync fields without unsendable
• Panics crossing the extern "C" FFI boundary
• PyResult propagation gaps — .unwrap(), .ok(), let _ =, missing ?, exception clobbering
• Wrong handle kind — Bound vs Py vs Borrowed; legacy &PyAny
• #[pymethods] protocol mistakes — missing __traverse__/__clear__, __richcmp__ semantics
• PyO3 version-migration debt and abi3 consistency
• Free-threaded Python (3.13t/3.14t) readiness

Installation

Marketplace install

claude plugin marketplace add devdanzin/rust-ext-review-toolkit
claude plugin install rust-ext-review-toolkit@rust-ext-review-toolkit

Try it without installing

git clone https://github.com/devdanzin/rust-ext-review-toolkit.git
claude --plugin-dir rust-ext-review-toolkit/plugins/rust-ext-review-toolkit

Prerequisites

• Claude Code installed and running
• Python 3.10+ for the analysis scripts
• tree-sitter and tree-sitter-rust: pip install tree-sitter tree-sitter-rust
• Optional: a Rust toolchain with cargo clippy / cargo miri / cargo expand for deeper cross-referencing

Quick start

In a PyO3 crate:

/rust-ext-review-toolkit:health      # Quick scored dashboard
/rust-ext-review-toolkit:hotspots    # Worst functions: unsafe + panic + complexity
/rust-ext-review-toolkit:explore     # Full analysis (all agents, phased)
/rust-ext-review-toolkit:migrate     # Bound-API / free-threading / abi3 checklist

Agents

13 agents — 11 script-backed, 1 qualitative, 1 preflight.

Preflight

• rust-codegen-mapper — orientation guide: PyO3 version + features, file classification, project-specific idioms; runs first so downstream agents triage accurately.

Safety-critical

• unsafe-block-auditor — soundness of every unsafe block; raw pyo3-ffi calls; transmute; manual buffer protocol (the #1 agent)
• pyresult-propagation-checker — .unwrap()/.ok() on PyResult, missing ?, exception clobbering
• gil-discipline-checker — handles held across detach; nested attach; foreign-callback GIL acquisition; free-threading declarations
• panic-safety-checker — panic-prone calls reachable from #[pymethods] / #[pyfunction]

PyO3-specific

• pyclass-traits-checker — #[pyclass] Send/Sync/frozen/unsendable
• pyclass-protocol-checker — #[pymethods] slot signatures, __traverse__/__clear__, __richcmp__
• module-init-checker — #[pymodule] shape, module-level static state
• lifetime-handle-checker — Bound vs Py vs Borrowed; legacy &PyAny

Compatibility, quality, parity

• pyo3-version-compat-scanner — deprecated/removed APIs by version; abi3 consistency
• rust-complexity-analyzer — complexity scoring (includes unsafe-block density)
• git-history-analyzer — similar-bug detection, churn-based risk prioritization
• parity-checker — behavioral divergence between a Rust extension and its pure-Python fallback

Commands

Command	Purpose
explore	Full analysis, phased agent groups, selectable aspects
health	Quick scored dashboard, all agents in summary mode
hotspots	Worst functions first — unsafe + pyresult + panic + complexity
migrate	Bound-API migration, free-threading readiness, abi3 — checklist output

How it works

Tree-sitter-rust parsing. Scripts parse .rs source with tree-sitter-rust — style-agnostic and robust against macro-heavy code. Tree-sitter does not expand procedural macros, so #[pyclass]/#[pymethods] analysis is syntactic inference over the attribute + struct + method shape.