What the agent does
The agent starts by reading how the site is built and what already checks it. In a site laid out like testing-library/testing-library-docs, package.json pins @docusaurus/core and @docusaurus/preset-classic at ^2.0.1 with React 16, .node-version says 16.14, the lockfile is package-lock.json, and the only formatting is Prettier through kcd-scripts, run by a Husky pre-commit hook over *.js, *.mdx and *.json. The content is 110 .mdx files and 4 .md files under docs/, split into one directory per library (dom-testing-library, react-testing-library, user-event, queries and fourteen more), plus three posts under blog/ and three React pages under src/pages. .github/ holds two issue templates and no workflows/ directory, and netlify.toml is what builds the site, with npm install; npm run format; npm run build. Nothing checks spelling anywhere.
The configuration goes in _typos.toml at the root. files.extend-exclude lists .all-contributorsrc, because it is a JSON list of GitHub logins and avatar URLs, and package-lock.json, whose integrity hashes are noise; build/, .docusaurus/ and node_modules/ are already in .gitignore, which typos honours. The users array in docusaurus.config.js holds brand captions such as Coches.net, Fotocasa, Habitaclia and Sweepbright, so those go under default.extend-words with a comment saying they are company names from the showcase, not prose. The agent installs typos-cli with cargo install --locked, runs typos from the root, and reads the report with the MDX in mind: a word inside a fenced block that is a query name or a test id (getByRole, findByText, ByLabelText) is an identifier and belongs in default.extend-identifiers with the file that uses it, while a misspelling in a sentence is fixed in place.
The corrections are made file by file. Prose in docs/*.mdx and the three blog posts is edited directly; a typo inside a code block comment is fixed, and a typo that is also a variable name is left alone and recorded. Because the MDX imports Tabs and TabItem from @theme and uses the npm2yarn remark plugin, the agent runs npm run build after the edits so a stray character inside JSX does not slip through, and runs npm run format the way Netlify does, so the diff Prettier would make is already in the pull request rather than appearing at deploy time.
The CI job is the repository's first workflow, .github/workflows/typos.yml, running on pull_request and on pushes to main with permissions: contents: read, one step on ubuntu-latest that checks out the code and runs crate-ci/typos pinned to a release tag. It needs no Node, so it reports in seconds, and it runs on a fork's pull request too, since it is a plain Actions job. The agent runs actionlint over the new file and typos once more for 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 typo check to this Docusaurus site. Read package.json, .node-version, netlify.toml, docusaurus.config.js, sidebars.js, .gitignore and the layout of docs/, blog/, src/ and .github/ first. Install typos-cli with cargo install --locked and write _typos.toml at the root: exclude .all-contributorsrc and package-lock.json under files.extend-exclude, and put the brand names from the users array in docusaurus.config.js under default.extend-words with a comment. Run typos from the root. Fix real misspellings in the MDX and Markdown prose and in comments inside code blocks; never change an identifier inside a code block, record it under default.extend-identifiers with the file that uses it instead. Run npm ci, npm run format and npm run build after the edits. Add .github/workflows/typos.yml running crate-ci/typos pinned to a release tag on pull_request and on pushes to main, with contents: read permissions. Run actionlint on the workflow and typos until it exits clean, then open a pull request listing every correction as a before-and-after pair grouped by directory under docs/, and every allow-list 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 _typos.toml and .github/workflows/typos.yml, and changes the .mdx and .md files under docs/ and blog/ where a word was corrected, plus whatever npm run format rewrote. Its description lists the corrections as before-and-after pairs grouped by the directory they live in, the allow-list entries with their reasons, the npm run build summary after the edits, and the final typos exit status.
Because the site has never had a workflow, the first run of the new job on the pull request itself is the proof that the configuration works on GitHub's runner and not only in the sandbox; the pull request's checks tab shows it beside the Netlify deploy preview.
Before merging, a reviewer scans the pairs for a spelling that was deliberate (a quoted error message, a British spelling in a contributor's post), decides whether brand names should stay in extend-words or move to a separate [default.extend-words] block per showcase, and whether to require the new check in branch protection once it has run green for a while.
Run it on every typos workflow failure
A team that maintains several Docusaurus sites sends this body once per repository from its own server, each 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 site: one with an existing ci.yml gets the job added there rather than in a new file, and one whose docs are versioned under versioned_docs/ gets that directory excluded, since old versions are frozen.
Once the job exists, an automation on the Project with a github trigger on workflow_run.failure and the prompt "the typos workflow failed on this branch; read its log, apply the corrections it suggests to the prose, leave identifiers alone and push one commit" starts one run per failed check. The trigger adds the event after the prompt and fills in nothing else; it fires only for work by an owner, member or collaborator, and never for a CI run from a fork, so a contributor's pull request still gets the red check and a maintainer applies the fix.
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 documentation site is mostly judgement: more than a hundred MDX files full of query names, test ids and showcase brands that look like typos, and a Prettier step that rewrites files at deploy time. The agent makes every call in the open, with a comment in _typos.toml and a line in the pull request, and runs the same npm run build Netlify will run so a broken JSX block never reaches the deploy preview.
The checker's report, the build output and the final clean exit stay with the run, so a reviewer sees why each allow-list entry exists. A team that owns the docs for several libraries runs the same request across all of them at once, each in its own sandbox, and reads the results side by side.
Frequently asked questions
Will it touch the code examples in the MDX?
Only comments inside them. A word that is an identifier, such as a query name or a test id, is never changed; it goes under default.extend-identifiers with a note naming the file. The agent runs npm run build after every batch of edits so a change inside a fenced block that breaks the MDX compiler is caught in the sandbox.
The site has no CI at all. Is a typos job a sensible first workflow?
Yes, because it needs nothing the site needs: no Node version, no npm install, no build. It is one checkout and one action, reports in seconds, and gives the repository a green or red check on every pull request for the first time. A build check can be added beside it later.
Why exclude the contributors file?
.all-contributorsrc is a JSON list of GitHub logins, display names and avatar URLs. Almost every login reads as a misspelling to a dictionary, and the file is regenerated by the all-contributors bot, so a correction there would be undone and would break a link to a real account.
What about the Prettier step Netlify runs?
The build command in netlify.toml runs npm run format before npm run build, so any file the agent edits would be reformatted at deploy time. The agent runs the same format step in the sandbox and commits the result, so the pull request shows the final content and the deploy preview matches it.