What the agent does
The agent reads how the docs are built and checked. In a project laid out like encode/httpx, mkdocs.yml uses the Material theme with a custom_dir of docs/overrides, a nav of about twenty pages under docs/ including an advanced/ folder, and the mkautodoc extension, which pulls the API reference on docs/api.md straight from the docstrings in the httpx package, so a typo in a docstring is a typo on the site. requirements.txt pins the tooling, with a comment explaining that tools are pinned and package dependencies are not: mkdocs==1.6.1, mkdocs-material==9.6.18, mkautodoc==0.2.0, ruff==0.12.11 and mypy==1.17.1. CI in .github/workflows/test-suite.yml runs on Python 3.9 through 3.13 and calls the shell scripts in order: scripts/install, scripts/check, which runs sync-version, ruff format --diff, mypy and ruff check over httpx tests, then scripts/build, which runs python -m build, twine check and mkdocs build, then scripts/test and scripts/coverage. Nothing checks spelling anywhere.
The agent adds codespell to requirements.txt beside the other pinned tools, at the version it installs, and a [tool.codespell] table in pyproject.toml next to the existing [tool.ruff.lint] sections. The table skips docs/img, docs/css, CHANGELOG.md, the lockfile-like generated files and .git, and lists the paths to check as docs httpx tests README.md. It runs codespell once from the root and sorts the report into real misspellings, which it fixes in place, and identifiers or deliberate spellings, which go into ignore-words-list with a short comment each, so the table reads as a set of decisions.
Fixes inside docstrings change files under httpx/, so after each such edit the agent reruns scripts/check to be sure ruff format --diff and mypy are still clean, and it reruns mkdocs build so a corrected word in a Markdown file that mkautodoc or an admonition relies on still renders. Prose fixes in docs/*.md are listed in the pull request as before-and-after pairs grouped by page.
The CI change is one line in scripts/check: codespell with no arguments, since the configuration carries the paths. Because test-suite.yml already calls that script on every push and pull request across the Python matrix, no workflow file changes. The agent runs scripts/check and scripts/build end to end in its sandbox and confirms a clean exit before opening the pull request.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Add a spell check to this MkDocs project. Read mkdocs.yml, requirements.txt, pyproject.toml, every script under scripts/ and every file under .github/workflows first. Add codespell to requirements.txt pinned like the other tools, and a [tool.codespell] table in pyproject.toml that skips images, stylesheets, the changelog and generated files and checks the docs directory, the package, the tests and the README. Run codespell from the root. Fix real misspellings in Markdown prose and in docstrings, rerunning the existing check script after any change under the package and mkdocs build after any docs change; put identifiers and deliberate spellings in ignore-words-list with a comment each. Add a codespell line to the check script that CI already runs rather than a new workflow. Run the check and build scripts end to end, then open a pull request that lists every correction as a before-and-after pair grouped by page and every ignore entry with its reason.",
"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 adds the pinned codespell line to requirements.txt, the [tool.codespell] table to pyproject.toml, one line to scripts/check, and the corrected words in files under docs/ and in docstrings under the package. Its description lists the corrections as pairs grouped by page, the ignore entries with their reasons, and the output of scripts/check and scripts/build from the sandbox.
After the merge, every push and pull request runs the spell check inside the existing lint step on every Python version in the matrix, and a new misspelling fails scripts/check before the tests start, in the same place a ruff or mypy error would.
Before merging, a reviewer reads the pairs for any spelling that was intentional in context, such as a quoted error message, checks that no docstring change altered a signature line that mkautodoc renders, and decides whether the changelog should be checked after all.
Run it on every new documentation site
A team that maintains several Python projects with MkDocs sites sends this body once per repository from its own server, each a POST /o/{org}/sessions with that 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. Each run reads its own layout: a project whose CI calls pre-commit gets the codespell hook instead of a script line, and one with docs in another language gets that language's dictionary left out.
Once the check exists, an automation on the Project with a github trigger on pull_request.opened and the prompt "if the lint step failed on this pull request because of codespell, read its output and comment with the corrections, file by file" starts one run per pull request. The trigger adds the pull request after the prompt, and only work by an owner, member or collaborator fires it.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
The first pass of a spell checker over a documented library is mostly judgement: which words are identifiers, which are quoted output, which are real. The agent makes each call in the open, with a comment in the config and a pair in the pull request, and reruns the project's own check and build scripts after every change inside the package so a docstring fix never breaks a type check.
The checker's output, the check script runs and the final build stay with the run, so a reviewer can see what was flagged and what was fixed. A team with many projects starts one run per repository at once, each in its own sandbox with its own virtualenv.
Frequently asked questions
Why codespell rather than another checker?
The project pins its tooling in requirements.txt and runs it through shell scripts, and codespell is a Python package that fits both, with its configuration in pyproject.toml next to ruff. It also understands code, so identifiers in docstrings produce fewer false hits than a prose checker would.
Will fixing a docstring break anything?
It can touch a line mkautodoc renders, so the agent reruns the check script, which includes ruff format --diff and mypy, and mkdocs build after any change under the package. A fix that changes a signature line is reverted and listed as a question for the reviewer.
Why no new workflow file?
The existing test-suite.yml already runs scripts/check on every push and pull request. One line in that script adds the check across the whole Python matrix, with nothing new to maintain in .github/workflows/.
What goes in the ignore list?
Identifiers that read as typos, deliberate spellings in quoted output and names, each with a comment saying which page or module uses it. The pull request lists them so a reviewer can object to any before merge.
More MkDocs jobs
The same job on other stacks
- Add a Typo Check to a Pelican Site (Pelican)
- Add a Typo Check to a Sphinx Documentation Site (Sphinx)
- Add a Typo Check to Starlight Docs (Starlight)