Plankton: Write-time Code Quality Enforcement for Claude Code Hooks

Plankton: Write-time Code Quality Enforcement for AI Coding Agents

A living research project that sits at the boundary between code linting, secure development practices, and AI-assisted programming. Built on Claude Code hooks, Plankton enforces style, safety, and structural quality as code is written, so teams ship more reliable software with fewer surprises during review and testing. Note: this is an active development effort. Hooks are tested against Claude Code version 2.1.50 and newer CC versions may work but aren’t guaranteed. To avoid silent breakage, disable auto-updates and pin to a known version when you start.

Quick primer: Plankton makes the directory you run Claude Code from into a write-time gate. As you edit, the hooks in .claude/hooks/ are engaged automatically—no extra install step beyond the initial clone and setup. If you’re switching codebases, simply tell Claude where you’re working, and Plankton applies the same quality checks to that project while hooks stay active.

Quick Start

• Clone the repository and set up interactively
• git clone https://github.com/alexfazio/plankton.git
• cd plankton
• python3 scripts/setup.py
• Follow the interactive wizard; Claude Code hooks activate automatically
• Then run claude to begin working with the integrated checks
• Non-interactive setup (macOS + Linux)
• bash scripts/setup.sh
• Windows users should note: Windows is not supported directly. Use WSL2 and follow the Linux instructions inside the WSL environment.
• Quick tip: you can work on any codebase from inside Plankton. Tell Claude: "work on /path/to/my-project" and it will apply the same quality enforcement to that codebase while the hooks stay active.
• Existing codebases: when Claude edits a file, Plankton runs the configured checks for that file, including pre-existing issues. Some issues may be auto-fixed on first touch; unresolved ones appear again as feedback.

What is Plankton?

Plankton is a code quality gate that operates at write-time. It blocks progress until the agent’s output passes a suite of checks—style, types, security, and complexity—before commits and code review. The intention is to catch potential problems early, making downstream steps easier and more deterministic.

Key components

• Interactive setup and language detection: The setup wizard auto-detects project languages, checks dependencies, and can install missing required tools such as jaq, ruff, and uv.
• Automatic hook activation: Once started, the hooks in .claude/hooks/ are engaged automatically with no separate install command or plugin required.
• Cross-project applicability: Plankton works the same across codebases, whether you’re working in Python, JavaScript, or other languages supported by Claude Code hooks.

Phases of operation

Three core phases run on every file edit: 1) Auto-format first: The system applies formatting using tools like ruff, shfmt, biome, taplo, and markdownlint to normalize style and structure. 2) Collect violations: Remaining issues are gathered as structured JSON from a broad set of linters, so you have a clear map of what’s left to fix. 3) Claude-based fixes: Claude subprocesses reason about each fix and attempt to resolve what remains, guiding the code toward correctness, security, and readability.

The architectural intent is to protect the core flow: pre-commit safety nets and a predictable feedback loop before changes reach a reviewer.

How it helps you write better code

• Higher pass rate: Write-time feedback helps catch bugs, type errors, and anti-patterns before tests run or reviews begin.
• Behavioral shift: With active Plankton, the model learns from write-time feedback and produces better code during generation, not just through post-hoc formatting.
• Compound quality: Incremental improvements across multiple dimensions accumulate to more reliable code overall.

What it enforces

Plankton enforces a broad spectrum of quality gates, spanning style and correctness, to keep your code robust and maintainable.

Style and formatting

• Consistent formatting across languages
• Import ordering and naming conventions
• Docstring style and comment quality
• Quote style, indentation, and trailing commas
• Use of modern syntax idioms (e.g., Python 3.11+ f-strings, up-to-date typing)

Correctness and security

• Detection of unused variables and type errors
• Dead code detection and static analysis
• Security vulnerabilities scanning (e.g., via Bandit, Semgrep)
• Async anti-patterns (e.g., Flake8-Async)
• Pydantic model validations and data integrity checks
• Duplicate code detection (e.g., jscpd)
• Shell script analysis with ShellCheck (all meaningful checks)
• Dockerfile best practices enforcement (Hadolint with strict rules)
• YAML strictness with comprehensive yamllint rules

Architectural constraints

• Complexity controls (cyclomatic complexity, maximum arguments, nesting depth, statements per function)
• Package manager compliance (enforcing constraints on pip, npm, yarn; ensuring usage of uv, bun)
• Tamper-proof configuration protection (prevents edits to linter configuration in ways that would bypass checks)
• Clear routing rules so Claide Code understands how to spend its effort on more complex problems

Configuring what gets enforced

Configuration is stored in .claude/hooks/config.json. This file governs:

• Languages to enable or disable
• Phase control (which phases run for which languages or files)
• Model routing patterns for various tasks
• Protected files that should not be altered by automated fixes
• Security-linter exclusions
• jscpd thresholds for duplicate code
• Package manager enforcement modes

If config.json is missing, Plankton enables sane defaults so you can start immediately and tune later.

Environment variables can tweak behavior at runtime

• HOOKSKIPSUBPROCESS=1 can bypass some subprocesses
• HOOKSUBPROCESSTIMEOUT sets timeouts for hook subprocesses

Full configuration references are documented in docs/REFERENCE.md.

Setup and Installation

Interactive wizard

• The recommended path is to run the interactive setup wizard:
• python3 scripts/setup.py
• The wizard auto-detects project languages, checks dependencies, and can install missing required tools (jaq, ruff, uv).

Non-interactive setup

• If you prefer automation or CI contexts, you can run:
• bash scripts/setup.sh
• Documentation provides per-language setup details at docs/SETUP.md.

Manual install notes (for those who prefer not to use the setup script)

