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 with this body:
{
"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"
}
]
}- 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.
- 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.
- 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.
The use case this job follows, with its automation and trigger: Hand off a long task.
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.