What the agent does
The agent reads the layouts before it writes a filter chain. In a blog started from barryclark/jekyll-now, _layouts/post.html wraps the post in <article class="post">, prints page.title, the content in a .entry div, then a .date div reading Written on {{ page.date | date: "%B %e, %Y" }} and the Disqus include; index.html loops site.posts and prints each title, post.excerpt and a Read More link, with no date at all. style.scss styles .date as italic in the $gray variable from _sass/_variables.scss. _config.yml lists jekyll-sitemap and jekyll-feed under gems, sets permalink: /:title/, and there is no Gemfile, because .gitignore excludes one and the README's local workflow is gem install github-pages followed by jekyll serve. That gem set pins Jekyll 3.10.0 and no reading-time plugin, so the job has to be done in Liquid.
Jekyll's number_of_words filter counts the words of a string, and the standard math filters plus, divided_by and at_least are all in the Liquid 4.0.4 that ships with the GitHub Pages gem. The agent adds _includes/reading-time.html, which takes the text it is given, assigns words from number_of_words, computes words | plus: 199 | divided_by: 200 so an integer division rounds up instead of down, and prints 1 min read or n min read with at_least: 1 so a short post never says zero. The words-per-minute value is one assign at the top of the include with a comment, and the include is called from post.html with include.content set to content, inside the .date div after the date, and from index.html with post.content, next to the Read More link, so the list and the post agree.
Two details decide whether the number is honest. content in a layout is the rendered HTML, so the agent passes it through strip_html before counting, otherwise tag names and attributes inflate a post with images or code. And the index must count post.content, not post.excerpt, or every post on the front page reads as a one-minute post. The agent writes both into the include so a caller cannot get it wrong, and adds a .reading-time rule next to .date in style.scss using the same $gray, so the line looks like the date it sits beside.
Then it builds the way the README says. It installs the github-pages gem in its own sandbox and runs jekyll build. The repository has one post, _posts/2014-3-3-Hello-World.md, which is short, so the agent copies the site to a scratch directory, adds a post of about a thousand words, builds that copy and reads _site/index.html and the two post pages to confirm 1 min read and 5 min read, then serves it and opens both in its own browser. The committed site keeps its one post.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Add an estimated reading time to the posts of this Jekyll blog, which is hosted on GitHub Pages without a Gemfile, so use Liquid only. Read _config.yml, index.html, _layouts/post.html, _layouts/default.html, style.scss, _sass/_variables.scss, _posts and the README first. Add an _includes/reading-time.html that strips HTML from the text it is given, counts words with number_of_words, divides by 200 words per minute rounding up, and prints n min read with a minimum of 1; include it in the post layout beside the date and in index.html for each post using post.content, not the excerpt. Add a matching rule to style.scss with the existing Sass variables. Install the github-pages gem, build the site, build a scratch copy with a long post added to show two different values, open both in a browser, and open a pull request linking 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 _includes/reading-time.html and changes _layouts/post.html, index.html and style.scss. Its description quotes the jekyll build output for the real site and for the scratch copy, the rendered .date line of the short post and of the long one, the front page's list with a reading time under each title, and a screenshot of the long post. No configuration and no post changes.
A reviewer checks the words-per-minute constant, where the line sits on the front page, and whether the excerpt should carry the time as well. After merging, GitHub Pages builds the site with the same Jekyll and Liquid the agent used, so the numbers on the live site match the ones in the pull request's build.
Run it on every Linear issue labelled blog
An automation in the Project that holds the blog takes a linear trigger on linear.issue.labeled with the label blog. Its runs are read-only, so the saved prompt asks for a plan: the run reads the layouts and the config and posts which include it would add, where the line would appear and what the build needs as a comment on the issue. 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 Jekyll blogs sends one request per repository, each with its own resources entry.
The use case this job follows, with its automation and trigger: Turn a Linear label into a PR.
Why run it on Rush?
The arithmetic is a line of Liquid, and the mistakes are in what it counts: rendered HTML instead of text, the excerpt instead of the post, an integer division that rounds a 300-word post down to one minute and a 50-word post down to zero. Those only show in a built site with posts of different lengths, so the agent installs the same gem set GitHub Pages uses in its own sandbox, builds the real site and a scratch copy, reads the generated pages and keeps every command and its output in the run's record.
It also stays inside what the host allows: no plugin, no Gemfile the project chose not to have, no Ruby code, so the site keeps building on GitHub Pages exactly as it does today. Ten blogs on ten Jekyll themes get ten pull requests, each placing the line where that theme prints its date.
Frequently asked questions
Why not a reading-time plugin?
GitHub Pages builds only with the plugins in the github-pages gem, which has no reading-time plugin, and the blog has no Gemfile to add one to. number_of_words and the math filters are built in, so the include works on Pages and on any local jekyll build alike.
Does it count code blocks and image tags?
The include strips HTML before counting, so tags and attributes are not words. Text inside a code block still counts, which is usually right for a technical blog; a post that wants to exclude it can wrap the code in an element the include removes with replace, and the pull request shows how.
Can I change the words per minute?
Yes. It is one assign at the top of _includes/reading-time.html with a comment, set to 200. A blog in a language that reads faster or slower changes that number in one place and both the post layout and the front page follow.
Will the time show on the feed and the sitemap?
No. jekyll-feed builds the feed from each post's content and jekyll-sitemap from its URL, and neither reads the layouts, so the line appears only in the HTML the layouts render. Nothing in _config.yml changes.
More Jekyll jobs
The same job on other stacks
- Add Reading Time to a Pelican Blog (Pelican)
- Add Reading Time to a VitePress Blog (VitePress)
- Add Reading Time to a Wagtail Blog (Wagtail)