# Add Pre-commit Hooks to a Textual App

Yes. An agent adds a pre-commit config with ruff and the basic file hooks to your Textual app, pinned to its Python floor, runs it on every file, and opens a PR.

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

## 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`

```json
{
  "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"
    }
  ]
}
```

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 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.

## 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.

## More Textual jobs

- [Add a Release Workflow for a Textual App](https://getrush.ai/run/add-release-workflow/textual/)
- [Add Shell Completion to a Textual App's CLI](https://getrush.ai/run/add-shell-completion/textual/)
- [Add Snapshot Tests to a Textual App](https://getrush.ai/run/add-snapshot-tests/textual/)

## The same job on other stacks

- [Add pre-commit Hooks to an Ansible Role](https://getrush.ai/run/add-pre-commit-hooks/ansible/)
- [Add pre-commit Hooks to a CMake C++ Project](https://getrush.ai/run/add-pre-commit-hooks/cmake/)
- [Add dbt-checkpoint Pre-commit Hooks to a dbt Project](https://getrush.ai/run/add-pre-commit-hooks/dbt/)

## 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/)
