Plankton provides write-time code quality enforcement specifically for AI coding agents like Claude Code. It aims to improve code quality by integrating automated formatting, linting, and AI-driven fixes directly into the agent's workflow, ensuring code adheres to style, correctness, and architectural standards before it's committed. This system benefits users by catching issues early, leading to higher pass rates and fostering better coding habits within the AI model itself.

How It Works

Plankton operates through a three-phase process triggered on every file edit. Initially, it auto-formats code using tools like ruff, shfmt, and biome. Subsequently, it collects remaining violations from over 20 linters, outputting them as structured JSON. Finally, dedicated Claude subprocesses are delegated to intelligently fix these remaining issues. This approach is advantageous as it ensures comprehensive quality checks and leverages AI for complex fixes while optimizing token usage through model routing based on problem complexity. Configuration files are protected via a PreToolUse hook to prevent tampering.

Quick Start & Requirements

The recommended installation involves cloning the repository (git clone https://github.com/alexfazio/plankton.git) and running the interactive setup wizard (python3 scripts/setup.py). A non-interactive installer (bash scripts/setup.sh) is available for macOS and Linux. Windows is not supported natively and requires WSL2. Prerequisites include Claude Code version >= 2.1.50 (users are strongly advised to disable Claude Code auto-updates to prevent breakage). Dependencies like ruff, uv, shellcheck, shfmt, hadolint, taplo, and bun are automatically installed by the setup script or can be installed manually following instructions in docs/SETUP.md.

Highlighted Details

• Enforces a wide range of checks: style (formatting, imports, docstrings), correctness (unused variables, type errors, security vulnerabilities, dead code), and architectural constraints (complexity limits, package manager compliance, config file protection).
• Tamper-proof configuration (.claude/hooks/config.json) prevents accidental or malicious changes to linter rules.
• Model routing dynamically assigns AI resources based on fix complexity, optimizing performance and cost.
• Provides write-time feedback, enabling the AI model to learn and improve its code generation over time.

Maintenance & Community

Plankton is described as a research project under active development. Contributions are explicitly welcomed. Specific community channels (like Discord or Slack) or details on notable contributors/sponsorships are not mentioned in the provided README.

Licensing & Compatibility

The project is licensed under the MIT license, which is generally permissive for commercial use and integration into closed-source projects. However, practical compatibility may be affected by its reliance on specific, potentially undocumented, internals of Claude Code and the recommendation to disable its auto-updates.

Limitations & Caveats

As an actively developed research project, Plankton may be subject to changes and potential instability. Its functionality is tightly coupled to specific Claude Code versions (>= 2.1.50), and updates to Claude Code can silently break the hooks, necessitating manual intervention or disabling auto-updates. Native Windows support is absent, requiring the use of WSL2. The current model routing primarily targets Anthropic models, with broader support being a future development goal.