What the agent does
The agent reads how posts become pages before it adds a field. In a blog like gatsbyjs/gatsby-starter-blog, package.json depends on gatsby ^5.14.6, gatsby-source-filesystem, gatsby-transformer-remark ^6.14.0 with gatsby-remark-images, gatsby-remark-responsive-iframe and gatsby-remark-prismjs as its plugins, gatsby-plugin-feed for the RSS file and React 18, and package-lock.json resolves Gatsby to 5.16.1 and the transformer to 6.16.0. Posts are Markdown files under content/blog/<slug>/index.md with title, date and an optional description in frontmatter. gatsby-node.js queries allMarkdownRemark sorted by date, creates a page per post from src/templates/blog-post.js with the previous and next post ids in context, adds a slug field in onCreateNode with createFilePath, and declares the Frontmatter type in createSchemaCustomization so a missing field returns null instead of failing the build. The scripts are build, develop, serve, clean and format with Prettier 2.8.8; test prints a reminder to write tests and exits 1.
The two places a reader sees the date are the two places the estimate belongs. src/templates/blog-post.js renders the post title as an h1 and the date in a p under it, then the HTML through dangerouslySetInnerHTML, Bio, and a previous and next navigation; its pageQuery asks markdownRemark for excerpt(pruneLength: 160), html and the formatted date. src/pages/index.js lists every post with the title linked, the date in a small, and the description or excerpt. The transformer already computes timeToRead and wordCount { words } on every MarkdownRemark node, which the agent confirms by reading the installed package's extend-node-type.js in node_modules after npm ci, so no new plugin and no onCreateNode change is needed: the agent adds timeToRead and wordCount { words } to both queries and renders the date and a min read phrase in one line, in the p of the post header and the small of the list item, so style.css, which already styles .blog-post header p and .post-list-item header, needs no change. For a one-minute post the phrase stays singular.
Because the starter has no tests, the build is the check. gatsby build runs every page query against the schema and fails on a field that does not exist, so a typo in timeToRead cannot reach the pull request. The agent runs npm ci, npm run build, then npm run serve and fetches the index and one post from the local server to read the rendered phrase in the HTML, and npm run format so the Prettier configuration in .prettierrc is respected. The RSS feed in gatsby-config.js serialises each post from its own query and is left as it is unless the prompt asks for the estimate in the feed too.
A reader who wants a different speed than the transformer assumes gets it as a follow-up rather than a rewrite: wordCount.words is in the same query, so a createNodeField in gatsby-node.js that divides words by the team's words per minute replaces the transformer's field with one the repository controls. The pull request names that option and shows the generated HTML for the index and a post.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Add reading time to the posts in this Gatsby blog. Read package.json, package-lock.json for the resolved gatsby and gatsby-transformer-remark versions, gatsby-config.js, gatsby-node.js, src/templates/blog-post.js, src/pages/index.js, src/style.css and one file under content/blog first. Run npm ci, then confirm in node_modules/gatsby-transformer-remark that MarkdownRemark nodes expose timeToRead and wordCount. Add timeToRead and wordCount { words } to the page query in blog-post.js and the query in index.js, and render the estimate beside the date in the post header paragraph and in the small element of each list item, singular for one minute. Do not add a plugin, do not change gatsby-config.js or the RSS serializer, and do not change the frontmatter schema. Run npm run build, then npm run serve and fetch the index and one post to read the rendered phrase, and run npm run format. Open a pull request that lists the files, quotes the build summary and the rendered lines, and notes how a team would replace the transformer's estimate with its own words-per-minute field through onCreateNode in gatsby-node.js.",
"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
What comes back is a pull request on its own branch that changes src/templates/blog-post.js and src/pages/index.js: two query fields and one rendered phrase in each. The body quotes the gatsby build summary from the sandbox and the two rendered lines from the served site, and ends with the words-per-minute option so the team can decide whether the transformer's estimate is the one it wants.
The session read names the repository and the pull request. The transcript keeps npm ci, the build with its page count, the serve and the two fetches, and the Prettier run, and GET /o/{org}/p/{project}/sessions/{id}/changes returns the diff per file.
Before merging, a reviewer opens the diff to confirm the only new query fields are timeToRead and wordCount, checks the phrase for the one-minute case, and decides whether the feed should carry the estimate as well, which a follow-up on the same session adds to the serialize function in gatsby-config.js with the build already warm.
Run it on every Gatsby site with posts
A reading-time line is the kind of small, well-specified change that is worth handing off rather than context-switching into. From Claude Code or Codex with Rush connected as an MCP server at https://api.phoenix.so/mcp, ask for a create_session with this prompt and your repository, keep working, and read the pull request later with get_session; wait_for_sessions waits up to 50 seconds per call when you would rather block. The sandbox parks with node_modules and the .cache directory when the turn ends, so a send_session_message asking for the estimate in the RSS feed rebuilds in place.
For several content sites, a script sends one POST /o/{org}/sessions per repository with the repository in resources and a request_id per repository, so a retried call returns the run it already started. A webhook_url on the key receives run.completed, run.failed or run.cancelled for each run the key started, with data.session_url to read for the pull request link.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
A Gatsby change is only real once gatsby build has run the page queries and written the HTML, and the quickest mistake here is to add a plugin for a field the transformer already provides. The agent reads the installed transformer in its own sandbox, confirms the field, and runs the production build and a served fetch, so the pull request shows the phrase in rendered HTML rather than in a screenshot of gatsby develop.
The result is a two-file diff with the build log and the rendered lines attached, and nothing about your laptop's Node version or .cache state in the way. The same request runs against every blog your team maintains, one sandbox and one pull request each, with the template and index read from each repository rather than assumed to match the starter.
Frequently asked questions
Does it add a plugin for reading time?
No. gatsby-transformer-remark at the version the lockfile resolves already exposes timeToRead and wordCount on every MarkdownRemark node, which the agent confirms in node_modules before writing a query. The change is two query fields and two rendered phrases.
Can we use our own words-per-minute figure?
Yes. wordCount.words is in the same query, so a createNodeField in onCreateNode in gatsby-node.js that divides it by your figure gives the repository its own field, and the templates read that instead. The pull request describes this option; ask for it in the prompt or in a follow-up and the agent makes the change.
Will the RSS feed show the reading time?
Not by default. The feed in gatsby-config.js serialises posts from its own query and the prompt leaves it alone, because a feed reader shows its own estimate. A follow-up adds the field to that query and to custom_elements if you want it there.
How is it verified with no test suite?
The build is the test: gatsby build fails on a query field the schema does not have, and the agent then serves the built site and fetches the index and a post to read the phrase in the HTML. Both outputs are quoted in the pull request and kept in the transcript.
More Gatsby jobs
The same job on other stacks
- Add Reading Time to a Hugo Blog (Hugo)
- Add Reading Time to a Jekyll Blog (Jekyll)
- Add Reading Time to a Pelican Blog (Pelican)