What the agent does
The agent reads the project before choosing hooks, because a hook that disagrees with the project's own tooling fails commits that CI would pass. In an app like Textualize/toolong, pyproject.toml is a Poetry project with python = "^3.8", click, textual and typing-extensions as dependencies, textual-dev as the only dev dependency, and a tl script pointing at toolong.cli:run. poetry.lock was written by Poetry 1.8.2. The source is nineteen modules under src/toolong/, most beginning with from __future__ import annotations because 3.8 has no list[str] at runtime, and using dataclasses, rich.repr and Textual's Message classes. There is no .pre-commit-config.yaml, no .github/ directory, no linter or formatter configured anywhere, and no test directory.
With nothing to match, the agent picks the smallest set that earns its keep. .pre-commit-config.yaml gets pre-commit/pre-commit-hooks at v6.0.0 with trailing-whitespace, end-of-file-fixer, check-yaml, check-toml and check-added-large-files, and astral-sh/ruff-pre-commit at v0.17.3 with ruff (with --fix) and ruff-format. It does not add mypy: the project has no type-checking configuration, and a hook that reports hundreds of findings on the first commit gets disabled rather than fixed. The ruff config goes into pyproject.toml under [tool.ruff] with target-version = "py38", matching the ^3.8 floor so ruff never suggests syntax 3.8 cannot run, src = ["src"] so first-party imports sort as such, and the default rule set plus I for import order.
The first run decides what the pull request looks like. The agent installs pre-commit and runs pre-commit run --all-files once to see what changes: ruff-format reflows anything not already in that style, ruff --fix sorts imports, and end-of-file-fixer touches files missing a final newline. It reads the diff before committing it. If formatting touches most of the nineteen modules, the pull request splits into two commits, one with the config and one with the mechanical reformat, so git blame on the second can be skipped with a .git-blame-ignore-revs file the agent also adds. Any ruff finding that is not auto-fixable, such as an unused import in cli.py, is fixed by hand in the first commit and named in the description.
Because pre-commit only helps people who installed it, the agent also adds a [tool.poetry.group.dev.dependencies] entry for pre-commit, a line in README.md under a new Development heading saying poetry install && pre-commit install, and .github/workflows/lint.yml that runs pre-commit run --all-files on pull requests with actions/setup-python on 3.8, the floor, so a contributor without the hooks installed still gets the same answer. It runs pre-commit run --all-files a second time on the finished tree and shows the all-passed output, and runs python -m toolong --help to confirm the entry point still imports after the import sorting.
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 Textual app. Read pyproject.toml, poetry.lock, README.md, .gitignore and every module under src/ first, and check for any existing linter, formatter or CI configuration. Add a .pre-commit-config.yaml with the pre-commit-hooks basics and ruff for linting with --fix and for formatting, pinned to their current releases, and configure ruff in pyproject.toml with the target version matching the project's Python floor and import sorting on. Do not add mypy. Add pre-commit as a dev dependency, a README note on installing the hooks, and a workflow that runs pre-commit on pull requests on the floor Python version. Run pre-commit on all files, read the diff, and if the reformat is large put it in its own commit with a .git-blame-ignore-revs entry. Fix any finding ruff cannot fix itself by hand. Run pre-commit again on the finished tree and run the app's --help, then open a pull request that shows both.",
"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 that adds .pre-commit-config.yaml, .github/workflows/lint.yml and, when the reformat was large, .git-blame-ignore-revs; changes pyproject.toml for the [tool.ruff] section and the pre-commit dev dependency, with poetry.lock updated by poetry lock --no-update; and changes README.md by one short section. The description lists the hooks and their pinned versions, how many files the formatter touched and which findings were fixed by hand, and shows the final all-passed pre-commit output.
The run's record keeps the first pre-commit run --all-files with every hook's changes, the diff the agent read before deciding how to split the commits, the second clean run and the --help check, so a reviewer can see what the hooks did to real files.
Before merging, a reviewer decides whether to keep the formatter hook or lint only, whether to extend the ruff rule set beyond the defaults and import order, and whether a type checker should follow in a later pull request once the code is annotated for it. The app's behaviour is unchanged; only whitespace, import order and the handful of named findings differ.
Run it on every repository with no hooks
A team that keeps several Python apps sends one POST /o/{org}/sessions per repository from the terminal or a script, with this prompt and the repository in resources, and a request_id that is a UUID v5 of the repository's full name so a retry returns the run already started. 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 pyproject.toml, so a project already on black and isort gets hooks for those at the versions it pins instead of ruff, one with a mypy section gets a mypy hook with the project's own dependencies, and one with a different Python floor gets that as ruff's target. Each opens its own pull request.
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 wrong in ways that only show on the first commit: a ruff target newer than the project's floor that rewrites code 3.8 cannot run, a formatter whose first pass rewrites every file and buries the config change, or a hook that passes on the author's machine and fails in CI because no workflow runs it. On Rush the agent reads the real floor, runs the real hooks over the real tree, reads the diff and decides how to commit it before anyone else sees it.
The first and second hook runs stay with the run and the pull request cites them, so the reviewer sees what the hooks changed rather than a description of what hooks do. Several Python repositories at once cost the same attention as one, because each run has its own sandbox, its own record and its own pull request.
Frequently asked questions
Why ruff and not black and flake8?
The project has neither configured, so there is nothing to match, and ruff covers linting, import sorting and formatting in one tool with one version to pin. A project that already uses black or flake8 gets hooks for those at its own pinned versions; the agent reads pyproject.toml before choosing.
Why no mypy hook?
The code is typed but never checked, and the first mypy run on a Textual app with no configuration reports findings in dependencies and in message handlers that take a session to settle. A hook that fails every commit from day one gets skipped with --no-verify. The pull request says a type checker belongs in a follow-up once the project has a mypy or pyright section that passes.
Will it reformat my code?
Yes, where the formatter disagrees with the current layout, and the agent reads that diff before committing it. When the reformat is large it goes in a commit of its own with its hash in .git-blame-ignore-revs, so git blame keeps pointing at the person who wrote each line rather than at the formatter.
Does this slow every commit down?
The hooks run only on the files in the commit, and ruff checks and formats a module in well under a second, so the delay is the hook environment's first install. The CI workflow runs on every file, but on pull requests, not on each commit.