# Add mypy Type Checking to a Textual App

Yes. An agent adds mypy to your Textual app as a Poetry group with a pyproject config, fixes what it reports, adds a workflow that runs it, and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-type-checking/textual/). 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 is packaged and how far its annotations already go, because the right mypy configuration for a codebase that is half-typed is not the one for a library. In an app laid out like Textualize/toolong, `pyproject.toml` is a Poetry project at version 1.5.0 with `python = "^3.8"`, three dependencies, `click ^8.1.7`, `textual ^0.58.0` and `typing-extensions ^4.9.0`, one dev-group dependency, `textual-dev`, and a console script `tl = toolong.cli:run`; `poetry.lock` resolves Textual 0.58.0 and Click 8.1.7. `src/toolong/` holds nineteen modules and about three thousand lines, most of them starting with `from __future__ import annotations`, with `TYPE_CHECKING` imports in `watcher.py` and `goto_screen.py`, and signatures like `def run(files: list[str], merge: bool, output_merge: str) -> None` in `cli.py` beside untyped ones like `def request_exit(*args) -> None`. There is no `[tool.mypy]` table, no `py.typed`, no `tests/` directory and no `.github/` directory, so nothing checks the types today; `.gitignore` already lists `.mypy_cache/`. Textual and Click both ship type information, so most of the app's calls into them can be checked without stubs.

The agent adds mypy, current release 2.4.1, under a new `typing` Poetry group so it installs with `poetry install --with typing` and never into the app's own dependencies, and writes a `[tool.mypy]` table in `pyproject.toml`: `files = ["src"]`, `python_version` at the lowest version the project declares that this mypy still accepts, with the pull request saying which, `check_untyped_defs = true` so the bodies of functions like `request_exit` are checked even before they gain annotations, `warn_unused_ignores = true` so a stale `# type: ignore` is an error, and `warn_return_any` and `no_implicit_optional` on. It leaves `strict` off for the first pass and says so, because turning everything on in one pull request would bury the real findings under hundreds of missing-annotation notes in a codebase that was written without a checker.

Then it runs `poetry run mypy` and fixes what comes back, in the smallest form each error allows: an `Optional` that is read without a check gets the check, a function that returns different shapes gets a union, a `*args` gets a type, a Textual message handler whose attribute is typed on the subclass gets the subclass. Where an error comes from a Textual API that is looser than the app's use of it, the agent adds `# type: ignore[<code>]` with the error code and a short reason in the pull request, never a bare ignore. It does not change behaviour: the diff is annotations, narrowing and the occasional explicit cast, and `poetry run tl --help` and a run against a sample log file in the sandbox behave as before. Because there is no CI, it adds `.github/workflows/typing.yml` with one job that installs Poetry, runs `poetry install --with typing` and `poetry run mypy` on pull requests and pushes to `main`, with the actions pinned to a version.

To check it, the agent runs `poetry install --with typing` and `poetry run mypy` until the output is `Success: no issues found` and pastes that line with the module count, runs `poetry run tl --help` and `poetry run python -m toolong` on a log file it writes in the sandbox to show the app starts, and runs `poetry check` and `poetry lock --no-update` so the lockfile carries the new group. It records how many errors the first run reported and how many lines the fixes touched, so a reviewer can see the shape of the work.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Add mypy type checking to this Textual app. Read pyproject.toml, poetry.lock and every module under src/toolong first, noting which already use from __future__ import annotations and TYPE_CHECKING. Add mypy to a new typing Poetry group and a [tool.mypy] table with files set to src, python_version at the project's floor where this mypy accepts it, check_untyped_defs, warn_unused_ignores, warn_return_any and no_implicit_optional on, and strict off for now, saying why. Run poetry run mypy and fix every error with the smallest change that does not alter behaviour: annotations, narrowing, unions, casts, and # type: ignore with an error code only where a library's typing is the cause, with the reason in the pull request. Add a typing workflow under .github/workflows that installs Poetry, installs the typing group and runs mypy on pull requests and pushes to main, with pinned actions. Run mypy to a clean result, run tl --help and the app on a sample log file, update the lockfile, and open a pull request with the output and the first run's error count.",
  "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

