# Add Pre-commit Hooks to a Python Project

Yes. An agent adds a pre-commit config that runs your project's own pinned ruff and mypy before each commit, matching the existing check scripts, and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-pre-commit-hooks/python/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

The agent reads how the project already checks itself before it adds a hook. In a library like encode/httpx, `scripts/check` runs `ruff format --diff`, `mypy` and `ruff check` over `httpx tests`, `scripts/lint` runs `ruff check --fix` and `ruff format` to fix what it can, and `scripts/test` runs `scripts/check` first unless it is on GitHub Actions, then `coverage run -m pytest`, then `scripts/coverage` with `--fail-under=100`. `requirements.txt` pins the tooling to exact versions, `ruff==0.12.11`, `mypy==1.17.1`, `coverage[toml]==7.10.6` and `pytest==8.4.1`, and installs the package itself with its `brotli`, `cli`, `http2`, `socks` and `zstd` extras, with a comment explaining that tooling is pinned and package dependencies are not. `.github/workflows/test-suite.yml` runs `scripts/install`, `scripts/check`, `scripts/build`, `scripts/test` and `scripts/coverage` on Python 3.9 through 3.13, and `.github/CONTRIBUTING.md` tells contributors to run `scripts/check` before pushing. There is no `.pre-commit-config.yaml`.

The rule configuration lives in `pyproject.toml`: `[tool.ruff.lint]` selects `E`, `F`, `I`, `B` and `PIE` and ignores `B904` and `B028`, `[tool.ruff.lint.isort]` combines as-imports, `__init__.py` is exempt from `F403` and `F405`, and `[tool.mypy]` is `strict` with `ignore_missing_imports`, relaxed for `tests.*` to `check_untyped_defs`. Because `mypy` in strict mode needs the project's own dependencies and the typed test helpers `trio-typing` and `trustme` importable, a hook that runs it in pre-commit's isolated environment would report errors the project's own `scripts/check` never sees.

So the agent writes `.pre-commit-config.yaml` with two kinds of hooks. From the `pre-commit/pre-commit-hooks` repository, pinned to a release tag, it takes `trailing-whitespace`, `end-of-file-fixer`, `check-yaml` and `check-toml`, none of which the project runs today. For the project's own tools it declares `repo: local` hooks with `language: system`: `ruff format --check`, `ruff check` and `mypy`, each restricted with `files` to `^(httpx|tests)/` and each calling the executables from the virtual environment `scripts/install` creates, so the versions are exactly the ones `requirements.txt` pins and the hook result is the `scripts/check` result. The `mypy` hook sets `pass_filenames: false` and runs on the two directories, because strict mypy on a single changed file misses errors in its importers. It adds `pre-commit` to `requirements.txt`, pinned the way the other tools are, appends `pre-commit install` to `scripts/install` so the hooks are installed when a contributor sets up, and adds a short paragraph to `CONTRIBUTING.md`.

Before it pushes, the agent runs `scripts/install` in its sandbox on the lowest supported Python, `3.9`, then `pre-commit run --all-files` and `scripts/check`, and compares the two outputs to show they agree. If the file-fixing hooks change anything, such as a missing final newline in a docs file, it keeps those edits in a separate commit so the reviewer can see them apart from the config. CI is left unchanged, because `test-suite.yml` already runs `scripts/check`, and the pull request says so.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Add pre-commit hooks to this Python project and open a pull request. Read scripts/install, scripts/check, scripts/lint, scripts/test, requirements.txt, pyproject.toml, .github/workflows/test-suite.yml and .github/CONTRIBUTING.md first. Write .pre-commit-config.yaml with trailing-whitespace, end-of-file-fixer, check-yaml and check-toml from pre-commit/pre-commit-hooks pinned to a release, and local system hooks that run the project's own pinned ruff format --check, ruff check and mypy from the virtual environment over the same paths scripts/check uses, so the hook result equals the scripts/check result; run mypy on the whole package rather than per file. Add pre-commit to requirements.txt pinned like the other tools, add pre-commit install to scripts/install, and document it in CONTRIBUTING.md. Do not change CI. Run scripts/install, pre-commit run --all-files and scripts/check on Python 3.9 in the sandbox, keep any fixes the hooks make in a separate commit, and quote the outputs in the pull request.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

1. **Get an API key.** In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
2. **Send the request.** POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
3. **Read what came back.** Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

## What comes back

