What the agent does
The agent starts from the issue and the repository in its own cloud sandbox and reads how posts are built before it changes anything. In a site like gatsbyjs/gatsby-starter-blog (Gatsby ^5.14.6, React 18, npm with a package-lock.json), gatsby-config.js sources Markdown from content/blog through gatsby-source-filesystem and gatsby-transformer-remark, with gatsby-remark-images, gatsby-remark-responsive-iframe and gatsby-remark-prismjs as the remark plugins. gatsby-node.js creates one page per post with src/templates/blog-post.js, passing id, previousPostId and nextPostId in context, and its createSchemaCustomization declares Frontmatter as title, description and date so queries stay valid when a field is missing. The template's BlogPostBySlug query fetches html, excerpt(pruneLength: 160) and the frontmatter, and renders the body with dangerouslySetInnerHTML inside an <article>.
Then it checks what the content gives it to work with. content/blog/hello-world/index.md and content/blog/new-beginnings/index.md use ## and ### headings; content/blog/my-second-post/index.md has none. gatsby-transformer-remark already exposes a tableOfContents field on every MarkdownRemark node, built from those headings, but its links point at heading anchors that nothing in this config creates. So the plan has two parts: give headings ids, and render the field.
The change lands in three files. In gatsby-config.js the agent adds gatsby-remark-autolink-headers to the gatsby-transformer-remark plugin list ahead of gatsby-remark-prismjs, the order that plugin's own documentation asks for, so every heading gets an id and an anchor link. In src/templates/blog-post.js the query gains tableOfContents(maxDepth: 3) and the component renders it in a <nav aria-label="Table of contents"> between the header and the body, only when the string is non-empty, so a post like my-second-post shows nothing extra. createSchemaCustomization in gatsby-node.js gains an optional toc: Boolean frontmatter field, so an author can switch the list off per post without the query failing on posts that never set it, and src/style.css gets a few lines so the list sits with the existing .blog-post styles.
The repository's test script only prints a reminder to write tests and exits non-zero, so the proof is the build. The agent runs npm ci, then npm run build, serves the output with npm run serve, and reads the HTML of /hello-world/ and /my-second-post/ to confirm the first has a navigation list whose hrefs match heading ids on the same page and the second has no list. It runs npm run format so Prettier ^2.8.8 leaves the diff clean, and pushes once the build is green.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "A Linear issue labeled agent says: \"Add a table of contents at the top of each blog post, generated from the post's headings, with links that jump to each section. Skip posts with no headings. Let a post opt out with toc: false in its frontmatter.\" Before changing anything, read gatsby-config.js, gatsby-node.js and src/templates/blog-post.js to see how Markdown posts are transformed and rendered and which remark plugins are configured. Use the tableOfContents field gatsby-transformer-remark provides, add the remark plugin that gives headings ids and anchors in the position its documentation requires relative to the prism plugin, render the list in a labelled nav only when it is non-empty, and declare the optional toc frontmatter field in the schema customization so queries stay valid. Keep the existing post layout, previous and next links and SEO head. Run the production build, serve it and check the generated HTML of a post with headings and a post without, then open a pull request that links back to the issue and describes what was already available and what was added.",
"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 with a diff over gatsby-config.js, gatsby-node.js, src/templates/blog-post.js, src/style.css, package.json and package-lock.json. Its description says what the agent found, that the tableOfContents field already existed but nothing gave headings ids, and names the plugin it added and where in the remark plugin order it sits.
The transcript is the proof: the npm ci and npm run build output, the served pages, and the HTML the agent read back showing the <nav> with anchor links on a post with headings and no <nav> on one without. If the repository runs a build on pull requests, that check runs there too.
Before merging, a reviewer checks that the anchor ids match the links on long posts with duplicate heading text, that maxDepth matches what the issue wants, that a post with toc: false renders no list, and that the new nav reads correctly with a screen reader and does not shift the existing header layout.
Run it on every Linear issue labelled agent
In the console, an automation with a linear trigger on linear.issue.labeled and the label agent starts one run per labelled issue in the Project's repository. The trigger adds the issue's text after the saved prompt, so each issue carries its own wording, such as the heading depth or the opt-out field name. Changes made by an app integration never fire it, and the automation's max_runs_per_hour bounds how many runs a burst of labelling can start.
From your own server, the same job is one POST /o/{org}/sessions per issue, with the repository in resources and the issue's https://linear.app/<workspace>/issue/<ID> URL beside it so Rush reads the issue through your Linear connection. A webhook_url on the API key receives run.completed or run.failed for every run that key starts, with the session_url to read the pull request link from.
The use case this job follows, with its automation and trigger: Turn a Linear label into a PR.
Why run it on Rush?
A Gatsby change is only real once gatsby build has run the GraphQL queries and written the HTML, and a remark plugin in the wrong order fails quietly rather than loudly. In a Rush sandbox the agent runs the full production build, serves it and reads the generated pages back, so the pull request arrives with a green build and the exact HTML it produced, instead of a config change that looked right in the editor.
A label in Linear becomes a reviewable pull request whose reasoning is on the record. The transcript shows the agent reading the existing config and template before it edits them and every build with its output, and several labelled issues can run at once, each in its own sandbox on its own branch, each linking back to the issue it answers.
Frequently asked questions
Does it work with MDX posts too?
The starter uses gatsby-transformer-remark and plain Markdown, which is what this page describes. A site on gatsby-plugin-mdx exposes a similar tableOfContents field with a different shape, and the agent reads the config first and adapts; the pull request says which path it took.
What if two headings have the same text?
The autolink plugin gives each heading a unique id by appending a suffix to repeats, and the tableOfContents field uses those same ids, so the links stay distinct. The reviewer can confirm on a post with repeated section titles.
Can I hide the list on short posts?
Posts with no headings render no list at all, and any post can set toc: false in its frontmatter. The field is declared in createSchemaCustomization, so posts that never set it do not break the query.
There are no tests in this repository. What is the check?
The production build and the pages it produces. The agent runs npm run build, serves the result and reads the HTML of a post with headings and one without, and those outputs are in the transcript for the reviewer to see.