Pi Plankton

Pi Plankton is a fork of the original alexfazio/plankton project. The original proved the useful idea: Pi can enforce code quality from inside the agent loop. This fork keeps that idea, but changes the product direction toward a Pi-first package that can bootstrap itself in any project and keep runtime linting, Git hooks, and correction subprocesses consistent.

This is not the upstream alexfazio/plankton repository. It is a maintained fork for the alfredosdpiii/pi-plankton workflow.

Why this fork exists

We forked because the workflow needed more than a checked-in project hook setup:

• Installable Pi package metadata for pi install and project-local installs.
• Automatic .plankton/ initialization in projects that do not already have it.
• Managed Git pre-commit and commit-msg hooks for commit-time enforcement.
• Pi-only subprocess delegation with a configurable correction model.
• Package-manager guardrails (uv for Python, bun for JavaScript).
• False-preserving config reads so explicit false toggles stay disabled.
• Elixir/Phoenix coverage, including Credo, Sobelow, compile warnings, dependency audit, xref warnings, and LiveView pattern checks.
• Regression tests for hook behavior, auto-init, Git hooks, package metadata, and config toggles.

What it does

Plankton is a Pi extension that runs local Bash hooks around Pi tool calls:

• Before write and edit, it blocks edits to protected linter config files.
• Before bash, it blocks disallowed package-manager commands.
• After successful write and edit, it lints the changed file.
• When violations remain, it can ask a Pi correction subprocess to fix them.
• It reports lint feedback directly in the tool result.

The extension prefers project-local hooks in .plankton/hooks/. If a project has only the package extension, bundled hooks from .pi/extensions/plankton/hooks/ are used as the fallback.

Install as a Pi package

After the npm package is published, install globally for all Pi sessions:

pi install npm:pi-plankton

Install for one project and commit .pi/settings.json for a team:

pi install -l npm:pi-plankton

You can also install directly from GitHub:

pi install git:github.com/alfredosdpiii/pi-plankton

Try a local checkout without adding it to settings:

pi -e /path/to/pi-plankton

The package manifest lives in package.json under pi.extensions. The package contains the TypeScript extension plus bundled hook scripts.

Repository-local install

To copy this checkout directly into another project:

bash /path/to/pi-plankton/scripts/install-plankton.sh /path/to/project
cd /path/to/project
pi

For this repository's own development tools:

bash scripts/setup.sh

scripts/setup.sh installs common local lint binaries such as jaq, ruff, uv, shellcheck, shfmt, hadolint, taplo, and bun when missing.

Auto initialization

When the extension starts in a recognizable project without .plankton/, it creates a project-local setup:

• .plankton/config.json
• .plankton/hooks/*.sh
• .plankton/subprocess-settings.json
• .git/hooks/pre-commit and .git/hooks/commit-msg when the project is a Git repository and those hooks are absent or already Plankton-managed

Recognized project markers include .git, package.json, pyproject.toml, uv.lock, mix.exs, Cargo.toml, go.mod, deno.json, bun.lock, pnpm-lock.yaml, yarn.lock, and package-lock.json.

Plankton does not overwrite existing custom Git hooks. Set PLANKTON_GIT_HOOKS=0 to bypass managed Git hooks temporarily.

Commands

Use these Pi slash commands:

/plankton-status                       Show config, hooks, package managers, stats
/plankton-lint <file>                  Run linting manually for one file
/plankton-toggle <lang>                Toggle a language in .plankton/config.json
/plankton-correction <provider/model>  Set the correction subprocess model

Example:

/plankton-correction gpt-5.4-mini

LLM-callable tools

The extension registers these tools for the assistant:

• plankton_lint({ path }): run linting for one project file and return a compact summary.
• plankton_config({ action, key, value }): safely read or update whitelisted config keys. The correction_model key maps to subprocess.correction_model.

Configuration

The main config file is .plankton/config.json.

Important defaults in this fork:

{
  "tested_version": "2.1.50",
  "subprocess": {
    "settings_file": ".plankton/subprocess-settings.json",
    "delegate_cmd": "pi",
    "correction_model": "gpt-5.4-mini"
  },
  "package_managers": {
    "python": "uv",
    "javascript": "bun"
  }
}

subprocess.correction_model is passed to Pi as --model for automatic correction subprocesses. Set it to any model string Pi accepts. If it is omitted, Plankton falls back to tiered model selection. The older subprocess.global_model_override key is still honored as a fallback.

The environment variable PLANKTON_CORRECTION_MODEL overrides config for one run.

Legacy delegate values are normalized at read time: auto and removed agent names become pi; unknown values become none.

Language coverage

Current hook coverage includes:

• Python: ruff, ty, flake8-async, flake8-pydantic, vulture, bandit.
• TypeScript/JavaScript/CSS: Biome, Semgrep, optional project-scoped tools.
• Elixir/Phoenix: mix format, Credo, Sobelow, compile warnings, deps audit, xref warnings, LiveView pattern checks.
• Shell: shellcheck and shfmt.
• YAML, JSON, TOML, Dockerfile, and Markdown checks.

Many tools are fail-open when the binary is not installed, so a project can start with only core dependencies and add language-specific tools over time.

Git hooks

Auto-init and scripts/install-plankton.sh install managed Git hooks when safe:

• pre-commit runs deterministic Plankton checks on staged files.
• commit-msg blocks AI attribution boilerplate such as Co-Authored-By, generated by, or AI assistant.

The managed hooks delegate to .plankton/hooks/git_pre_commit.sh and .plankton/hooks/git_commit_msg.sh.

Verification

Run the main verification suite:

bun run test

Equivalent expanded commands:

bunx tsc --noEmit
bash .plankton/test/test_auto_init.sh
bash .plankton/test/test_hook.sh --self-test
uv run pytest

Package and publish dry-runs:

npm pack --dry-run
npm publish --dry-run

Publish to npm after the dry-runs pass and you are logged in with npm login:

npm publish

Useful direct hook checks:

printf '%s' '{"tool_input":{"file_path":".ruff.toml"}}' \
  | PLANKTON_PROJECT_DIR="$PWD" bash .plankton/hooks/protect_linter_configs.sh

printf '%s' '{"tool_input":{"command":"pip install requests"}}' \
  | PLANKTON_PROJECT_DIR="$PWD" bash .plankton/hooks/enforce_package_managers.sh

bash .plankton/hooks/git_pre_commit.sh

Manual global install

Prefer pi install, but a manual global install also works:

mkdir -p ~/.pi/agent/extensions
cp -a .pi/extensions/plankton ~/.pi/agent/extensions/plankton
pi