Back to Details

plankton-code-quality

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Plankton Code Quality Skill

Plankton代码质量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.
Plankton集成参考（作者：@alxfazio），这是一款面向Claude Code的编写时代码质量管控系统。Plankton通过PostToolUse钩子在每次文件编辑时运行格式化工具和linter，然后启动Claude子进程来修复Agent未捕获的违规问题。

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)
  • 你需要在每次文件编辑时（而非仅提交时）自动执行格式化和代码检查
  • 你需要防止Agent为了通过检查而修改linter配置而非修复代码
  • 你需要分等级的模型路由来处理修复任务（Haiku处理简单样式问题，Sonnet处理逻辑问题，Opus处理类型问题）
  • 你使用多种语言开发（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)
每次Claude Code编辑或写入文件时，Plankton的
multi_linter.sh
PostToolUse钩子就会运行：
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

主Agent可见内容

ScenarioAgent seesHook exit
No violationsNothing0
All fixed by subprocessNothing0
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.
场景Agent可见内容钩子退出码
无违规问题无0
所有问题都被子进程修复无0
子进程处理后仍有违规问题
[hook] N violation(s) remain
2
建议通知（重复项、旧工具等）
[hook:advisory] ...
0
主Agent只会看到子进程无法修复的问题，大多数质量问题都会被透明处理。

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:
  1. PreToolUse hook — 
    protect_linter_configs.sh
    blocks edits to all linter configs before they happen
  2. Stop hook — 
    stop_config_guardian.sh
    detects config changes via 
    git diff
    at session end
  3. Protected files list — 
    .ruff.toml
    , 
    biome.json
    , 
    .shellcheckrc
    , 
    .yamllint
    , 
    .hadolint.yaml
    , and more
LLM会修改
.ruff.toml
或
biome.json
来禁用规则，而不是修复代码。Plankton通过三层机制阻止这种行为：
  1. PreToolUse钩子 — 
    protect_linter_configs.sh
    会在编辑行为发生前阻止对所有linter配置的修改
  2. Stop钩子 — 
    stop_config_guardian.sh
    会在会话结束时通过
    git diff
    检测配置变更
  3. 受保护文件列表 — 
    .ruff.toml
    、
    biome.json
    、
    .shellcheckrc
    、
    .yamllint
    、
    .hadolint.yaml
    等

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
Bash上的PreToolUse钩子会阻止旧版包管理器：
  • pip
    、
    pip3
    、
    poetry
    、
    pipenv
    → 已阻止（请使用
    uv
    ）
  • npm
    、
    yarn
    、
    pnpm
    → 已阻止（请使用
    bun
    ）
  • 允许的例外情况：
    npm audit
    、
    npm view
    、
    npm publish

Setup

安装配置

Quick Start

快速开始

bash
undefined
bash
undefined

Clone Plankton into your project (or a shared location)

Clone Plankton到你的项目（或共享目录）

Note: Plankton is by @alxfazio

注意：Plankton作者为@alxfazio

git clone https://github.com/alexfazio/plankton.git cd plankton
git clone https://github.com/alexfazio/plankton.git cd plankton

Install core dependencies

安装核心依赖

brew install jaq ruff uv
brew install jaq ruff uv

Install Python linters

安装Python linters

uv sync --all-extras
uv sync --all-extras

Start Claude Code — hooks activate automatically

启动Claude Code — 钩子会自动激活

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.
claude

无需安装命令，无需插件配置。当你在Plankton目录下运行Claude Code时，`.claude/settings.json`中的钩子会被自动加载。

Per-Project Integration

单项目集成

To use Plankton hooks in your own project:
  1. Copy 
    .claude/hooks/
    directory to your project
  2. Copy 
    .claude/settings.json
    hook configuration
  3. Copy linter config files (
    .ruff.toml
    , 
    biome.json
    , etc.)
  4. Install the linters for your languages
要在你自己的项目中使用Plankton钩子：
  1. 复制
    .claude/hooks/
    目录到你的项目
  2. 复制
    .claude/settings.json
    中的钩子配置
  3. 复制linter配置文件（
    .ruff.toml
    、
    biome.json
    等）
  4. 安装对应语言的linters