The pull request changes `pyproject.toml`, `poetry.lock` and the modules under `src/toolong/` that needed an annotation or a check, and adds `.github/workflows/typing.yml`. Its description pastes the first mypy run's summary line with its error count, the final `Success: no issues found` line, a list of every `# type: ignore` with its code and reason, and the `tl --help` output showing the app unchanged.

The new `typing` workflow runs on the pull request itself, so the first check is mypy on a GitHub runner against the committed configuration, and the run's record keeps the full first mypy output, which is the map of where the codebase was loosest.

Before merging, a reviewer looks at each ignore and decides whether it should stay or become an upstream issue, decides whether `python_version` should track the project's floor or its lockfile, and whether to schedule a second pass with `disallow_untyped_defs` on. The app's behaviour, its dependencies and its entry point are unchanged.

## Run it on every Python project with no type checker

A team with several Python projects sends this body once per repository to `POST /o/{org}/sessions`, each with its own repository in `resources` and a `request_id` that is a UUID v5 of the repository's full name, so a retried call returns the run already started rather than opening a second pull request. Each run reads its own packaging: a project on `uv` gets a dependency group instead of a Poetry group, one with a `tox.ini` gets a `typing` env and a job that calls it, and one that already runs `ruff` in CI gets mypy as a second step in the same job.

Once the workflow is in, no further run is needed to keep the check green, because every pull request runs it. A `webhook_url` on the key reports each `run.completed` with the pull request in `result`, and a `run.failed` names a project whose first mypy run the agent could not bring to zero within its limits, with the remaining errors listed in the run's final message.

## Why run it on Rush?

Adding a checker to a codebase written without one is mostly judgement: which flags to turn on first, which errors are real and which are a library's loose stubs, and how to fix each without changing what the program does. The agent reads every module before choosing flags, fixes the errors one at a time in its own sandbox, and keeps the program's own output as proof nothing moved.

The first and last mypy runs, the list of ignores with reasons and the app's output stay with the run and are pasted into the pull request, so a reviewer reads a finished first pass instead of a configuration to argue about. Several projects can get the same treatment at once, each from its own baseline.

## Frequently asked questions

### Why not turn on strict mode from the start?

Because a codebase of this size that was written without a checker would answer with a long list of missing annotations that hide the real problems, such as an `Optional` read without a check. The first pass turns on the flags that find bugs, `check_untyped_defs` above all, and the pull request names `disallow_untyped_defs` as the next step once the suite is green.

### Will mypy understand Textual's widgets and messages?

Mostly, yes: Textual ships type information, so `compose`, `on_mount`, message handlers and reactive attributes are checked against its own signatures. Where Textual's typing is looser than the app's use, the agent adds an ignore with the error code and explains it, so the list in the pull request is also a list of things to report upstream.

### Does this change how the app runs?

No. The changes are annotations, narrowing checks, unions and casts, and the agent runs `tl --help` and the app on a sample log file before and after to show the same behaviour. mypy is in its own Poetry group, so it is not installed with the app.

### What about pyright instead?

The same shape of pull request works with pyright, with a `[tool.pyright]` table and `pyright` in the group, and the agent can be asked for either or both. mypy is the default here because the project's dependencies publish mypy-tested type information and because its error codes make the ignores precise.

## More Textual jobs

- [Migrate a Textual App From Poetry to uv](https://getrush.ai/run/migrate-to-uv/textual/)
- [Upgrade a Textual App to the Current Textual Release](https://getrush.ai/run/upgrade-textual/textual/)
- [Write Pytest Tests for a Textual Terminal App](https://getrush.ai/run/write-pytest-tests/textual/)

## The same job on other stacks

- [Add mypy Type Checking to a Python Project's CI](https://getrush.ai/run/add-type-checking/python/)
- [Add Type Checking to a Streamlit App](https://getrush.ai/run/add-type-checking/streamlit/)

## More jobs like this: Hand off a long task

- [Generate an API Reference for a TypeScript Library With TypeDoc](https://getrush.ai/run/add-typedoc/typescript-library/)

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