What the agent does
The agent runs the checker before it configures anything, because the first run says what the config has to exclude. In a site like tauri-apps/tauri-docs, package.json builds with astro build on Astro 7 and @astrojs/starlight, with starlight-links-validator, starlight-llms-txt, starlight-blog and a Lunaria translation tracker, and its scripts include format:check with Prettier and check:translations; .github/workflows/check.yml runs those two on every pull request with pnpm and Node 24 and nothing checks spelling. locales.json lists English plus fr, es, zh-cn, ja and de, and those directories sit under src/content/docs/ beside the English ones, the Japanese and Chinese trees being the largest. .prettierignore already names what is generated: src/content/docs/reference, the per-locale reference/cli.mdx, src/content/releases, public/release, the packages/releases-site generator output and the three git submodules under packages/. lunaria.config.json carries an ignoreKeywords list with typo in it, which means a commit whose message says so does not mark the translations of the pages it touches as outdated.
A first typos run over the whole checkout reports hundreds of hits, nearly all of them Spanish, French and German words in the translated pages and junk in data files: packages/releases-site/generator/data.json, the community survey CSV in public/, src/data/openCollectiveData.json, the Korean diagrams under public/d2/docs/ko whose SVG text trips the checker, and src/stale_translations. Restricted to the English pages, the run is short and mixed: real misspellings such as specifity, Februrary, transfered, occurances, capabilites, targetting, vistors, wether and prefered in the blog, distribution and development pages, next to false positives, ser three times in serde::ser::Serializer inside Rust code in develop/calling-rust.mdx and the publisher PACKT in the 1.0 announcement. Outside src/content/docs, astro.config.mjs holds Spanish sidebar labels inline, Conceptos, comandos, Versiones, which the checker reads as English typos, and a comment in src/content.config.ts hyphenates mis-slugify.
So the config is mostly a list of what not to read. The agent writes _typos.toml with files.extend-exclude covering the five translated directories, src/stale_translations, public/d2, the releases generator, the survey CSV, src/data and pnpm-lock.yaml; default.extend-identifiers with ser = "ser" so the serde path is always valid; default.extend-words with PACKT = "PACKT"; and one default.extend-ignore-re pattern for the es: label lines in the Astro config, which keeps the English labels on the lines around them checked. Then it fixes the real misspellings in the English pages only, since the translated pages are maintained by their translators and tracked by Lunaria, and writes the word typo into the commit message so Lunaria does not flag every translation of those pages. The job goes into a new typos.yml workflow on pull_request, with actions/checkout and crate-ci/typos pinned to the release the agent ran, passing the config through the action's config input, so a contributor sees the misspelling on the pull request rather than after merge.
The proof is the run itself, three times: the whole checkout before any config, to show why the excludes exist; the English pages with the config and before the fixes, listing each real hit with its file and line; and the full checkout with the config after the fixes, which reports nothing. The agent also runs pnpm format:check to show Prettier is unchanged by the edits and builds the site with astro build so the links validator confirms no fixed word was part of a heading an anchor depended on.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Add a spelling check with typos to this Starlight documentation site. Read package.json, astro.config.mjs, locales.json, lunaria.config.json, .prettierignore, .gitignore and the workflows under .github/workflows first. Install the current typos release and run it over the whole checkout, then over the English pages only, and sort the hits into real misspellings, words that are valid in code or names, and files that should not be checked: translated locales, stale translations, generated references and releases, diagram SVGs, data files and the lock file. Write a _typos.toml with those excludes, identifiers and words, and an ignore pattern for the translated labels inside the Astro config. Fix the real misspellings in the English pages only and put the word typo in the commit message so the translation tracker ignores it. Add a pull_request workflow running the typos action with the config. Show the run before the config, with it before the fixes, and after, run the formatter check and the site build, and open a pull request linked to the issue with the commands and their output.",
"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 edits the English pages that held misspellings, with the translated trees untouched. Its description shows the three runs, the list of fixed words with file and line, the false positives and how each is allowed, and the format:check and astro build results.
A reviewer checks the allowed words, decides whether the blog's older posts should be fixed or excluded as historical, and confirms the workflow's pin. After merging, a pull request with a misspelled word in an English page fails the new check with the word, the file and the suggestion.
Run it on every Linear issue labelled docs
An automation in the Project that holds the site takes a linear trigger on linear.issue.labeled with the label docs. Its runs are read-only, so the saved prompt asks for the survey: the run runs typos, sorts the hits and posts the counts and the proposed excludes as a comment on the issue, where the docs lead can say which locales and which old posts are in scope. A handler on the team's own server then starts the run that writes the pull request, sending this body with the issue's URL added to resources and a request_id that is a UUID v5 of the issue id, so a retried start returns the run already started.
A team with several Starlight sites sends one request per repository, each with its own resources entry; a site with one locale gets a short exclude list and a site with ten gets the long one.
The use case this job follows, with its automation and trigger: Turn a Linear label into a PR.
Why run it on Rush?
The checker takes a minute to add and a day to tune, because a multilingual site is mostly words it must not read: five locales, generated references, diagrams, data exports. The agent runs it in its own sandbox, reads every hit, and writes the config from what it saw rather than from a template, keeping each run's output in the run's record so the review can see why each exclude exists.
It also respects how the site is maintained: translators own the translated pages and Lunaria tracks their freshness, so the fixes stay in English and the commit message uses the keyword the tracker already ignores. Several sites get the same treatment at once, each with its own sorted list.
Frequently asked questions
Why not fix the typos in the translated pages too?
Most hits there are correct words in another language, and the few real ones belong to the translators who maintain those trees. The config excludes the locale directories, and the pull request lists their counts so the translation leads can decide separately.
Will the check complain about code samples?
Identifiers inside code are where most false positives come from, like ser in a serde path. The agent allows each one it met through extend-identifiers or extend-words, and the pull request shows the list so a reviewer can trim it.
Why a keyword in the commit message?
The site's Lunaria configuration lists typo among the keywords whose commits do not mark translations as outdated. Without it, fixing a word in an English page would flag that page's five translations as stale.
Does it run locally too?
Yes. The same _typos.toml is read by the typos binary from the repository root, and the pull request's README note gives the one-line install so a writer can run it before pushing.
More Starlight jobs
The same job on other stacks
- Add a Typo Check to a VitePress Site in CI (VitePress)
- Add a Typo Check to a Zola Site (Zola)
- Add a Typo Check to a Docusaurus Site in CI (Docusaurus)