Language-Specific Dependencies

语言相关依赖

LanguageRequiredOptional
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
—
语言必须依赖可选依赖
Python
ruff
、
uv
ty
（类型检查）、
vulture
（死代码检测）、
bandit
（安全检测）
TypeScript/JS
biome
oxlint
、
semgrep
、
knip
（死导出检测）
Shell
shellcheck
、
shfmt
—
YAML
yamllint
—
Markdown
markdownlint-cli2
—
Dockerfile
hadolint
(>= 2.12.0)		—
TOML
taplo
—
JSON
jaq
—

Pairing with ECC

与ECC搭配使用

Complementary, Not Overlapping

互补而非重叠

ConcernECCPlankton
Code quality enforcementPostToolUse hooks (Prettier, tsc)PostToolUse hooks (20+ linters + subprocess fixes)
Security scanningAgentShield, security-reviewer agentBandit (Python), Semgrep (TypeScript)
Config protection—PreToolUse blocks + Stop hook detection
Package managerDetection + setupEnforcement (blocks legacy PMs)
CI integration—Pre-commit hooks for git
Model routingManual (
/model opus
)		Automatic (violation complexity → tier)
功能ECCPlankton
代码质量管控PostToolUse钩子（Prettier、tsc）PostToolUse钩子（20+ linters + 子进程修复）
安全扫描AgentShield、安全审查AgentBandit（Python）、Semgrep（TypeScript）
配置保护—PreToolUse拦截 + Stop钩子检测
包管理器检测 + 配置强制管控（阻止旧版包管理器）
CI集成—Git预提交钩子
模型路由手动（
/model opus
）		自动（根据违规复杂度分配等级）

Recommended Combination

推荐组合

  1. Install ECC as your plugin (agents, skills, commands, rules)
  2. Add Plankton hooks for write-time quality enforcement
  3. Use AgentShield for security audits
  4. Use ECC's verification-loop as a final gate before PRs
  1. 安装ECC作为你的插件（提供Agent、Skill、命令、规则）
  2. 添加Plankton钩子实现编写时质量管控
  3. 使用AgentShield做安全审计
  4. 使用ECC的验证循环作为PR前的最终检查关卡

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)
如果同时运行ECC和Plankton钩子：
  • ECC的Prettier钩子和Plankton的biome格式化工具可能在JS/TS文件上产生冲突
  • 解决方案：使用Plankton时禁用ECC的Prettier PostToolUse钩子（Plankton的biome功能更全面）
  • 两者可以在不同文件类型上共存（ECC处理Plankton未覆盖的内容）

Configuration Reference

配置参考

Plankton's 
.claude/hooks/config.json
controls all behavior:
json
{
  "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)
Plankton的
.claude/hooks/config.json
控制所有行为：
json
{
  "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
  }
}
关键配置：
  • 禁用你不需要的语言来提升钩子运行速度
  • volume_threshold
    — 违规数量超过该值时自动升级到更高等级的模型处理
  • subprocess_delegation: false
    — 完全跳过第三阶段（仅上报违规问题）

Environment Overrides

环境变量覆写

VariablePurpose
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
变量用途
HOOK_SKIP_SUBPROCESS=1
跳过第三阶段，直接上报违规问题
HOOK_SUBPROCESS_TIMEOUT=N
覆写模型等级超时时间
HOOK_DEBUG_MODEL=1
打印模型选择决策日志
HOOK_SKIP_PM=1
绕过包管理器强制管控

References

参考资料

  • Plankton (credit: @alxfazio)
  • Plankton REFERENCE.md — Full architecture documentation (credit: @alxfazio)
  • Plankton SETUP.md — Detailed installation guide (credit: @alxfazio)
  • Plankton（作者：@alxfazio）
  • Plankton REFERENCE.md — 完整架构文档（作者：@alxfazio）
  • Plankton SETUP.md — 详细安装指南（作者：@alxfazio）