macOS

• Install common tooling first:
• brew install jaq ruff uv
• install Bun and related tooling if you use Bun for JavaScript tooling
• Install Python linting and code quality tools
• uv sync --all-extras --no-install-project
• (additional per-language commands may be needed)

Linux

• Core tooling (via Astral installers) for ruff and uv:
• curl -LsSf https://astral.sh/ruff/install.sh | sh
• curl -LsSf https://astral.sh/uv/install.sh | sh
• Binary tools: jaq, shellcheck, shfmt, hadolint, taplo
• JS runtime and tooling: Bun
• curl -fsSL https://bun.sh/install | bash
• bun install
• Biome and oxlint for Python linting
• uv sync --all-extras --no-install-project

Per-language setup is detailed in docs/SETUP.md, including site-wide recommendations and downloads.

Verification and governance

How to verify that the hooks are functioning

• Install pre-commit hooks (recommended). This ensures the strict runtime-parity gate runs automatically on git commit and enables the commit-message policy hook.
• uv run pre-commit install --hook-type pre-commit --hook-type commit-msg
• Install pre-push hook to ensure checks run before pushes:
• uv run pre-commit install --hook-type pre-push -f
• Do a repo-wide baseline sweep (skip staged-file runtime hook for speed; designed for full-file checks):
• SKIP=plankton-strict-runtime-commit uv run pre-commit run --all-files
• Run the Plankton hook test suite directly for self-checks:
• ./scripts/prepushplankton_hooks.sh
• Re-run the same strict gate on currently staged files:
• make strict
• For intentional protected config edits, use the override:
• make strict-protected FILES=".semgrep.yml"
• Or commit with protection enabled:
• PLANKTONSTRICTALLOW_PROTECTED=1 git commit
• Self-test the hook:
• .claude/hooks/test_hook.sh --self-test

How it works under the hood

The architecture centers on safe, deterministic feedback for every file edit:

• Phase 1: Auto-format pass
• Applies formatting and normalization across languages
• Phase 2: Violation collection
• Aggregates remaining issues into a structured JSON from 20+ linters
• Phase 3: Claude-based reasoning
• Delegates the remaining concerns to Claude subprocesses to propose or apply fixes
• Tamper-proofing
• Config files are protected by PreToolUse hooks to prevent mid-edit configuration edits
• Model routing and problem sizing
• Routing logic ensures Claude’s attention is focused on harder problems while simpler issues are handled by formatters

Full architecture details, message flows, and configuration references live in docs/REFERENCE.md. The original motivation and design story are captured in the original writeup linked in the project (https://x.com/alxfazio/status/2024931367612743688).

What it enforces in practice

• Style enforcement: formatting consistency, import order, naming conventions, docstrings, quotes, indentation, trailing commas, and modern syntax usage.
• Correctness: detection of unused variables, type errors, dead code, and basic correctness signals.
• Security and quality: vulnerability scanning etc., including specific tools for various languages and ecosystems.
• Architectural discipline: complexity metrics, packaging policies, and tamper-proof protections that project code should respect.
• Housekeeping: you primarily interact with the auto-formatting and lint results through the feedback loop, with automated fixes attempted where safe.

FAQ and further reading

• The project maintains an FAQ at docs/FAQ.md with guidance on how this differs from traditional pre-commit hooks, whether AI models will eventually obviate the need for such tools, and why agents may adjust linting rules themselves.
• For in-depth references, see docs/REFERENCE.md for architecture and message flows, and docs/SETUP.md for installation and per-language specifics.
• Original writeup and motivation: the linked status update (https://x.com/alxfazio/status/2024931367612743688) explains the broader design intent behind write-time code quality enforcement and how Plankton fits in.

Todos and ongoing work

• Improve the install wizard: move toward a one-click installer that detects your stack and configures everything automatically.
• Marketplace integration: a Claude Code marketplace option for one-click install.
• In-session configuration and troubleshooting: a Claude Code skill to adjust rules and resolve issues without leaving a session.
• Language expansion: Swift and Go are next on the roadmap.
• Model routing flexibility: currently aligned with Anthropic models; extend support to other Claude Code-compatible providers (Qwen, DeepSeek, Gemini, etc.) with a generic three-tier routing system.
• Per-directory rule overrides and team-specific config profiles to enable enterprise-grade collaboration.
• Extend beyond code to detect AI-writing slop in docs and READMEs, integrating slop-guard-style protections.
• Codebase modularization: split the large multi-linter script into per-hook-type files for better maintenance.
• Test suite improvements: increase determinism in integration tests and address stochasticity in Claude subprocesses.
• Benchmarking: develop measures to compare LLM+Plankton versus LLM-alone performance; contributions welcome.

Community, collaboration, and licensing

Plankton invites contributions. The project license is MIT, reflecting an open and collaborative approach to improving AI-assisted development tooling.

Star history

If you’re curious about project momentum, you can view star history to see community engagement over time:

• Star History Chart

License

MIT

Closing thoughts

Plankton represents a convergence of automated tooling, AI-assisted code quality, and developer workflow optimization. By acting as a write-time gate, it shifts quality assurance earlier in the development lifecycle, reducing the friction of downstream fixes and enabling teams to ship safer, cleaner, and more reliable software. While it is a developing project with ongoing improvements, its design goals are clear: detect and fix issues as code is written, guide models toward better practices, and offer a tunable, transparent, and auditable framework for enforceable code standards.

If you’re exploring AI-enabled development environments, Plankton offers a compelling blueprint for how write-time checks can be integrated into Claude Code workflows, providing immediate feedback, early safeguards, and a path toward more maintainable codebases without sacrificing velocity.