GitHub | Agent SDK | Cursor Docs
Skip to main content Command Palette Search for a command to run... Get Started Welcome Quickstart Changelog Release Notes Agent Overview Agents Window Projects Agent Review Planning Prompting Voice Chat Debugging Design Mode Customize Overview Plugins Rules Skills Subagents Hooks MCP Cloud Agents Overview Setup Builds Apps Best Practices Choose Where Cloud Agents Run Automations Bugbot Security Review Vulnerability Remediation PR Routing & Approval Rollouts Mobile Settings API Origin Overview Create a repository Mirror GitHub Clone, Push & Pull CloneKit in CI Pull requests Code Tours Browse & Search Agents and Automations Settings Integrations Slack Microsoft Teams Jira Linear Notion GitHub GitLab Azure DevOps Bitbucket JetBrains Xcode Tailscale Deeplinks SDK TypeScript Python Bridge Changelog Agent SDK GitHub Slack Webhooks Cursor Automations OpenTelemetry GitLab Bitbucket PagerDuty CLI Overview Installation Capabilities Changelog Shell Mode ACP Headless / CI Teams & Enterprise Agent SDK GitHub agents A GitHub agent wakes from repo events, reads the latest PR and CI state, then writes back reviews, comments, checks, or pushes.
Every wake for the same pull request resumes one session, so the open, later comments, and CI results share one conversation. Connect GitHub in Cursor for the repos you care about (Settings or cursor.com/dashboard ), then sign the host in with agent-sdk login . cursorAccount reuses that connection for events and API calls, so you don't need a public webhook URL, a GitHub App, or a personal access token. For a complete reviewer or issue triager, start from the review and triage templates .
Review a pull request When someone opens a pull request or marks it ready for review, the agent starts a turn, reads the change, and posts its verdict as a review. // bot/channels/github.ts import { defaultGitHubAuth, githubChannel } from "@grok/agent-sdk/channels/github"; export default githubChannel({ // Skip the agent's own comments so replies don't re-trigger it. botName: "my-agent", cursorAccount: { repos: ["acme/checkout"] }, onPullRequest: (ctx, pr) => { if (pr.draft) { return null; } if (pr.action !== "opened" && pr.action !== "ready_for_review") { return null; } // `auth` starts a model turn running as the sender. return { auth: defaultGitHubAuth(ctx) }; }, }); // bot/tools/submit_review.ts import { parseGitHubPrContinuationKey } from "@grok/agent-sdk/channels/github"; import { defineTool } from "@grok/agent-sdk/tools"; import { z } from "zod"; export default defineTool({ description: "Post the review decision on this session's pull request.
Call once.", inputSchema: z.object({ verdict: z.enum(["approve", "request_changes"]), summary: z .string() .describe("One or two sentences explaining the verdict."), }), async execute({ verdict, summary }, ctx) { if (ctx.session.purpose === "eval") { return { posted: false, reason: "eval" }; } const ref = parseGitHubPrContinuationKey(ctx.session.continuationKey ?? ""); if (ref === undefined) { throw new Error("submit_review requires a GitHub pull request session"); } let event: "APPROVE" | "REQUEST_CHANGES" = "REQUEST_CHANGES"; if (verdict === "approve") { event = "APPROVE"; } const octokit = await ctx.host.github.getOctokit(); await octokit.rest.pulls.createReview({ owner: ref.owner, repo: ref.repo, pull_number: ref.number, event, body: summary, }); return { posted: true, pr: `${ref.owner}/${ref.repo}#${ref.number}` }; }, }); The event only tells you that the pull request changed.
Read the title, files, and checks during the turn. Answer a mention onComment replaces the default @botName gate. Return a turn when the comment is for this agent, then post the reply from a tool. onComment: (ctx, comment) => { if (!comment.body.includes("@my-agent")) { return null; } return { auth: defaultGitHubAuth(ctx) }; }, // bot/tools/reply.ts import { parseGitHubPrContinuationKey } from "@grok/agent-sdk/channels/github"; import { defineTool } from "@grok/agent-sdk/tools"; import { z } from "zod"; export default defineTool({ description: "Post a comment on this session's pull request.", inputSchema: z.object({ body: z.string().describe("Markdown to post on the PR timeline."), }), async execute({ body }, ctx) { if (ctx.session.purpose === "eval") { return { posted: false, reason: "eval" }; } const ref = parseGitHubPrContinuationKey(ctx.session.continuationKey ??
""); if (ref === undefined) { throw new Error("reply requires a GitHub pull request session"); } const octokit = await ctx.host.github.getOctokit(); await octokit.rest.issues.createComment({ owner: ref.owner, repo: ref.repo, issue_number: ref.number, body, }); return { posted: true }; }, }); The tool reads the pull request from the session, so the model never picks where the comment goes. Triage a failing check When CI fails, this hook labels the pull request with host code and no model turn.
Return { auth: defaultGitHubAuth(ctx) } instead when the agent should read the logs and decide what to do. onCheckSuite: (ctx, suite) => { if (suite.conclusion !== "failure") { return null; } // `task` runs host code instead of a model turn. return { task: () => labelFailure(ctx, suite) }; }, async function labelFailure(ctx, suite) { const pr = suite.pullRequests[0]; if (pr === undefined) { return; } const octokit = await ctx.github.getOctokit(); await octokit.rest.issues.addLabels({ owner: ctx.repository.owner, repo: ctx.repository.name, issue_number: pr.number, labels: ["ci-failed"], }); } Events Declare a hook for each event that should wake the agent: onPullRequest , onComment , onIssue , onCheckSuite , onCheckRun , onWorkflowRun , onStatus , and the catch-all onEvent .
Each hook returns { auth } , { task } , or null , as handler results describes. Choose watched repositories The examples above list their repositories with cursorAccount: { repos: [...] } , and every repository in one channel must share one GitHub owner. To keep the list out of source, set cursorAccount: true and pass --repo to agent-sdk serve . A hosted deployment watches the repositories you pass to agent-sdk deploy in both cases. agent-sdk serve --dir . --cursor-events \ --repo acme/checkout --repo acme/payments agent-sdk deploy --dir . \ --cursor-events-repo acme/checkout \ --cursor-events-repo acme/payments Each deploy replaces the previous list, so pass every repository each time.
Use agent-sdk deployment update to change the list without redeploying. Call GitHub from deterministic code via ctx With cursorAccount , hooks ( ctx.github.getOctokit() ) and tools ( ctx.host.github.getOctokit() ) share one credential. Hooks can also use ctx.thread.post() , ctx.repository , and ctx.conversation . This hook reads the pull request, skips a draft, and posts before the model turn: onPullRequest: async (ctx, pr) => { if (pr.action !== "opened") { return null; } const octokit = await ctx.github.getOctokit(); const { data } = await octokit.rest.pulls.get({ owner: ctx.repository.owner, repo: ctx.repository.name, pull_number: pr.number, }); if (data.draft) { return null; } await ctx.thread.post(`Reviewing ${pr.url}`); return { auth: defaultGitHubAuth(ctx) }; }, Batch events GitHub can send many events for one pull request within a few seconds.
Coalesce them per pull request: const pending = new Map(); function enqueue(pr, flush) { const key = `${pr.owner}/${pr.repo}#${pr.number}`; const existing = pending.get(key); if (existing !== undefined) { clearTimeout(existing); } pending.set( key, setTimeout(() => { pending.delete(key); flush(); }, 3_000) ); } Persist that buffer across restarts, and drop it when the pull request closes. Test with replay agent-sdk github replay reads a pull request you can access and posts GitHub-shaped events to your channel. agent-sdk github replay https://github.com/acme/checkout/pull/42 --dir . --action opened # Replay everything the channel listens for, with CI failing agent-sdk github replay acme/checkout#42 --dir . --events '*' --conclusion failure # Save the payloads as fix
The rest of this page is on the live site.