
python-format
Python formatting and lint reporting through Ruff, gated to repositories with a Ruff config.
- GitHub stars
- 32
What it does
- Adds
setupskill to verify prerequisites, register git pre-commit entries, and report which formatter and linter run - Formats Python files with Ruff once per batch of tool calls, silently, using
ruff formatafter import sorting - Reports Ruff lint findings at git pre-commit on lines the commit adds, with no lint autofix running
- Designed for projects that already configure Ruff and want formatting to happen without manual steps
Formats Python with Ruff once per batch of tool calls and at git pre-commit, and reports Ruff lint findings at commit, only where a Ruff config governs the file; formatting and linting are separate, no lint autofix runs, and hooks never run an ecosystem record's command.
Add marketplace
/plugin marketplace add melodic-software/claude-code-pluginsRun it inside Claude Code once, then install the plugin below.
Install
/plugin install python-format@melodic-softwareRun it inside Claude Code after adding the marketplace.
Files
Discovered from sourceReadme
python-format
A Claude Code plugin that formats and lints Python with Ruff, as two separate concerns, wherever your repository has opted into Ruff. Formatting runs once per batch of tool calls in a Claude Code session and again at git pre-commit for every author; linting reports at pre-commit, on the lines the commit adds. No lint autofix runs in either place, and no finding reaches Claude on each edit.
The hooks run only the shipped Ruff adapter, when a .ruff.toml, ruff.toml or pyproject.toml
with a [tool.ruff] section governs the file: import sorting where your lint config selects it,
then ruff format; ruff check for lint. A repository without one is left untouched, and
/python-format:setup check reports the concern unresolved.
The hooks never run a command from your python record (.claude/ecosystems/python.yaml, the
ecosystem-commands contract in the marketplace repository). That record names any formatter and
linter you use, and /toolchain:lint and /toolchain:check run it when you ask.
The plugin ships no rules of its own.
Behavior
- One format per batch, silent. A
PostToolBatchrow runs after the tool calls of a turn step resolve. It takes the.pyand.pyifiles thatWrite,EditorMultiEditcalls in the batch named, and runs the Ruff adapter once over those a Ruff config governs. It prints nothing and exits0. A file thatReadnamed is never rewritten.- The row has no matcher or
if. Its launcher skips the script unless the payload mentions.py, so a batch without Python costs onenodeprocess. - Pointer: when deciding what filters a
PostToolBatchrow, fetch hooks: PostToolBatch live.
- The row has no matcher or
- Ruff adapter opt-in. The adapter walks up from the file to the repository root for a Ruff
config. Known limitation: a
pyproject.tomlthat uses a bare[tool]header with an inlineruff = { ... }table is not recognized, so the adapter skips (a missed opt-in, never a wrong edit).- Pointer: when comparing this walk with Ruff's own, fetch Config file discovery live.
- Pre-existing drift is rewritten whole. The batch payload carries no pre-edit bytes, so a file that already drifted from your config is formatted in full, as the pre-commit entry would.
- Respects your excludes. The adapter passes
--force-excludeand--no-cache. Files under.githooks/(installed copies) and gitignored files (unlesspython_format_lint_gitignoredis set) are skipped.
Git pre-commit entries
The plugin ships two git-hook entries (git-hooks/entries.json):
formatrewrites. At commit it refuses a partly staged Python file untouched, runs the resolved format command over the staged.pyand.pyifiles, and re-stages what changed.lintreports. It runs the resolved lint command and blocks the commit only on a finding on a line the commit adds, printed as<path>:<line>: <message>. A linter that exits non-zero with no such line fails the commit and shows its output.
They reach every author, not only Claude, once
/python-format:setup apply install-git-hooks [scope=local|shared] registers them with the
repository's hook manager (lefthook, husky or plain git hooks). Local scope stays in this clone;
shared scope commits the copies under .githooks/python-format/. /python-format:setup check
reports drift, including a copy of the earlier single ruff-check entry, which that action
retires; a decline of ruff-check carries to both.
When the resolved tool is missing, an agent's commit fails with the install command; a person's
commit gets a one-line notice and goes through. git -c checks.skipmissing=<tool> commit ... skips
the entry while the tool is absent. The placement rules are the check-placement convention in the
marketplace repository.
An opt-in Stop row (python_format_end_of_turn) runs the lint entry over the uncommitted changes
at the end of a turn and hands findings back to Claude once per turn.
Requirements
- Bash. The hook is a Bash script. On native Windows, install Git for Windows so Claude Code can run it under Git Bash.
- Node.js on
PATH. Every hook row launches throughnode hooks/exec-bash.mjs, which finds Bash. A missingnodeis a hook launch error, not a skip notice. - jq on
PATH. Reads the file paths from thePostToolBatchpayload. Absent: the batch row does nothing, and the SessionStart probe reports it. Install jq. - Ruff available to the repo. The Ruff adapter resolves it from the repo's
.venv(.venv/bin/ruff, or.venv/Scripts/ruff.exeon Windows, walking up from the edited file) orPATH, and never downloads it; when it is absent the batch row skips the file. Ruff 0.12+ is recommended for the adapter (tested against 0.17.4). - A SessionStart probe reports a missing
ruffonce per session, fromprerequisites.json, only where a Ruff config sits in the project directory or above it or is tracked anywhere in its repository, and a drifted git-hook entry. Runnode "<plugin root>/lib/prerequisites.mjs" check "<plugin root>"to see what resolves; it is read-only and installs nothing.
The hook scripts run on Bash 3.2+.
Hook budget accounting
Per docs/contracts/hook-budget/README.md,
the PostToolBatch row is always-on: the event has no matcher, so it fires on every batch of every
session. Its launcher flag --skip-unless-stdin-contains .py closes before bash starts when the
payload never mentions .py. Measured on WSL2 Ubuntu (bash 5.3.9, ruff 0.17.0, node 24) on
2026-10-15, with the row launched as hooks.json registers it, ten fires per case; spawns are
from scripts/hook-census.sh:
| Batch | Median wall | Min-max | Spawns |
|---|---|---|---|
No .py in the payload | 0.031 s | 0.030-0.033 s | 1 (the node launcher) |
A Read of a .py file, nothing to rewrite | 0.039 s | 0.036-0.041 s | 6 |
One Edit of a .py file that needs a rewrite | 0.083 s | 0.073-0.107 s | 17 |
The ceiling for a per-batch formatter row is 1 s median per fire. Fences:
.performance/ratchets.json holds the no-Python row at 1 spawn, and the Stop row with
python_format_end_of_turn off (its default) at 1 spawn. The Ruff adapter path measured 20 spawns
before and after the resolver landed (2026-11-16, WSL2 Ubuntu, bash 5.3.9).
Install
/plugin marketplace add melodic-software/claude-code-plugins
/plugin install python-format@melodic-software
Then verify prerequisites with /python-format:setup check.
Configuration
The rules themselves are never configured here. They come from the Ruff config already in your repository, which the plugin reads automatically. To change the rules, edit that file.
Three userConfig options tune the hooks themselves:
| Option | Default | Effect |
|---|---|---|
python_format_enabled | true | Kill switch. Set false for a clean no-op. |
python_format_lint_gitignored | false | Set true to rewrite a file the repository gitignores. Off by default. |
python_format_end_of_turn | false | Set true to run the pre-commit check over the uncommitted changes when a turn ends; findings go back to Claude once per turn so they are fixed before it stops. Nothing is rewritten. |
Set them interactively with /plugin configure python-format@<marketplace>, or headless on the
install command:
claude plugin install python-format@<marketplace> --config python_format_enabled=false
Options reference
Generated from this plugin's .claude-plugin/plugin.json. For how Claude Code asks for
these and hands them to the plugin, see User configuration.
| Option | Type | Default | Description |
|---|---|---|---|
python_format_enabled | boolean | true | After each batch of tool calls, run the resolved format command over the Python files it wrote |
python_format_lint_gitignored | boolean | false | By default the hook leaves a file the repository gitignores alone: it is not rewritten or linted, since a rewrite of an ignored file has no git checkout to undo it. Set true to act on gitignored files too. A tracked file that matches an ignore pattern is always in scope. |
python_format_end_of_turn | boolean | false | At the end of each turn, run the pre-commit lint entry over the lines changed since the last commit and hand any findings back so they are fixed before the turn ends, at most once per turn. Nothing is rewritten. Off by default. |
How to set these
Set the options above for python-format@<marketplace>, replacing <marketplace> with the
marketplace you installed this plugin from:
- In a session or headless:
/pluginin a session orclaude plugin configure. The configure command is the preferred headless route in the plugin-reconfiguration convention, which records its limits. - By hand: under
pluginConfigsin your user settings.
Do not uninstall the plugin to reconfigure it: see What an uninstall deletes and keeps.
For a Claude Code release without plugin configure, see Plugin install.
Upstream documentation
- User configuration
- Plugin configure
- Plugin install options
- Plugins and skills settings
- Settings files and who they affect
- Manage installed plugins
License
MIT (SPDX-License-Identifier: MIT).
Details
- Marketplace
- melodic-software/claude-code-plugins
- Source
- plugins/python-format
- Category
- Development
More from melodic-software/claude-code-plugins
All 139- rate-limit-guard
- rate-limits
- repo-fleet-hygiene
- repo-hygiene
- requirements-elicitationv1.0.0
- researchv1.0.0
- response-qualityv1.0.0
- retro-audio
- review
- ruff-format
- securityv1.0.0
- session-flow
- session-telemetry
- skill-quality
- soft-skillsv1.0.0
- songwriting
- source-control
- spec-driven-developmentv1.0.0
- speech
- spelling
- sql-server
- systems-designv1.0.0
- tacv1.0.0
- tdd
Similar to python-format
More Development Tools
reamorluto/rea466.8K starsReverse engineer anything with agents, from app behavior down to native binaries.
superpowersobra/superpowers319.5K starsCore skills library for Claude Code: TDD, debugging, collaboration patterns, and proven techniques
claude-apianthropics/skills196.9K starsClaude API and SDK documentation skill for building LLM-powered applications
prompts.chatf/prompts.chat178.2K starsAccess thousands of AI prompts and skills directly in your AI coding assistant. Search prompts, discover skills, save your own, and improve prompts with AI.
agent-sdk-devanthropics/claude-code156.1K starsDevelopment kit for working with the Claude Agent SDK
ui-ux-pro-maxnextlevelbuilder/ui-ux-pro-max-skill152.6K starsProfessional UI/UX design intelligence for AI coding assistants. Includes searchable databases of styles, colors, typography, charts, and UX guidelines for Reac