What the agent does
The agent starts with what Jekyll offers and why it is not enough here. site.related_posts exists on every page, but Jekyll's documentation says that by default it holds the ten most recent posts, and only a build with the --lsi flag turns it into posts that are actually similar. GitHub Pages builds without that flag and the github-pages gem does not carry the classifier it needs, and in a blog started from barryclark/jekyll-now there is no Gemfile to add one to, because .gitignore excludes it and the README's workflow is gem install github-pages. So a list built from site.related_posts would be a list of recent posts under a misleading heading.
The repository's layouts give the agent the shape. _layouts/post.html prints the title, the content in .entry, then a .date div and the Disqus include; index.html loops site.posts with post.excerpt and a Read More link; _config.yml sets permalink: /:title/, lists jekyll-sitemap and jekyll-feed under gems and has no related_posts setting. The only post, _posts/2014-3-3-Hello-World.md, has layout and title in its front matter and no tags. The agent adds _includes/related-posts.html: it loops site.posts, skips the current one by post.url, and for each of the current page's tags checks post.tags contains tag; a post that shares at least one tag is appended to a related string of URLs separated by a marker, the loop stops at three, and the include renders them as a <ul> of titles with dates, under a Related posts heading that only appears when the list is not empty. With no tags on the page, or no post sharing one, it falls back to the three most recent other posts, labelled More posts, so a blog that never tags still gets a useful block.
The include goes into post.html after the content and before the .date div, and a .related rule joins style.scss next to the .posts and .post rules, reusing $lightGray for a top border and $gray for the dates from _sass/_variables.scss. The agent adds tags: to the Hello World post's front matter with one tag so the first real post has an example, and a line in the README's features list. It does not add site.related_posts anywhere, and the pull request explains why, with the sentence from Jekyll's documentation.
Then it builds as the README says, with the github-pages gem installed in its own sandbox and jekyll build, which brings Jekyll 3.10.0, the version GitHub Pages runs. One post cannot show a related list, so the agent copies the site to a scratch directory, adds six posts with overlapping tags and one with none, builds the copy and reads the generated pages: a tagged post lists the posts sharing its tags and not the others, the untagged post shows the More posts fallback, and no page lists itself. It serves the scratch build and opens two of the pages 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 a related posts section to the posts of this Jekyll blog, which is hosted on GitHub Pages without a Gemfile, so plain Liquid only and no LSI. Read _config.yml, index.html, _layouts/post.html, _layouts/default.html, style.scss, _sass/_variables.scss, _posts, .gitignore and the README first. Add an _includes/related-posts.html that lists up to three other posts sharing at least one tag with the current post, newest first, and falls back to the three most recent other posts when there is no match; never list the current post. Include it in the post layout after the content, add a rule to style.scss using the existing Sass variables, add a tags line to the existing post, and note the feature in the README. Do not use site.related_posts. Install the github-pages gem, build the site, build a scratch copy with several tagged posts and one untagged post to show both the match and the fallback, open two pages 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 adds _includes/related-posts.html and changes _layouts/post.html, style.scss, _posts/2014-3-3-Hello-World.md and the README. Its description quotes the jekyll build output for the real site and the scratch copy, the rendered related list from a tagged post and the fallback list from the untagged one, a table of which scratch posts matched which, and a screenshot. _config.yml does not change.
A reviewer checks the heading text, the limit of three, whether the fallback should be shown at all on an untagged blog, and the tag added to the first post. After merging, every post with tags gets its matches on the next GitHub Pages build, and adding tags to older posts is the only ongoing work.
Run it on every Jekyll blog in the terminal
A developer with jekyll serve running sends this body from their own machine with the blog in resources, keeps writing, and opens the pull request from the console when the webhook on their API key reports the run finished. A team that runs several blogs sends one request per repository, each carrying a request_id that is a UUID v5 of the repository's full name, so running the script twice returns the runs already started rather than opening a second pull request on each.
Each run reads its own blog: one whose posts already carry categories instead of tags gets the include written against that field, and one with a Gemfile and a --lsi build step gets a note that site.related_posts would work there and the choice left to the reviewer.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
The tempting one-line answer, site.related_posts, is wrong on this host, and the right answer is a loop whose edge cases only show with real posts: a post that lists itself, a tag match that counts the same post twice, a fallback that appears when it should not. The agent builds a scratch copy with enough tagged and untagged posts to hit each case in its own sandbox, with the same gem set GitHub Pages uses, reads the generated HTML and keeps every command and its output in the run's record, so the pull request shows the lists rather than a template that ought to produce them.
It also respects how the blog is run, with no plugin, no Gemfile and no change to the build, so the site keeps deploying from a push exactly as before. Ten blogs get ten pull requests, each matched to its own front matter and layouts.
Frequently asked questions
Why not site.related_posts?
Because without the --lsi flag Jekyll fills it with the ten most recent posts, which is what its documentation says, and GitHub Pages never passes that flag. A list of recent posts under a Related heading misleads readers; the tag match is cheap and says what it means.
My posts have no tags yet. What happens?
Each post shows the More posts fallback, the three most recent other posts, so nothing looks broken. As you add tags: to front matter the matches take over post by post. The pull request tags the first post as an example.
Does this slow down the build?
The include loops over site.posts once per post, so the cost grows with the square of the post count, which is fine for a personal blog of hundreds of posts. The pull request notes that a blog with thousands should prefer a per-tag page over a per-post list.
Can it match on categories instead?
Yes. The include compares page.tags with post.tags, and changing both to categories is the only edit. A blog that uses both can check either field, and the agent writes it for whichever the existing posts already use.