Plankton Code Quality & Auto-Fix

Улучшите Claude Code с помощью Plankton. Автоматизируйте линтинг, форматирование и исправления на базе ИИ, защищая ваши конфигурации от несанкционированных изменений агентами.

Инструменты разработчика ★ 130,863 GitHub (130,863 ★)

Plankton — это комплексная система обеспечения качества на этапе написания кода, предназначенная для поддержания производственных стандартов в среде Claude Code. Система работает по трёхфазной архитектуре, которая автоматически форматирует код, выявляет ошибки линтинга и интеллектуально направляет неисправляемые ошибки в специализированные подпроцессы Claude (Haiku, Sonnet или Opus) для автоматического исправления. Благодаря строгой защите конфигурации предотвращается «игнорирование» системы ИИ-агентами путём отключения правил, а также обеспечивается использование современных менеджеров пакетов, таких как uv и bun, для согласованности кодовой базы на Python, TypeScript, Shell и других языках.

Ключевые функции

01Автоматическое многофазное форматирование и линтинг при каждом изменении файла

02Блокировка устаревших менеджеров пакетов для принудительного использования современных инструментов, таких как uv и bun

03130,863 звёзд на GitHub

04Многоуровневая маршрутизация ИИ-моделей для автоматического исправления ошибок в зависимости от сложности нарушения

05Защита от изменения конфигурации для предотвращения модификации или отключения правил линтинга агентами

06Встроенная поддержка Python, TypeScript, Shell, YAML, Dockerfile и Markdown

Варианты использования

01Автоматизация сложных задач проверки типов и рефакторинга в цикле разработки

02Поддержание архитектурной и стилистической согласованности в мультиязычных репозиториях без ручных проверок

03Предотвращение накопления технического долга или обхода правил безопасности ИИ-агентами

name	plankton-code-quality
description	Write-time code quality enforcement using Plankton — auto-formatting, linting, and Claude-powered fixes on every file edit via hooks.
origin	community

Plankton Code Quality Skill

Integration reference for Plankton (credit: @alxfazio), a write-time code quality enforcement system for Claude Code. Plankton runs formatters and linters on every file edit via PostToolUse hooks, then spawns Claude subprocesses to fix violations the agent didn't catch.

When to Use

You want automatic formatting and linting on every file edit (not just at commit time)
You need defense against agents modifying linter configs to pass instead of fixing code
You want tiered model routing for fixes (Haiku for simple style, Sonnet for logic, Opus for types)
You work with multiple languages (Python, TypeScript, Shell, YAML, JSON, TOML, Markdown, Dockerfile)

How It Works

Three-Phase Architecture

Every time Claude Code edits or writes a file, Plankton's multi_linter.sh PostToolUse hook runs:

Phase 1: Auto-Format (Silent)
├─ Runs formatters (ruff format, biome, shfmt, taplo, markdownlint)
├─ Fixes 40-50% of issues silently
└─ No output to main agent

Phase 2: Collect Violations (JSON)
├─ Runs linters and collects unfixable violations
├─ Returns structured JSON: {line, column, code, message, linter}
└─ Still no output to main agent

Phase 3: Delegate + Verify
├─ Spawns claude -p subprocess with violations JSON
├─ Routes to model tier based on violation complexity:
│   ├─ Haiku: formatting, imports, style (E/W/F codes) — 120s timeout
│   ├─ Sonnet: complexity, refactoring (C901, PLR codes) — 300s timeout
│   └─ Opus: type system, deep reasoning (unresolved-attribute) — 600s timeout
├─ Re-runs Phase 1+2 to verify fixes
└─ Exit 0 if clean, Exit 2 if violations remain (reported to main agent)

What the Main Agent Sees

Scenario	Agent sees	Hook exit
No violations	Nothing	0
All fixed by subprocess	Nothing	0
Violations remain after subprocess	`[hook] N violation(s) remain`	2
Advisory (duplicates, old tooling)	`[hook:advisory] ...`	0

