What the agent does
The agent reads how the site is built and tested before it changes anything. In a site laid out like github/choosealicense.com, Gemfile pins jekyll ~> 4.3 with jekyll-seo-tag, jekyll-sitemap, jekyll-redirect-from, jekyll-github-metadata and jekyll-polyglot, and .ruby-version says 4.0.5. _config.yml declares seven languages with en as default_lang, a licenses collection output under /licenses/:path/, and an exclude list that already keeps script, spec, vendor/bundle and the license-list-XML submodule out of the build. The prose is six Markdown pages at the root (about.md, appendix.md, community.md, no-permission.md, non-software.md, terms-of-service.md) plus index.html and licenses.html; the 47 files under _licenses/ carry YAML front matter with a description, how, using and rule lists above the verbatim license body; _data/i18n/<lang>/ and i18n/<lang>/ hold the translations; and .github/workflows/test.yml runs script/cibuild, which is bundle exec rake test (a Jekyll build, the RSpec suite in spec/, then html-proofer over _site) followed by RuboCop. Nothing checks spelling.
The configuration is _typos.toml at the root, and its exclusions are the point of the job. TRANSLATING.md says the legal text of a license is never translated and CONTRIBUTING.md says it must match the SPDX text wrapped at 78 characters, so a spelling fix inside a license body would be a change to a legal document: files.extend-exclude lists _licenses/, and the agent says so in a comment. It also excludes i18n/, _data/i18n/ (the English dictionary would flag every French and Korean string), license-list-XML/ (an SPDX submodule) and assets/vendor/. The _data files that stay in scope are rules.yml, fields.yml and meta.yml, whose labels and descriptions are English prose. SPDX identifiers such as bsd-3-clause-clear, lppl-1.3c and mulanpsl-2.0 appear in file names, front matter and appendix.md, so they go under default.extend-identifiers rather than being corrected.
The agent installs typos-cli with cargo install --locked, runs typos from the root and works through the report. Prose corrections in the root pages, the _includes/*.html partials, the _layouts and the front-matter summaries in _licenses/*.txt are made in place; the front matter is above the license body and is site copy, not legal text, which the comment in _typos.toml spells out. After editing a license file's front matter the agent runs bundle exec rspec so the specs in spec/, which read every license's metadata and check it against the approved lists, still pass, and bundle exec jekyll build so a broken YAML key does not stop the build.
The CI job is a second job in .github/workflows/test.yml named typos, running crate-ci/typos pinned to a release tag on ubuntu-latest, with submodules: false on its checkout since the SPDX submodule is excluded anyway. It needs no Ruby, so it finishes long before the build-and-html-proofer job. The agent runs actionlint over the edited workflow, then script/cibuild end to end and typos once more to confirm 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 Jekyll site. Read _config.yml, Gemfile, .ruby-version, Rakefile, script/cibuild, spec/, .github/workflows/test.yml, CONTRIBUTING.md, TRANSLATING.md and the layout of _licenses/, _data/, i18n/ and _includes/ first. Install typos-cli with cargo install --locked and write _typos.toml at the root with files.extend-exclude for _licenses/, i18n/, _data/i18n/, license-list-XML/ and assets/vendor/, each with a comment saying why; put SPDX identifiers under default.extend-identifiers. Run typos from the root. Fix real misspellings in the root Markdown pages, the includes, the layouts and the English data files; never edit the body of a license file. Run bundle exec rspec and bundle exec jekyll build after the edits. Add a separate typos job to .github/workflows/test.yml using crate-ci/typos pinned to a release tag. Run actionlint, script/cibuild and typos until everything exits clean, then open a pull request that lists every correction as a before-and-after pair grouped by file and every exclusion 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, adds the typos job to .github/workflows/test.yml, and changes the root Markdown pages, includes, layouts and English data files where a word was corrected. Its description lists the corrections as before-and-after pairs grouped by file, each exclusion with the sentence from TRANSLATING.md or CONTRIBUTING.md that justifies it, the RSpec and Jekyll build summaries after the edits, and the final typos exit status.
No file under _licenses/ changes its body, and the description says so in one line, because that is the first thing a maintainer of a license site will look for. If a correction lands in a license's front-matter description or how line, the description names the license so the translation maintainers know the English source string moved.
Before merging, a reviewer reads the pairs for a spelling that was intentional, checks that the excluded directories match the site's own rules rather than a guess, and decides whether the job should also run on a schedule so a new release of the typos dictionary surfaces older misspellings between pull requests.
Run it on every pull request
A team that maintains several Jekyll 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 that builds with the native GitHub Pages build and has no workflow gets a new typos.yml instead of a second job, and one without collections or translations gets a config with no exclusions beyond vendor/.
Once the job exists, an automation on the Project with a github trigger on pull_request.synchronize and the prompt "if the typos job failed on this pull request, read its log and comment with the corrections it suggests, file by file, without pushing" starts one run per push to an open pull request. The trigger adds the pull request after the prompt and fills in nothing else, and it fires only for work by an owner, member or collaborator, so a fork's pull request keeps its red check until a maintainer acts.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
On a site whose content is legal text, a spell checker is dangerous unless the boundary is drawn exactly: one wrong exclusion and the pull request rewrites a sentence of the GPL. The agent draws that boundary from the repository's own rules, writes each exclusion down with its reason, and proves the rest of the site still builds and passes its specs, all in a sandbox where it can run Ruby, Bundler and the full script/cibuild without touching anyone's machine.
The typos report, the RSpec run, the Jekyll build and the html-proofer output stay with the run, so a reviewer can see the decision behind every allow-list entry and every exclusion. A team with many Jekyll sites runs the same request across all of them at once, each in its own sandbox, and compares the results.
Frequently asked questions
Why is the whole `_licenses/` directory excluded when only the body is legal text?
typos exclusions are per file, not per section, and the body of each .txt file is the part that must match SPDX byte for byte. Excluding the directory is the safe default; the agent then checks the front-matter summaries separately by reading the report for _data/meta.yml and the appendix.md tables, which repeat most of the same English text.
Will it fix typos in the French or Korean translations?
No. i18n/ and _data/i18n/ are excluded because an English dictionary would flag most of their content, and TRANSLATING.md says missing or stale strings fall back to English at build time, so a translation is never the cause of a broken page. A translator can run typos with a language-specific dictionary on their own directory later.
Why a separate job rather than a step in the existing one?
The existing job installs Ruby 4.0.5 with Bundler caching, builds the site, runs RSpec and then html-proofer over _site, which takes minutes. The typos action needs none of that, so a job of its own reports within seconds of a push, and a spelling failure does not hide behind a build failure.
Does it change the html-proofer or RuboCop configuration?
No. Rakefile and .rubocop.yml stay as they are. The agent runs script/cibuild after its edits only to prove the build, specs, html-proofer and RuboCop still pass with the corrected files in place.
More Jekyll jobs
The same job on other stacks
- Add a Typo Check to an mdBook in CI (mdBook)
- Add a Spell Check to MkDocs Docs in CI (MkDocs)
- Add a Typo Check to a Pelican Site (Pelican)