Skip to main content
This example builds pr-reviewer: an agent that reviews a pull request when it is opened or updated, and answers when someone mentions @pr-reviewer in the pull request’s conversation. Each pull request gets one session, so a later push or question is handled with the earlier review in context. GitHub posts its webhooks straight to a paddock trigger; you run no server. The examples use the repository acme/web; replace it with yours.

1. The template

The template describes the reviewer: Claude Code on claude-opus, and a system prompt that fixes what it may do and how it must post. The agent reaches GitHub only through the GitHub MCP server, which the agent gets in the next step with your token.
agents/pr-reviewer/template.yaml
Claude Code follows the review content of a system prompt readily, but output rules, such as the review event and the marker line, hold best when they come first as a contract and are repeated in each message. The rules below repeat them.

2. The agent

Create the template and an agent from it, then give the agent the GitHub MCP server with a GitHub token that can read the repository and write reviews and comments. The token is the agent’s own configuration, so no template version ever carries it.
Keep GITHUB_TOKEN in your environment, never in code. In the console, the agent’s Capabilities tab adds the same MCP server. After the agent’s first turn, its harness status shows the github server as loaded.

3. The trigger

The trigger checks GitHub’s signature with a secret you generate (for example openssl rand -hex 32), drops GitHub’s redeliveries by their X-GitHub-Delivery header, and has two rules:
  • review: a pull request opened, updated, reopened, or marked ready, and not a draft.
  • mention: a new comment on a pull request that mentions @pr-reviewer. It skips the agent’s own comments, which carry the <!-- pr-reviewer --> marker, and comments by bots, so the agent never triggers itself.
Both rules render the same session key for a pull request, because GitHub numbers a pull request as an issue: a mention lands in the session of that pull request’s review.
Before you connect GitHub, run the rules on sample events with triggers.test, or in the console’s rule editor, whose test panel shows each rule’s match, session key, and message as you type. A synchronize event should match review, a draft or a ping should be filtered, and a comment carrying the marker should not match mention.

4. The GitHub webhook

In the repository’s Settings → Webhooks → Add webhook: GitHub sends a ping when you save the webhook. It shows in the trigger’s deliveries with both rules filtered: its x-github-event is ping, and && stops before reading fields a ping lacks.

What happens

Find a pull request’s conversation with sessions.list({ metadata: { triggerKey: "acme/web#42" } }), or in the console’s Sessions page.

Notes from running it

  • Posting as yourself. With a personal token, reviews and comments are posted as your own account. GitHub does not let an author approve or request changes on their own pull request, which is why the prompt allows only COMMENT reviews. The marker line is how the rules tell the agent’s comments from yours. A bot account’s token avoids both limits.
  • Iterating on the prompt. An agent stays on the template version it was created from, so a new template version does not change this agent’s prompt; it only records the prompt for agents you create from that version later. To change the prompt of the running agent, set the agent’s own system prompt (agent.SystemPrompt.Set in Go, agent.system_prompt.set in Python, agent.systemPrompt.set in TypeScript; see Configuration). Only sessions created afterwards use it: a pull request’s existing session keeps the prompt it started with, so delete that session, or wait for the next pull request, to see the change.
  • Tools in the sandbox. The agent reaches GitHub only through the MCP server. Say so in the prompt, so it does not reach for a CLI the sandbox does not have.