The main agent only sees issues the subprocess couldn't fix. Most quality problems are resolved transparently.

Config Protection (Defense Against Rule-Gaming)

LLMs will modify .ruff.toml or biome.json to disable rules rather than fix code. Plankton blocks this with three layers:

PreToolUse hook — protect_linter_configs.sh blocks edits to all linter configs before they happen
Stop hook — stop_config_guardian.sh detects config changes via git diff at session end
Protected files list — .ruff.toml, biome.json, .shellcheckrc, .yamllint, .hadolint.yaml, and more

Package Manager Enforcement

A PreToolUse hook on Bash blocks legacy package managers:

pip, pip3, poetry, pipenv → Blocked (use uv)
npm, yarn, pnpm → Blocked (use bun)
Allowed exceptions: npm audit, npm view, npm publish

Setup

Quick Start

Note: Plankton requires manual installation from its repository. Review the code before installing.

# Install core dependencies
brew install jaq ruff uv

# Install Python linters
uv sync --all-extras

# Start Claude Code — hooks activate automatically
claude

No install command, no plugin config. The hooks in .claude/settings.json are picked up automatically when you run Claude Code in the Plankton directory.

Per-Project Integration

To use Plankton hooks in your own project:

Copy .claude/hooks/ directory to your project
Copy .claude/settings.json hook configuration
Copy linter config files (.ruff.toml, biome.json, etc.)
Install the linters for your languages

Language-Specific Dependencies

Language	Required	Optional
Python	`ruff`, `uv`	`ty` (types), `vulture` (dead code), `bandit` (security)
TypeScript/JS	`biome`	`oxlint`, `semgrep`, `knip` (dead exports)
Shell	`shellcheck`, `shfmt`	—
YAML	`yamllint`	—
Markdown	`markdownlint-cli2`	—
Dockerfile	`hadolint` (>= 2.12.0)	—
TOML	`taplo`	—
JSON	`jaq`	—

Pairing with ECC

Complementary, Not Overlapping

Concern	ECC	Plankton
Code quality enforcement	PostToolUse hooks (Prettier, tsc)	PostToolUse hooks (20+ linters + subprocess fixes)
Security scanning	AgentShield, security-reviewer agent	Bandit (Python), Semgrep (TypeScript)
Config protection	—	PreToolUse blocks + Stop hook detection
Package manager	Detection + setup	Enforcement (blocks legacy PMs)
CI integration	—	Pre-commit hooks for git
Model routing	Manual (`/model opus`)	Automatic (violation complexity → tier)

Recommended Combination

Install ECC as your plugin (agents, skills, commands, rules)
Add Plankton hooks for write-time quality enforcement
Use AgentShield for security audits
Use ECC's verification-loop as a final gate before PRs

Avoiding Hook Conflicts

If running both ECC and Plankton hooks:

