🎨 pi-formatter

A pi extension that auto-formats files after write and edit tool calls.

By default, formatting runs once per prompt — after the agent finishes all its work and yields control back to you. You can also format after each individual tool call or defer formatting until the session shuts down.

To format after every individual edit instead, set "formatMode": "tool".

📦 Install

pi install npm:pi-formatter

⚙️ What it does

pi-formatter detects file types and runs the appropriate formatter as best-effort post-processing. Formatter failures never block tool results.

Formatting is limited to files inside the current working directory. Paths outside the current directory and paths that traverse symlinks are ignored.

Formatting modes:

• tool: format immediately after each successful write or edit tool call. Use this mode when you want files on disk to stay formatted after every edit, even while the agent is still working.
• prompt: collect all files touched during the agent run and format them once when the agent finishes and yields control back to you. This is the default. Use this mode to avoid mid-run formatter interruptions while still getting clean files after each response.
• session: collect files touched during the current session and format them once at session shutdown, reload, or switch. Use this mode when you want the fewest interruptions and are okay with formatting only when the session ends.

Built-in supported file types:

• C/C++
• CMake
• Markdown
• JSON
• Shell
• Python
• JavaScript/TypeScript

For JS/TS and JSON, project-configured tools are preferred first (Biome, ESLint), with Prettier as a fallback.

When a project contains treefmt.toml or .treefmt.toml and treefmt is installed, pi-formatter prefers treefmt before the built-in file-type runners. This can add support for additional file types declared in the project's treefmt config. If treefmt reports that no formatter matches a path, pi-formatter falls back to the built-in runners.

For flake-based treefmt-nix setups, pi-formatter detects flake roots that contain treefmt.nix or nix/treefmt.nix and then tries nix fmt -- <path> before falling back to the built-in runners. These nix fmt calls are run with --no-update-lock-file and --no-write-lock-file so formatting does not rewrite flake lock files.

When multiple project formatter configs apply, pi-formatter uses the nearest config root. If treefmt and treefmt-nix share the same root, treefmt-nix is tried first.

🎮 Commands

• /formatter: open the interactive formatter settings editor and save changes to formatter.json

🔧 Configuration

Create <agent-dir>/formatter.json, where <agent-dir> is pi's agent config folder (default: ~/.pi/agent, overridable via PI_CODING_AGENT_DIR):

{
  "formatMode": "prompt",
  "commandTimeoutMs": 10000,
  "hideCallSummariesInTui": false
}

• formatMode: formatting strategy ("tool" | "prompt" | "session", default: "prompt"). Use "tool" to format after every individual edit.
• commandTimeoutMs: timeout (ms) per formatter command (default: 10000)
• hideCallSummariesInTui: hide formatter pass/fail summaries in the TUI (default: false)

🧩 Adding formatters

Each formatter is a runner that wraps a CLI tool behind a common interface. To add one:

1. Create a file in extensions/formatter/runners/ using defineRunner and a launcher helper (direct, pypi, or goTool).
2. Register it in extensions/formatter/runners/index.ts.
3. Add its id to a group in extensions/formatter/plan.ts.

The format plan maps file kinds to ordered runner groups. Each group runs in "all" mode (every runner) or "fallback" mode (first match wins).

📄 License

Apache-2.0