What the agent does
The agent clones the repository into its own cloud sandbox and reads how the project is packaged and checked before it adds a tool. In a project like httpie/cli, setup.py is two lines and everything is in setup.cfg: python_requires = >=3.7, install_requires with requests[socks], Pygments, rich, multidict, charset_normalizer, defusedxml and requests-toolbelt, a dev extra listing pytest, pytest-httpbin, responses, flake8 with four plugins, pyopenssl, pytest-cov and twine, and a [flake8] section that ignores E501 and W503. The Makefile has a codestyle target that runs flake8 over httpie/ tests/ extras/profiling/ docs/packaging/brew/ *.py, and .github/workflows/code-style.yml runs make venv and make codestyle on Python 3.9 for every pull request that touches Python files; tests.yml runs pytest on a matrix from 3.7 to 3.12 across three operating systems. Nothing mentions mypy or pyright: not setup.cfg, not the Makefile, not a workflow.
It then reads the code to see what a checker will meet. httpie/compat.py carries MIN_SUPPORTED_PY_VERSION = (3, 7) and MAX_SUPPORTED_PY_VERSION = (3, 11) and a cached_property fallback for old interpreters; httpie/models.py annotates its methods (iter_body(self, chunk_size: int) -> Iterable[bytes]) but not HTTPMessage.__init__, which is the mix of typed and untyped code a first mypy run meets everywhere. The package has cli/, output/ with its formatters and lexers, plugins/, manager/, internal/ and legacy/, and httpie/cli/argparser.py is the largest module at a few hundred lines.
The agent installs the project with pip install -e '.[dev]' in a virtual environment, adds mypy to the dev extra, and runs mypy httpie once with no configuration to get the baseline. Mypy's own notes name the stub packages for dependencies without inline types (types-requests, types-Pygments, and whichever others the run lists), which the agent adds to the extra and installs; the remaining errors it groups by module. The configuration goes in setup.cfg under [mypy], where the project already keeps its tool settings: python_version set to the lowest version the installed mypy still accepts, ignore_missing_imports only for the modules the run named and no stub package covers, warn_unused_ignores, and check_untyped_defs off for now, since turning it on at the same time as adding the gate would make the first pull request unreadable. Errors that are cheap and safe to fix (an Optional missing on a parameter that defaults to None, a return annotation that disagrees with the body) it fixes in the code; errors that need a design decision get a # type: ignore[code] with the error code so warn_unused_ignores catches them when they go away, and each one is listed in the pull request by file and count.
The check joins the project's own tooling: a typecheck target in the Makefile beside codestyle, a typecheck job in code-style.yml that runs make typecheck on the same Python version, and a line in CONTRIBUTING.md. The agent runs make codestyle, make typecheck and pytest in the sandbox to show the three pass together, and keeps the output.
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 Python project. Read setup.cfg, setup.py, the Makefile and the workflows under .github/workflows first. Install the project with its dev extra, add mypy to that extra, and run mypy on the package once with no configuration to get a baseline. Install the stub packages mypy's notes name and add them to the dev extra. Write a [mypy] section in the file where the project keeps its tool configuration, strict enough to catch new errors but passing on the current code: fix errors that are small and safe, and mark the rest with a type: ignore carrying the error code, listed by file in the pull request. Add a typecheck target to the Makefile and a job to the existing style workflow. Run the style check, the type check and the test suite, and open a pull request with the baseline error count by module and what is left to fix.",
"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 edits setup.cfg (the dev extra and the [mypy] section), the Makefile, .github/workflows/code-style.yml and CONTRIBUTING.md, and touches the modules where a cheap fix or an annotated ignore was needed. The description has the baseline table, errors by module from the first run, then what was fixed, what was marked, and the make typecheck and pytest output from the sandbox.
The run's record keeps the first mypy httpie run in full, the stub installs with their versions, and the final clean run, so a reviewer can see the starting point without reproducing it.
Before merging, a reviewer decides whether the chosen python_version matches the lowest version the project still supports, reads each type: ignore to confirm none hides a real bug, and picks which module to make check_untyped_defs clean first.
Run it on every new repository
A platform team with many Python repositories starts one run per repository from its own server: one POST /o/{org}/sessions with this body and the repository in resources, with a request_id that is a UUID v5 of the repository name so a retried call returns the first run. Each run reads that repository's own packaging and workflows, so the configuration lands where that project keeps it and the job joins its existing CI.
A webhook URL on the API key receives run.completed or run.failed for each run with session_url, and the server collects the pull request links with each one's baseline count.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
The first mypy run on an established codebase is the hard part: hundreds of errors, half of them missing stubs, and a configuration that is either too strict to merge or too loose to be worth having. The agent does the baseline run, reads the notes, fixes what is safe and marks what is not, and the pull request shows the count before and after rather than a bare green check.
Everything runs in the sandbox with the project's own Makefile and extras, and the output stays in the record. Several repositories can get the same gate at the same time, each with its own baseline.
Frequently asked questions
Will the first pull request make the whole codebase type-clean?
No, and it should not try. It adds a gate that passes on the current code, fixes the cheap errors, and marks the rest with error codes so they are visible and counted. Making a module strict is a follow-up run per module.
Why mypy rather than pyright?
Either works; mypy fits a project whose configuration already lives in setup.cfg and whose CI runs make targets. Say pyright in input and the agent writes a pyrightconfig.json and the equivalent job instead.
Does it change runtime behaviour?
Only where a fix is a real correction, such as an Optional the code already handled, and the test suite runs after every change. Annotations and type: ignore comments have no effect at runtime.
What if a dependency has no stubs at all?
Mypy's notes say so, and the agent adds that module to ignore_missing_imports by name rather than globally, so a dependency that later ships types is picked up as soon as warn_unused_ignores flags the entry.
More Python jobs
The same job on other stacks
- Add Type Checking to a Streamlit App (Streamlit)
- Add mypy Type Checking to a Textual App (Textual)
More jobs like this: Hand off a long task
- Generate an API Reference for a TypeScript Library With TypeDoc (TypeScript library)