ECC's Prettier hook and Plankton's biome formatter may conflict on JS/TS files
Resolution: disable ECC's Prettier PostToolUse hook when using Plankton (Plankton's biome is more comprehensive)
Both can coexist on different file types (ECC handles what Plankton doesn't cover)

Configuration Reference

Plankton's .claude/hooks/config.json controls all behavior:

{
  "languages": {
    "python": true,
    "shell": true,
    "yaml": true,
    "json": true,
    "toml": true,
    "dockerfile": true,
    "markdown": true,
    "typescript": {
      "enabled": true,
      "js_runtime": "auto",
      "biome_nursery": "warn",
      "semgrep": true
    }
  },
  "phases": {
    "auto_format": true,
    "subprocess_delegation": true
  },
  "subprocess": {
    "tiers": {
      "haiku":  { "timeout": 120, "max_turns": 10 },
      "sonnet": { "timeout": 300, "max_turns": 10 },
      "opus":   { "timeout": 600, "max_turns": 15 }
    },
    "volume_threshold": 5
  }
}

Key settings:

Disable languages you don't use to speed up hooks
volume_threshold — violations > this count auto-escalate to a higher model tier
subprocess_delegation: false — skip Phase 3 entirely (just report violations)

Environment Overrides

Variable	Purpose
`HOOK_SKIP_SUBPROCESS=1`	Skip Phase 3, report violations directly
`HOOK_SUBPROCESS_TIMEOUT=N`	Override tier timeout
`HOOK_DEBUG_MODEL=1`	Log model selection decisions
`HOOK_SKIP_PM=1`	Bypass package manager enforcement

References

Plankton (credit: @alxfazio)
Plankton REFERENCE.md — Full architecture documentation (credit: @alxfazio)
Plankton SETUP.md — Detailed installation guide (credit: @alxfazio)

ECC v1.8 Additions

Copyable Hook Profile

Set strict quality behavior:

export ECC_HOOK_PROFILE=strict
export ECC_QUALITY_GATE_FIX=true
export ECC_QUALITY_GATE_STRICT=true

Language Gate Table

TypeScript/JavaScript: Biome preferred, Prettier fallback
Python: Ruff format/check
Go: gofmt

Config Tamper Guard

During quality enforcement, flag changes to config files in same iteration:

biome.json, .eslintrc*, prettier.config*, tsconfig.json, pyproject.toml

If config is changed to suppress violations, require explicit review before merge.

CI Integration Pattern

Use the same commands in CI as local hooks:

run formatter checks
run lint/type checks
fail fast on strict mode
publish remediation summary

Health Metrics

Track:

edits flagged by gates
average remediation time
repeat violations by category
merge blocks due to gate failures

🧹 Plankton Code Quality & Auto-Fix

Что это

Plankton (автор @alxfazio) — это система контроля качества кода на моменте записи файла для агентов Claude Code. В отличие от традиционных pre-commit хуков, которые срабатывают при коммите, Plankton запускает форматтеры и линтеры сразу после каждого изменения файла через механизм PostToolUse хуков. Если агент пропустил какую-то ошибку, Plankton автоматически делегирует исправление дочернему процессу Claude с подходящей моделью (Haiku, Sonnet или Opus). Основная задача — сделать так, чтобы код всегда оставался в «опрятном» состоянии, а агент даже не знал о большинстве исправлений.

⚙️ Как работает

Архитектура «три фазы»

Каждый раз, когда Claude Code редактирует или создаёт файл, хук multi_linter.sh выполняет три фазы:

Фаза 1: Автоформатирование (беззвучно)

Запускаются форматтеры: ruff format, biome, shfmt, taplo, markdownlint.
40–50% проблем исправляются тихо — агент не видит процесс.
Выхода в основной поток нет.

Фаза 2: Сбор нарушений (JSON)

Запускаются линтеры, собираются те проблемы, которые не исправить автоматически.
Результат — структурированный JSON: {line, column, code, message, linter}.
Агент по-прежнему ничего не видит.

Фаза 3: Делегация + проверка

Запускается claude -p (подпроцесс) с полученным JSON нарушений.
Выбор модели зависит от сложности проблемы:
- Haiku (таймаут 120 с) — форматирование, импорты, стиль (коды E/W/F).
- Sonnet (таймаут 300 с) — сложность, рефакторинг (C901, PLR).
- Opus (таймаут 600 с) — система типов, глубокие рассуждения (unresolved-attribute).
После попытки исправления фазы 1 и 2 запускаются снова для верификации.
Если всё чисто — код возврата 0, если нарушения остались — 2 (сообщение агенту).

Что видит основной агент

Сценарий	Видит агент	Exit code
Нет нарушений	Ничего	0
Всё исправлено подпроцессом	Ничего	0
Нарушения остались	`[hook] N violation(s) remain`	2
Предупреждения (дубликаты, устаревшие правила)	`[hook:advisory] ...`	0

Таким образом, агент получает информацию только о неисправимых проблемах — качество растёт прозрачно.

🛡️ Защита от подлога правил

LLM часто пытаются отключить правила в конфигах (.ruff.toml, biome.json), чтобы не исправлять код. Plankton блокирует это тремя слоями:

PreToolUse хук — protect_linter_configs.sh запрещает любые правки конфигов линтеров до того, как они произойдут.
Stop hook — stop_config_guardian.sh детектирует изменения через git diff в конце сессии.
Список защищённых файлов: .ruff.toml, biome.json, .shellcheckrc, .yamllint, .hadolint.yaml и другие.

🚫 Принудительное использование менеджеров пакетов

PreToolUse хук на Bash блокирует устаревшие менеджеры пакетов:

pip, pip3, poetry, pipenv — заблокированы (требует uv).
npm, yarn, pnpm — заблокированы (требует bun).
Исключения: npm audit, npm view, npm publish.

📦 Настройка

Быстрый старт

# Установка зависимостей
brew install jaq ruff uv

# Установка Python-линтеров
uv sync --all-extras

# Запуск Claude Code — хуки активируются автоматически
claude

Никаких команд установки или конфигурации плагинов. Хуки находятся в .claude/settings.json и подхватываются при запуске claude в директории Plankton.

Интеграция в свой проект

Чтобы использовать хуки Plankton в своём проекте:

Скопировать .claude/hooks/ в свой проект.
Скопировать .claude/settings.json с конфигурацией хуков.
Скопировать файлы конфигов линтеров (.ruff.toml, biome.json, и т.д.).
Установить линтеры для используемых языков.

Конфигурационный файл

.claude/hooks/config.json управляет всем поведением Plankton. Основные параметры:

languages — включить/отключить проверку для каждого языка (можно отключить ненужные для скорости).
phases.auto_format — включить/отключить автоформатирование.
phases.subprocess_delegation — false пропускает фазу 3 (только отчёт о нарушениях).
subprocess — настройки таймаутов для каждой модели и порог объёма (volume_threshold: если нарушений больше этого числа — авто-эскалация на более мощную модель).

Переменные окружения

Переменная	Назначение
`HOOK_SKIP_SUBPROCESS=1`	Пропустить фазу 3, сообщать о нарушениях напрямую
`HOOK_SUBPROCESS_TIMEOUT=N`	Переопределить таймаут для всех уровней
`HOOK_DEBUG_MODEL=1`	Логировать выбор модели
`HOOK_SKIP_PM=1`	Отключить принудительный контроль менеджеров пакетов

🧩 Когда использовать

Вы хотите автоматическое форматирование и линтинг при каждом изменении файла, а не только при коммите.
Вам нужна защита от модификаций конфигов линтеров агентом.
Вы работаете с несколькими языками (Python, TypeScript, Shell, YAML, JSON, TOML, Markdown, Dockerfile).
Вы хотите автоматическое распределение задач между моделями Claude по сложности.
Применяется в связке с ECC (сестринский проект): ECC отвечает за общее поведение агента (команды, правила), а Plankton — за качество кода на уровне каждого файла.

💡 Важно знать

Конфликт с ECC: если вы используете оба набора хуков, то ECC's Prettier и Plankton's biome могут конфликтовать на JS/TS. Рекомендуется отключить Prettier в ECC, так как biome покрывает больше правил.
Не требует установки как плагин — просто скопируйте хуки в .claude/hooks/.
Зависимости под язык: например, для Python нужен ruff и uv, для TypeScript — biome, для Shell — shellcheck и shfmt.
Настройка volume_threshold в config.json позволяет автоматически повышать уровень модели, если нарушений слишком много.
Безопасность: PreToolUse хуки блокируют попытки агента изменить правила линтеров, что предотвращает типичный «обман» системы качества.

Установите одной командой.

npx skillfish add affaan-m/everything-claude-code plankton-code-quality

Источник: https://mcpmarket.com/tools/skills/plankton-code-quality-auto-fix