# Add mypy Type Checking to a Python Project's CI

Yes. An agent adds mypy with a config that passes on your current code, installs the stubs it needs, fixes the cheap errors and puts the check in CI with a PR.

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

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

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

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

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

- [Find Dead Code in a Python Library](https://getrush.ai/run/find-dead-code/python/)
- [Fix "ImportError: cannot import name 'Mapping' from 'collections'"](https://getrush.ai/run/fix-collections-abc-import-error/python/)
- [Fix a Failing CI Build in a Python Project](https://getrush.ai/run/fix-failing-ci/python/)

## The same job on other stacks

- [Add Type Checking to a Streamlit App](https://getrush.ai/run/add-type-checking/streamlit/)
- [Add mypy Type Checking to a Textual App](https://getrush.ai/run/add-type-checking/textual/)

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