Plankton Code Quality

Plankton Code Quality Skill

Integration reference for Plankton (credit: @alxfazio), a write-time code quality enforcement system for OpenAI Codex. Plankton runs formatters and linters on every file edit via PostToolUse hooks, then spawns Codex 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 (Fast for simple style, Standard for logic, Deep for types)
• You work with multiple languages (Python, TypeScript, Shell, YAML, JSON, TOML, Markdown, Dockerfile)

How It Works

Three-Phase Architecture

Every time OpenAI Codex 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 codex -p subprocess with violations JSON
├─ Routes to model tier based on violation complexity:
│   ├─ Fast: formatting, imports, style (E/W/F codes) — 120s timeout
│   ├─ Standard: complexity, refactoring (C901, PLR codes) — 300s timeout
│   └─ Deep: 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

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:

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

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 OpenAI Codex — hooks activate automatically
codex

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

Per-Project Integration

To use Plankton hooks in your own project:

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

Language-Specific Dependencies

Pairing with ecc

Complementary, Not Overlapping

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

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 .codex/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": {
      "fast":  { "timeout": 120, "max_turns": 10 },
      "standard": { "timeout": 300, "max_turns": 10 },
      "deep":   { "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

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:

1. run formatter checks
2. run lint/type checks
3. fail fast on strict mode
4. publish remediation summary

Health Metrics

Track:

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