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
# Clone Plankton into your project (or a shared location)
# Note: Plankton is by @alxfazio
git clone https://github.com/alexfazio/plankton.git
cd plankton
# 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)
1---2name: plankton-code-quality3description: "Write-time code quality enforcement using Plankton — auto-formatting, linting, and Claude-powered fixes on every file edit via hooks."4origin: community5metadata:6 source: https://skillmd.com/skills/x-cmd/plankton-code-quality7---89# Plankton Code Quality Skill1011Integration 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.1213## When to Use1415- You want automatic formatting and linting on every file edit (not just at commit time)16- You need defense against agents modifying linter configs to pass instead of fixing code17- You want tiered model routing for fixes (Haiku for simple style, Sonnet for logic, Opus for types)18- You work with multiple languages (Python, TypeScript, Shell, YAML, JSON, TOML, Markdown, Dockerfile)1920## How It Works2122### Three-Phase Architecture2324Every time Claude Code edits or writes a file, Plankton's `multi_linter.sh` PostToolUse hook runs:2526```27Phase 1: Auto-Format (Silent)28├─ Runs formatters (ruff format, biome, shfmt, taplo, markdownlint)29├─ Fixes 40-50% of issues silently30└─ No output to main agent3132Phase 2: Collect Violations (JSON)33├─ Runs linters and collects unfixable violations34├─ Returns structured JSON: {line, column, code, message, linter}35└─ Still no output to main agent3637Phase 3: Delegate + Verify38├─ Spawns claude -p subprocess with violations JSON39├─ Routes to model tier based on violation complexity:40│ ├─ Haiku: formatting, imports, style (E/W/F codes) — 120s timeout41│ ├─ Sonnet: complexity, refactoring (C901, PLR codes) — 300s timeout42│ └─ Opus: type system, deep reasoning (unresolved-attribute) — 600s timeout43├─ Re-runs Phase 1+2 to verify fixes44└─ Exit 0 if clean, Exit 2 if violations remain (reported to main agent)45```4647### What the Main Agent Sees4849| Scenario | Agent sees | Hook exit |50|----------|-----------|-----------|51| No violations | Nothing | 0 |52| All fixed by subprocess | Nothing | 0 |53| Violations remain after subprocess | `[hook] N violation(s) remain` | 2 |54| Advisory (duplicates, old tooling) | `[hook:advisory] ...` | 0 |5556The main agent only sees issues the subprocess couldn't fix. Most quality problems are resolved transparently.5758### Config Protection (Defense Against Rule-Gaming)5960LLMs will modify `.ruff.toml` or `biome.json` to disable rules rather than fix code. Plankton blocks this with three layers:61621. **PreToolUse hook** — `protect_linter_configs.sh` blocks edits to all linter configs before they happen632. **Stop hook** — `stop_config_guardian.sh` detects config changes via `git diff` at session end643. **Protected files list** — `.ruff.toml`, `biome.json`, `.shellcheckrc`, `.yamllint`, `.hadolint.yaml`, and more6566### Package Manager Enforcement6768A PreToolUse hook on Bash blocks legacy package managers:69- `pip`, `pip3`, `poetry`, `pipenv` → Blocked (use `uv`)70- `npm`, `yarn`, `pnpm` → Blocked (use `bun`)71- Allowed exceptions: `npm audit`, `npm view`, `npm publish`7273## Setup7475### Quick Start7677```bash78# Clone Plankton into your project (or a shared location)79# Note: Plankton is by @alxfazio80git clone https://github.com/alexfazio/plankton.git81cd plankton8283# Install core dependencies84brew install jaq ruff uv8586# Install Python linters87uv sync --all-extras8889# Start Claude Code — hooks activate automatically90claude91```9293No install command, no plugin config. The hooks in `.claude/settings.json` are picked up automatically when you run Claude Code in the Plankton directory.9495### Per-Project Integration9697To use Plankton hooks in your own project:98991. Copy `.claude/hooks/` directory to your project1002. Copy `.claude/settings.json` hook configuration1013. Copy linter config files (`.ruff.toml`, `biome.json`, etc.)1024. Install the linters for your languages103104### Language-Specific Dependencies105106| Language | Required | Optional |107|----------|----------|----------|108| Python | `ruff`, `uv` | `ty` (types), `vulture` (dead code), `bandit` (security) |109| TypeScript/JS | `biome` | `oxlint`, `semgrep`, `knip` (dead exports) |110| Shell | `shellcheck`, `shfmt` | — |111| YAML | `yamllint` | — |112| Markdown | `markdownlint-cli2` | — |113| Dockerfile | `hadolint` (>= 2.12.0) | — |114| TOML | `taplo` | — |115| JSON | `jaq` | — |116117## Pairing with ECC118119### Complementary, Not Overlapping120121| Concern | ECC | Plankton |122|---------|-----|----------|123| Code quality enforcement | PostToolUse hooks (Prettier, tsc) | PostToolUse hooks (20+ linters + subprocess fixes) |124| Security scanning | AgentShield, security-reviewer agent | Bandit (Python), Semgrep (TypeScript) |125| Config protection | — | PreToolUse blocks + Stop hook detection |126| Package manager | Detection + setup | Enforcement (blocks legacy PMs) |127| CI integration | — | Pre-commit hooks for git |128| Model routing | Manual (`/model opus`) | Automatic (violation complexity → tier) |129130### Recommended Combination1311321. Install ECC as your plugin (agents, skills, commands, rules)1332. Add Plankton hooks for write-time quality enforcement1343. Use AgentShield for security audits1354. Use ECC's verification-loop as a final gate before PRs136137### Avoiding Hook Conflicts138139If running both ECC and Plankton hooks:140- ECC's Prettier hook and Plankton's biome formatter may conflict on JS/TS files141- Resolution: disable ECC's Prettier PostToolUse hook when using Plankton (Plankton's biome is more comprehensive)142- Both can coexist on different file types (ECC handles what Plankton doesn't cover)143144## Configuration Reference145146Plankton's `.claude/hooks/config.json` controls all behavior:147148```json149{150 "languages": {151 "python": true,152 "shell": true,153 "yaml": true,154 "json": true,155 "toml": true,156 "dockerfile": true,157 "markdown": true,158 "typescript": {159 "enabled": true,160 "js_runtime": "auto",161 "biome_nursery": "warn",162 "semgrep": true163 }164 },165 "phases": {166 "auto_format": true,167 "subprocess_delegation": true168 },169 "subprocess": {170 "tiers": {171 "haiku": { "timeout": 120, "max_turns": 10 },172 "sonnet": { "timeout": 300, "max_turns": 10 },173 "opus": { "timeout": 600, "max_turns": 15 }174 },175 "volume_threshold": 5176 }177}178```179180**Key settings:**181- Disable languages you don't use to speed up hooks182- `volume_threshold` — violations > this count auto-escalate to a higher model tier183- `subprocess_delegation: false` — skip Phase 3 entirely (just report violations)184185## Environment Overrides186187| Variable | Purpose |188|----------|---------|189| `HOOK_SKIP_SUBPROCESS=1` | Skip Phase 3, report violations directly |190| `HOOK_SUBPROCESS_TIMEOUT=N` | Override tier timeout |191| `HOOK_DEBUG_MODEL=1` | Log model selection decisions |192| `HOOK_SKIP_PM=1` | Bypass package manager enforcement |193194## References195196- Plankton (credit: @alxfazio)197- Plankton REFERENCE.md — Full architecture documentation (credit: @alxfazio)198- Plankton SETUP.md — Detailed installation guide (credit: @alxfazio)