What the agent does
The agent reads the templates before touching them. In a theme like janraasch/hugo-bearblog, layouts/_default/single.html prints, for a page of type blog that is not a menu entry, an h1 and a <time> whose format comes from .Site.Params.dateFormat with 02 Jan, 2006 as the default, then .Content and the post_footer.html partial with the tags. layouts/_default/list.html renders each post as a <time> and a link inside ul.blog-posts. There is no .ReadingTime or .WordCount anywhere in layouts/, theme.toml names min_version = "v0.110.0", and exampleSite/hugo.toml documents the theme's parameters, including the commented dateFormat and enablePostNavigator, which is the pattern a new option should follow.
Hugo already computes the number: every page has .ReadingTime, an integer of minutes derived from .WordCount at the rate Hugo uses, and .FuzzyWordCount beside it. The agent adds a reading_time.html partial that prints {{ .ReadingTime }} min read, with the singular handled for one minute, and includes it after the <time> in both templates inside the same <i> so the look matches the date. It is wrapped in {{ if .Param "showReadingTime" }}, which reads the page's front matter first and the site's [params] second, so a site that upgrades the theme sees no change until it opts in, and a single post can turn it off. exampleSite/hugo.toml gets showReadingTime = true with a comment in the style of the others, and the README's configuration section gets one line.
The build is the check. .github/workflows/ci.yml runs hugo --minify --gc --destination ../public --source ./exampleSite --themesDir ../.. --baseURL https://janraasch.github.io/hugo-bearblog/ with peaceiris/actions-hugo@v3.2.1 at the latest Hugo, so the agent runs the same command in its sandbox and reads public/markdown-syntax/index.html, the one post in exampleSite/content/blog/, to confirm the line appears once on the post and once in the blog list, and not on bear.md or hugo.md, which are pages, not posts.
Because Hugo has no test runner, the agent adds the assertion to the workflow: a step after the build that greps the rendered post for min read and fails if it is missing, and greps the home page to confirm it is absent there. That turns a visual check into one CI already runs on every pull request, and the deploy job that follows it with peaceiris/actions-gh-pages@v4.1.0 is unchanged.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Add a reading-time line to this Hugo theme. Read layouts/_default/single.html, layouts/_default/list.html, layouts/_default/baseof.html, layouts/partials/post_footer.html, theme.toml, exampleSite/hugo.toml, exampleSite/content/blog/markdown-syntax.md, README.md and .github/workflows/ci.yml first. Add layouts/partials/reading_time.html that prints .ReadingTime as `N min read` with the singular handled, and include it after the date in single.html and list.html inside the same element so it matches the date's style, behind `.Param \"showReadingTime\"` so sites and single posts can opt in or out. Set showReadingTime = true in exampleSite/hugo.toml with a comment like the other parameters, and document it in README.md. Build the example site with the exact hugo command the CI workflow uses, confirm the line appears on the post and the blog list and not on the pages, add a workflow step that greps the rendered post for the line, and open a pull request with the build output and the rendered snippet.",
"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 layouts/partials/reading_time.html, changes layouts/_default/single.html and list.html, exampleSite/hugo.toml, README.md and .github/workflows/ci.yml. Its description pastes the hugo build output and the rendered <i> element from the post, so a reviewer sees the exact markup next to the date.
A reader opening a post sees the date and 3 min read in one italic line; the blog list shows the same beside each title. Sites that use the theme keep their current output until they set showReadingTime, and a long post can set it false in front matter without a template override. Nothing is added to the page's CSS or JavaScript, which keeps the theme's no-stylesheets, no-scripts promise from theme.toml.
Before merging, a reviewer decides whether the default should be on for the example site only or for every site, checks the wording against the theme's minimal tone, and, for a site with hasCJKLanguage set, confirms the count Hugo produces reads sensibly for that content.
Run it on every theme without a reading-time line
Someone maintaining several Hugo sites starts one run per repository from the terminal: one POST /o/{org}/sessions each with that repository in resources and a request_id that is a UUID v5 of its full name, so a retried call returns the run already started. Each run reads its own layouts: a site that vendors its theme gets the partial in its own layouts/partials/, which Hugo prefers over the theme's, one that already prints .WordCount gets the minutes beside it, and a multilingual site gets the string through i18n with a key per language.
Each run opens its own pull request on its own branch, and GET /o/{org}/sessions lists them newest first, so the person who started the batch reads every build result from one place.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
A template change is judged by rendered HTML, and the mistakes are quiet: a line that appears on the home page because the blog type check was skipped, a parameter name that silently reads as false, or a build that passes on an old Hugo and fails on the version CI installs. The agent builds the example site with the workflow's own command in its sandbox, reads the output files, and leaves the grep step so the check repeats on every pull request.
The run keeps every command and its output, so the reviewer sees the build and the rendered snippet without installing Hugo. Several sites can be updated at once, each in its own sandbox, and one that already shows reading time is left with a note rather than a second line.
Frequently asked questions
Where does the number come from?
Hugo computes .ReadingTime for every page from its word count, so the template reads a value that already exists and adds no build step. The pull request does not change how Hugo counts; a site that sets hasCJKLanguage gets Hugo's count for that case.
Will existing sites change when they update the theme?
No. The partial renders only when showReadingTime is true, read through .Param, which checks the page's front matter and then the site's [params]. A site that does not set it sees today's output. The example site sets it so the demo shows the feature.
Can one post hide it?
Yes. showReadingTime = false in that post's front matter overrides the site value, because .Param looks at the page first. That covers a photo post or a link post where the minutes would mislead.
Why add a grep step to CI instead of a test?
Hugo has no test runner, and the workflow already builds the example site on every pull request. A step that reads the rendered post for the line is the cheapest assertion that fails if a later template edit drops the partial, and it needs no new tool.
More Hugo jobs
The same job on other stacks
- Add Reading Time to a Jekyll Blog (Jekyll)
- Add Reading Time to a Pelican Blog (Pelican)
- Add Reading Time to a VitePress Blog (VitePress)