What comes back is a pull request on its own branch that adds `.pre-commit-config.yaml`, adds a pinned `pre-commit` line to `requirements.txt`, appends `pre-commit install` to `scripts/install`, and adds a paragraph to `.github/CONTRIBUTING.md`. If the whitespace hooks touched any file, those edits are in a second commit titled for what they fixed. `pyproject.toml`, `scripts/check` and the workflows are unchanged.

The proof is the sandbox output quoted in the description and kept in the run's record: `pre-commit run --all-files` with each hook's result, `scripts/check` run after it with the same result, and the Python version both ran on. The repository's own `test-suite.yml` runs on the pull request as well, which shows that nothing in the five-version matrix changed.

Before merging, a reviewer checks that the `pre-commit-hooks` tag is a recent release, that the `files` patterns match what `scripts/check` covers and nothing more, that running `mypy` on every commit is acceptable for the project's size, and that the `CONTRIBUTING.md` wording fits the house style. Then they run `scripts/install` on their own machine and make a commit to see the hooks fire.

## Run it on every repository with check scripts and no hooks

A team that keeps several Python packages sends one `POST /o/{org}/sessions` per repository from the terminal or a script, with this prompt and the repository in `resources`. `GET /o/{org}/github` lists every repository the Rush GitHub App installation can reach, so a script can clone each and start a run only where there is no `.pre-commit-config.yaml`. Each run reads that project's own scripts and `pyproject.toml`, so a project on `black` and `flake8` gets hooks for those instead, and each opens its own pull request.

Set a webhook URL on the API key and Rush POSTs `run.completed` or `run.failed` when a run's turn finishes, with `session_url` so your server can read the pull request link. Send a fresh UUID as `request_id` with each request so a retry returns the run already started.

## Why run it on Rush?

A pre-commit config is easy to write and easy to get subtly wrong: a `ruff` mirror pinned to a different version than `requirements.txt` fails commits that CI would pass, and a `mypy` hook in an isolated environment reports missing imports the project never sees. On Rush the agent reads the exact pins and the exact paths from `scripts/check`, mirrors them in local hooks, and runs both the hooks and the script in its own sandbox to show they agree, so the first review is of a config that already matches CI. Nothing is installed on your machine.

Every command and its output stay in the run's record, the diff is a handful of files, and any mechanical fixes the hooks made are in their own commit. The same request can add hooks to every Python repository the team owns, each run reading that project's own tooling, one pull request each.

## Frequently asked questions

### Why local hooks instead of the ruff and mypy pre-commit mirrors?

Because the project pins `ruff==0.12.11` and `mypy==1.17.1` in `requirements.txt` and its strict mypy needs the package's own dependencies importable. Local `language: system` hooks run those exact installed versions, so a commit that passes the hooks passes `scripts/check` and CI. The mirrors would need a second set of pins and a list of `additional_dependencies` to keep in step.

### Does this slow every commit down?

`ruff` takes well under a second on a project this size. `mypy` in strict mode over `httpx` and `tests` is the slow hook, and it runs on the whole package by design. If that is too slow for day-to-day commits, move the mypy hook to the `pre-push` stage in the config and the agent can make that change in a follow-up.

### Does CI change?

No. `test-suite.yml` already runs `scripts/check`, which is the same ruff and mypy invocation the hooks run, so adding a `pre-commit run --all-files` job would double the work. The hooks exist to catch problems before a push, and CI stays the arbiter.

### Will it reformat my code?

Only if a hook that fixes files finds something. `ruff format --check` and `ruff check` in the hooks report without changing anything, matching `scripts/check`. `trailing-whitespace` and `end-of-file-fixer` do edit, and any edits they made in the run are in a separate commit you can read or drop.

## More Python jobs

- [Add towncrier Changelog Fragments to a Python Package](https://getrush.ai/run/add-towncrier-changelog/python/)
- [Add mypy Type Checking to a Python Project's CI](https://getrush.ai/run/add-type-checking/python/)
- [Find Dead Code in a Python Library](https://getrush.ai/run/find-dead-code/python/)

## The same job on other stacks

- [Add Pre-commit Hooks to a Reflex App](https://getrush.ai/run/add-pre-commit-hooks/reflex/)
- [Add Pre-commit Hooks With fmt, validate, tflint and terraform-docs to a Terraform Repo](https://getrush.ai/run/add-pre-commit-hooks/terraform/)
- [Add Pre-commit Hooks to a Textual App](https://getrush.ai/run/add-pre-commit-hooks/textual/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
