What the agent does
The agent reads the templates before it changes a macro, because Zola already computes the number and the theme decides where it shows. In a site on the Terminimal theme, as in pawroman/zola-theme-terminimal, config.toml sets compile_sass = true, generate_feeds = true, a tags taxonomy and an [extra] table with accent_color, background_color, logo_text, menu_items, enable_post_view_navigation and post_view_navigation_prompt, which are the theme's switches, each documented in the README and mirrored with defaults in theme.toml. templates/macros/post.html holds the pieces of a post: header prints the title as a link, a .post-meta-inline div with the date macro, then the tags macro; content prints the summary or the full content; list_posts is the compact list the archive uses, with the date and the title on one line. templates/page.html and the listing in templates/index.html both call header, so one macro covers the post page and the home page. Nothing in the templates reads reading_time or word_count.
Zola's template documentation lists reading_time on every page as an estimate in minutes using per-language silent-reading rates, next to word_count, so no plugin, shortcode or script is needed. The agent adds show_reading_time to [extra] in config.toml and theme.toml, off by default so every site already on the theme renders exactly as before, and in the header macro, after the date macro and inside the same .post-meta-inline div, prints :: {{ page.reading_time }} min read when config.extra.show_reading_time is true and page.reading_time is set, using the :: separator the theme already uses between the date and the tags. A .post-reading-time class gets a rule in sass/post.scss beside .post-date, with the same --accent-alpha-70 variable, so it sits in the theme's colour scheme for each of the accent and background variants under sass/color/.
The archive is a separate choice. list_posts prints {{ page.date }} :: title per line and the agent leaves it alone, because a minutes figure on a dense archive adds noise, and says so in the pull request; a site that wants it there adds the same conditional to that macro. The README gains the new key in its configuration section, in the same block as enable_post_view_navigation, and the theme's example config.toml turns it on so the demo shows it.
The sandbox has no Zola, so the agent downloads the zola-v0.23.6-x86_64-unknown-linux-gnu.tar.gz asset of the current release from GitHub and runs zola build in the theme's own directory, where config.toml and content/ make the theme its own demo site. It reads public/zola-is-nice/index.html for the minutes next to the date, reads the home page to confirm the list shows the same figure for that post, reads the archive page to confirm it is unchanged, runs zola check, and serves public/ to open a post in its own browser. It also builds once with the switch off to show the templates render exactly as before, and quotes theme.toml's min_version = "0.11.0" in the pull request so a site pinned to an old Zola knows which floor the theme promises.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Show an estimated reading time on the posts of this Zola site using Zola's built-in page.reading_time. Read config.toml, theme.toml, templates/index.html, templates/page.html, templates/archive.html, templates/macros/post.html, templates/macros/head.html, sass/post.scss, the content directory and the README first. Add an extra.show_reading_time switch, off by default, to config.toml and theme.toml; in the header macro print the minutes after the date inside the post-meta-inline div with the theme's :: separator when the switch is on, so the post page and the home page list both show it; leave the archive list alone and say why. Add a rule to sass/post.scss using the theme's existing variables, document the key in the README and turn it on in the example config. Download the current Zola release, build with the switch on and off, run zola check, confirm the figure on a post and on the home page and its absence on the archive, open a post in a browser, and open a pull request 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 changes templates/macros/post.html, sass/post.scss, config.toml, theme.toml and README.md. Its description quotes the zola build summary for both builds, the zola check result, the rendered .post-meta-inline line of one post from the post page and from the home page, the unchanged archive line, and a screenshot. No content file and no other template changes.
A reviewer checks the wording after the number, whether the archive should carry it too, and whether their own site turns the switch on. After merging, a site on the theme sees no change until it sets show_reading_time = true, which is the point of the default.
Run it on every Zola site in the terminal
A developer with zola serve running sends this body from their own machine with the site in resources and reads the pull request from the console when the webhook on their API key reports the run. A team with several Zola sites sends one request per repository, each with a request_id that is a UUID v5 of the repository's full name, so a script run twice returns the runs already started rather than a second set of pull requests.
Each run reads its own theme: a site whose theme already prints reading_time gets a pull request that only adds the switch it lacks, and a site with [languages] gets the figure per language, since Zola picks the reading rate from each page's language.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
The variable is built in, so the work is placement and restraint: which macro both the post and the list go through, which separator and colour the theme already uses, whether the archive should change, and whether a site that never asked for the feature still renders the same. Those are checked by building, so the agent downloads Zola in its own sandbox, builds twice, runs the link check, reads the generated pages and opens one in a browser, keeping every command and its output in the run's record.
It also keeps the theme's conventions: an [extra] key with a default in theme.toml, a README entry, a Sass rule on the theme's own variables so every colour variant works. Ten sites on ten Zola themes get ten pull requests, each placing the figure where that theme prints its post metadata.
Frequently asked questions
How does Zola compute the minutes?
The template documentation says reading_time is an estimate in minutes from per-language silent-reading rates, computed from the same text word_count counts, and it does not publish the rates. There is no setting to change it; a site that wants its own figure divides page.word_count by its own rate in the template, and the pull request shows that line as an alternative.
Why is the switch off by default?
Because the macro belongs to a theme many sites use, and a theme update should not change how their posts look. The example config turns it on so the demo shows the feature, and a site opts in with one line under [extra].
Does it work for posts in Chinese or Japanese?
Zola's documentation says that for zh and ja the word count is a character count and the reading rate is per language, so a multilingual site gets a sensible figure per page without configuration. The theme prints whatever the page reports.
Will the feeds change?
No. The RSS and Atom feeds come from Zola's feed templates, not from the theme's post macros, so the minutes appear only in the HTML. config.toml keeps generate_feeds and feed_filenames as they are.