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 with this body:
{
"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"
}
]
}- 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
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.
The use case this job follows, with its automation and trigger: Hand off a long task.
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
The same job on other stacks
- Add mypy Type Checking to a Python Project's CI (Python)
- Add Type Checking to a Streamlit App (Streamlit)
More jobs like this: Hand off a long task
- Generate an API Reference for a TypeScript Library With TypeDoc (TypeScript library)