@cursor/july 0.1.41 → 0.1.43

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (195) hide show
  1. package/AGENTS.md +10 -3
  2. package/dist/bin/agent-serve.js +3 -1
  3. package/dist/channels/github/api.d.ts +5 -0
  4. package/dist/channels/github/api.d.ts.map +1 -1
  5. package/dist/channels/github/api.js +18 -0
  6. package/dist/channels/github/defaults.d.ts +4 -5
  7. package/dist/channels/github/defaults.d.ts.map +1 -1
  8. package/dist/channels/github/defaults.js +27 -1
  9. package/dist/channels/github/github-channel.d.ts.map +1 -1
  10. package/dist/channels/github/github-channel.js +28 -5
  11. package/dist/channels/github/index.d.ts +1 -0
  12. package/dist/channels/github/index.d.ts.map +1 -1
  13. package/dist/channels/github/index.js +1 -0
  14. package/dist/channels/github/progress.d.ts +54 -0
  15. package/dist/channels/github/progress.d.ts.map +1 -0
  16. package/dist/channels/github/progress.js +168 -0
  17. package/dist/channels/github/state.d.ts +2 -0
  18. package/dist/channels/github/state.d.ts.map +1 -1
  19. package/dist/channels/github/state.js +1 -1
  20. package/dist/channels/github/types.d.ts +8 -4
  21. package/dist/channels/github/types.d.ts.map +1 -1
  22. package/dist/channels/slack/slack-channel.d.ts +4 -0
  23. package/dist/channels/slack/slack-channel.d.ts.map +1 -1
  24. package/dist/channels/slack/slack-channel.js +4 -0
  25. package/dist/docs/404.html +2 -2
  26. package/dist/docs/ab.html +4 -4
  27. package/dist/docs/assets/{app.mIw24pb1.js → app.DsTLo2j1.js} +1 -1
  28. package/dist/docs/assets/chunks/@localSearchIndexroot.BZx4pmZL.js +1 -0
  29. package/dist/docs/assets/chunks/{VPLocalSearchBox.hOzpPwrG.js → VPLocalSearchBox.DoVfutcV.js} +1 -1
  30. package/dist/docs/assets/chunks/{theme.BtFhUYmh.js → theme.DtuVtKkc.js} +2 -2
  31. package/dist/docs/assets/{deployment.md.BHVjVqRa.js → deployment.md.Cdp4rTE4.js} +1 -1
  32. package/dist/docs/assets/{guides_github.md.R2QlpR75.js → guides_github.md.DSg0j9qj.js} +29 -3
  33. package/dist/docs/assets/{guides_github.md.R2QlpR75.lean.js → guides_github.md.DSg0j9qj.lean.js} +1 -1
  34. package/dist/docs/assets/guides_opentelemetry.md.DmyUwC5R.js +20 -0
  35. package/dist/docs/assets/guides_opentelemetry.md.DmyUwC5R.lean.js +1 -0
  36. package/dist/docs/assets/{index.md.BKpbkCa6.js → index.md.CMc5FP7E.js} +2 -1
  37. package/dist/docs/assets/{reference_channels.md.BIabFUAI.js → reference_channels.md.MN8iDy8V.js} +1 -1
  38. package/dist/docs/assets/reference_hooks.md.4cbRRIIu.js +14 -0
  39. package/dist/docs/assets/{reference_hooks.md.BHeG-vjK.lean.js → reference_hooks.md.4cbRRIIu.lean.js} +1 -1
  40. package/dist/docs/assets/{reference_project-layout.md._XdeMahr.js → reference_project-layout.md.D3MdHM2z.js} +2 -1
  41. package/dist/docs/assets/templates_triage.md.CConZt1z.js +11 -0
  42. package/dist/docs/assets/templates_triage.md.CConZt1z.lean.js +1 -0
  43. package/dist/docs/building-with-agents.html +5 -5
  44. package/dist/docs/concepts.html +5 -5
  45. package/dist/docs/deployment.html +6 -6
  46. package/dist/docs/evals.html +4 -4
  47. package/dist/docs/example-agents/approval-buddy.html +4 -4
  48. package/dist/docs/example-agents/benny.html +4 -4
  49. package/dist/docs/example-agents/bugbot.html +4 -4
  50. package/dist/docs/example-agents/codebase-wiki.html +4 -4
  51. package/dist/docs/example-agents/codeowners-review.html +4 -4
  52. package/dist/docs/example-agents/concierge.html +4 -4
  53. package/dist/docs/example-agents/fsd.html +4 -4
  54. package/dist/docs/example-agents/index.html +5 -5
  55. package/dist/docs/example-agents/knowledge-base.html +4 -4
  56. package/dist/docs/example-agents/oncall.html +4 -4
  57. package/dist/docs/example-agents/security-reviewer.html +4 -4
  58. package/dist/docs/example-agents/slack-agent.html +4 -4
  59. package/dist/docs/example-agents/weather-agent.html +4 -4
  60. package/dist/docs/guides/agent-to-agent.html +4 -4
  61. package/dist/docs/guides/cloud-runtime.html +5 -5
  62. package/dist/docs/guides/github.html +33 -7
  63. package/dist/docs/guides/human-in-the-loop.html +4 -4
  64. package/dist/docs/guides/mcp-oauth.html +4 -4
  65. package/dist/docs/guides/opentelemetry.html +44 -0
  66. package/dist/docs/guides/slack.html +4 -4
  67. package/dist/docs/guides/webhooks.html +4 -4
  68. package/dist/docs/hashmap.json +1 -1
  69. package/dist/docs/hillclimbing.html +4 -4
  70. package/dist/docs/index.html +7 -6
  71. package/dist/docs/quickstart.html +4 -4
  72. package/dist/docs/reference/agent-config.html +4 -4
  73. package/dist/docs/reference/artifacts.html +4 -4
  74. package/dist/docs/reference/channels.html +6 -6
  75. package/dist/docs/reference/cli.html +4 -4
  76. package/dist/docs/reference/connections.html +4 -4
  77. package/dist/docs/reference/hooks.html +9 -7
  78. package/dist/docs/reference/http-api.html +4 -4
  79. package/dist/docs/reference/instructions.html +4 -4
  80. package/dist/docs/reference/playground.html +4 -4
  81. package/dist/docs/reference/project-layout.html +7 -6
  82. package/dist/docs/reference/prompt.html +4 -4
  83. package/dist/docs/reference/schedules.html +4 -4
  84. package/dist/docs/reference/sessions.html +4 -4
  85. package/dist/docs/reference/skills.html +4 -4
  86. package/dist/docs/reference/subagents.html +4 -4
  87. package/dist/docs/reference/tools.html +4 -4
  88. package/dist/docs/scaffolding-agents.html +4 -4
  89. package/dist/docs/storage.html +4 -4
  90. package/dist/docs/templates/triage.html +35 -0
  91. package/dist/docs/troubleshooting.html +4 -4
  92. package/dist/hooks.d.ts +3 -1
  93. package/dist/hooks.d.ts.map +1 -1
  94. package/dist/hooks.js +3 -1
  95. package/dist/index.d.ts +2 -0
  96. package/dist/index.d.ts.map +1 -1
  97. package/dist/index.js +1 -0
  98. package/dist/internal/cli-ax.d.ts +1 -0
  99. package/dist/internal/cli-ax.d.ts.map +1 -1
  100. package/dist/internal/cli-ax.js +18 -3
  101. package/dist/internal/discovery.d.ts.map +1 -1
  102. package/dist/internal/discovery.js +36 -4
  103. package/dist/internal/distribution.d.ts.map +1 -1
  104. package/dist/internal/distribution.js +1 -0
  105. package/dist/internal/init-project.d.ts +24 -0
  106. package/dist/internal/init-project.d.ts.map +1 -1
  107. package/dist/internal/init-project.js +126 -7
  108. package/dist/internal/otel/attrs.d.ts +7 -0
  109. package/dist/internal/otel/attrs.d.ts.map +1 -0
  110. package/dist/internal/otel/attrs.js +13 -0
  111. package/dist/internal/otel/collector.d.ts +16 -0
  112. package/dist/internal/otel/collector.d.ts.map +1 -0
  113. package/dist/internal/otel/collector.js +564 -0
  114. package/dist/internal/otel/config.d.ts +42 -0
  115. package/dist/internal/otel/config.d.ts.map +1 -0
  116. package/dist/internal/otel/config.js +236 -0
  117. package/dist/internal/otel/http.d.ts +11 -0
  118. package/dist/internal/otel/http.d.ts.map +1 -0
  119. package/dist/internal/otel/http.js +97 -0
  120. package/dist/internal/otel/runtime.d.ts +21 -0
  121. package/dist/internal/otel/runtime.d.ts.map +1 -0
  122. package/dist/internal/otel/runtime.js +188 -0
  123. package/dist/internal/server.d.ts.map +1 -1
  124. package/dist/internal/server.js +25 -1
  125. package/dist/internal/session-engine.d.ts +10 -1
  126. package/dist/internal/session-engine.d.ts.map +1 -1
  127. package/dist/internal/session-engine.js +36 -2
  128. package/dist/memory.d.ts +4 -0
  129. package/dist/memory.d.ts.map +1 -1
  130. package/dist/memory.js +4 -0
  131. package/dist/otel.d.ts +88 -0
  132. package/dist/otel.d.ts.map +1 -0
  133. package/dist/otel.js +64 -0
  134. package/dist/playground/assets/{index-B3HBneZZ.js → index-D-DIYQzw.js} +31 -31
  135. package/dist/playground/assets/index-DQTH622f.css +1 -0
  136. package/dist/playground/index.html +2 -2
  137. package/dist/types.d.ts +31 -4
  138. package/dist/types.d.ts.map +1 -1
  139. package/docs/README.md +3 -0
  140. package/docs/deployment.md +2 -1
  141. package/docs/guides/github.md +79 -6
  142. package/docs/guides/opentelemetry.md +184 -0
  143. package/docs/reference/channels.md +3 -1
  144. package/docs/reference/hooks.md +25 -5
  145. package/docs/reference/project-layout.md +2 -0
  146. package/docs/templates/triage.md +147 -0
  147. package/package.json +23 -1
  148. package/skills/create-agent/SKILL.md +2 -2
  149. package/skills/debug/SKILL.md +4 -0
  150. package/skills/framework-map/SKILL.md +2 -0
  151. package/skills/otel/SKILL.md +80 -0
  152. package/src/bin/agent-serve.ts +3 -1
  153. package/src/channels/github/api.ts +22 -0
  154. package/src/channels/github/defaults.ts +27 -6
  155. package/src/channels/github/github-channel.ts +27 -1
  156. package/src/channels/github/index.ts +1 -0
  157. package/src/channels/github/progress.ts +243 -0
  158. package/src/channels/github/state.ts +3 -0
  159. package/src/channels/github/types.ts +8 -4
  160. package/src/channels/slack/slack-channel.ts +4 -0
  161. package/src/hooks.ts +3 -1
  162. package/src/index.ts +6 -0
  163. package/src/internal/cli-ax.ts +19 -1
  164. package/src/internal/discovery.ts +59 -4
  165. package/src/internal/distribution.ts +1 -0
  166. package/src/internal/init-project.ts +150 -7
  167. package/src/internal/otel/attrs.ts +18 -0
  168. package/src/internal/otel/collector.ts +796 -0
  169. package/src/internal/otel/config.ts +307 -0
  170. package/src/internal/otel/http.ts +126 -0
  171. package/src/internal/otel/runtime.ts +271 -0
  172. package/src/internal/server.ts +38 -1
  173. package/src/internal/session-engine.ts +52 -0
  174. package/src/memory.ts +4 -0
  175. package/src/otel.ts +155 -0
  176. package/src/types.ts +29 -4
  177. package/templates/triage/README.md +48 -0
  178. package/templates/triage/agent/agent.ts +14 -0
  179. package/templates/triage/agent/channels/intake.ts +20 -0
  180. package/templates/triage/agent/channels/slack.ts +3 -0
  181. package/templates/triage/agent/hooks/memory.ts +3 -0
  182. package/templates/triage/agent/instructions.md +27 -0
  183. package/templates/triage/agent/skills/triage-rubric.md +43 -0
  184. package/templates/triage/agent/tools/record_triage.ts +23 -0
  185. package/templates/triage/evals/evals.config.ts +5 -0
  186. package/templates/triage/evals/triage.eval.ts +43 -0
  187. package/templates/triage/package.json +18 -0
  188. package/templates/triage/tsconfig.json +12 -0
  189. package/dist/docs/assets/chunks/@localSearchIndexroot.BA7V8dEJ.js +0 -1
  190. package/dist/docs/assets/reference_hooks.md.BHeG-vjK.js +0 -12
  191. package/dist/playground/assets/index-Bqk9nplh.css +0 -1
  192. /package/dist/docs/assets/{deployment.md.BHVjVqRa.lean.js → deployment.md.Cdp4rTE4.lean.js} +0 -0
  193. /package/dist/docs/assets/{index.md.BKpbkCa6.lean.js → index.md.CMc5FP7E.lean.js} +0 -0
  194. /package/dist/docs/assets/{reference_channels.md.BIabFUAI.lean.js → reference_channels.md.MN8iDy8V.lean.js} +0 -0
  195. /package/dist/docs/assets/{reference_project-layout.md._XdeMahr.lean.js → reference_project-layout.md.D3MdHM2z.lean.js} +0 -0
package/dist/docs/guides/github.html CHANGED
@@ -9,23 +9,23 @@
9
9
  <link rel="preload stylesheet" href="/docs/assets/style.CK3hwt6q.css" as="style">
10
10
  <link rel="preload stylesheet" href="/docs/vp-icons.css" as="style">
11
11
 
12
- <script type="module" src="/docs/assets/app.mIw24pb1.js"></script>
12
+ <script type="module" src="/docs/assets/app.DsTLo2j1.js"></script>
13
13
  <link rel="preload" href="/docs/assets/inter-roman-latin.Di8DUHzh.woff2" as="font" type="font/woff2" crossorigin="">
14
- <link rel="modulepreload" href="/docs/assets/chunks/theme.BtFhUYmh.js">
14
+ <link rel="modulepreload" href="/docs/assets/chunks/theme.DtuVtKkc.js">
15
15
  <link rel="modulepreload" href="/docs/assets/chunks/framework.CAZyNGu9.js">
16
- <link rel="modulepreload" href="/docs/assets/guides_github.md.R2QlpR75.lean.js">
16
+ <link rel="modulepreload" href="/docs/assets/guides_github.md.DSg0j9qj.lean.js">
17
17
  <script id="check-dark-mode">(()=>{const e=localStorage.getItem("vitepress-theme-appearance")||"auto",a=window.matchMedia("(prefers-color-scheme: dark)").matches;(!e||e==="auto"?a:e==="dark")&&document.documentElement.classList.add("dark")})();</script>
18
18
  <script id="check-mac-os">document.documentElement.classList.toggle("mac",/Mac|iPhone|iPod|iPad/i.test(navigator.platform));</script>
19
19
  </head>
20
20
  <body>
21
- <div id="app"><div class="Layout" data-v-41df81ff><!--[--><!--]--><!--[--><span tabindex="-1" data-v-c792f8ce></span><a href="#VPContent" class="VPSkipLink visually-hidden" data-v-c792f8ce>Skip to content</a><!--]--><!----><header class="VPNav" data-v-41df81ff data-v-ecf0170c><div class="VPNavBar" data-v-ecf0170c data-v-74fc79fd><div class="wrapper" data-v-74fc79fd><div class="container" data-v-74fc79fd><div class="title" data-v-74fc79fd><div class="VPNavBarTitle has-sidebar" data-v-74fc79fd data-v-38e78292><a class="title" href="/docs/" data-v-38e78292><!--[--><!--]--><!----><span data-v-38e78292>Agent SDK</span><!--[--><!--]--></a></div></div><div class="content" data-v-74fc79fd><div class="content-body" data-v-74fc79fd><!--[--><!--]--><div class="VPNavBarSearch search" data-v-74fc79fd><!--[--><!----><div id="local-search"><button type="button" class="DocSearch DocSearch-Button" aria-label="Search"><span class="DocSearch-Button-Container"><span class="vp-icon DocSearch-Search-Icon"></span><span class="DocSearch-Button-Placeholder">Search</span></span><span class="DocSearch-Button-Keys"><kbd class="DocSearch-Button-Key"></kbd><kbd class="DocSearch-Button-Key">K</kbd></span></button></div><!--]--></div><nav aria-labelledby="main-nav-aria-label" class="VPNavBarMenu menu" data-v-74fc79fd data-v-6bcb02d4><span id="main-nav-aria-label" class="visually-hidden" data-v-6bcb02d4> Main Navigation </span><!--[--><!--[--><a class="VPLink link VPNavBarMenuLink" href="/docs/quickstart.html" tabindex="0" data-v-6bcb02d4 data-v-40a52867><!--[--><span data-v-40a52867>Quickstart</span><!--]--></a><!--]--><!--[--><a class="VPLink link VPNavBarMenuLink" href="/docs/guides/webhooks.html" tabindex="0" data-v-6bcb02d4 data-v-40a52867><!--[--><span data-v-40a52867>Guides</span><!--]--></a><!--]--><!--[--><a class="VPLink link VPNavBarMenuLink" href="/docs/example-agents/" tabindex="0" data-v-6bcb02d4 data-v-40a52867><!--[--><span data-v-40a52867>Examples</span><!--]--></a><!--]--><!--[--><a class="VPLink link VPNavBarMenuLink" href="/docs/reference/project-layout.html" tabindex="0" data-v-6bcb02d4 data-v-40a52867><!--[--><span data-v-40a52867>Reference</span><!--]--></a><!--]--><!--]--></nav><!----><div class="VPNavBarAppearance appearance" data-v-74fc79fd data-v-106703d3><button class="VPSwitch VPSwitchAppearance" type="button" role="switch" title aria-checked="false" data-v-106703d3 data-v-2881b93b data-v-5009fed8><span class="check" data-v-5009fed8><span class="icon" data-v-5009fed8><!--[--><span class="vpi-sun sun" data-v-2881b93b></span><span class="vpi-moon moon" data-v-2881b93b></span><!--]--></span></span></button></div><!----><div class="VPFlyout VPNavBarExtra extra" data-v-74fc79fd data-v-53eccc99 data-v-f6ef69a3><button type="button" class="button" aria-haspopup="true" aria-expanded="false" aria-label="extra navigation" data-v-f6ef69a3><span class="vpi-more-horizontal icon" data-v-f6ef69a3></span></button><div class="menu" data-v-f6ef69a3><div class="VPMenu" data-v-f6ef69a3 data-v-00ea3a5e><!----><!--[--><!--[--><!----><div class="group" data-v-53eccc99><div class="item appearance" data-v-53eccc99><p class="label" data-v-53eccc99>Appearance</p><div class="appearance-action" data-v-53eccc99><button class="VPSwitch VPSwitchAppearance" type="button" role="switch" title aria-checked="false" data-v-53eccc99 data-v-2881b93b data-v-5009fed8><span class="check" data-v-5009fed8><span class="icon" data-v-5009fed8><!--[--><span class="vpi-sun sun" data-v-2881b93b></span><span class="vpi-moon moon" data-v-2881b93b></span><!--]--></span></span></button></div></div></div><!----><!--]--><!--]--></div></div></div><!--[--><!--]--><button type="button" class="VPNavBarHamburger hamburger" aria-label="mobile navigation" aria-expanded="false" aria-controls="VPNavScreen" data-v-74fc79fd data-v-1d6d00d8><span class="container" data-v-1d6d00d8><span class="top" data-v-1d6d00d8></span><span class="middle" data-v-1d6d00d8></span><span class="bottom" data-v-1d6d00d8></span></span></button></div></div></div></div><div class="divider" data-v-74fc79fd><div class="divider-line" data-v-74fc79fd></div></div></div><!----></header><div class="VPLocalNav has-sidebar empty" data-v-41df81ff data-v-fac38a7d><div class="container" data-v-fac38a7d><button class="menu" aria-expanded="false" aria-controls="VPSidebarNav" data-v-fac38a7d><span class="vpi-align-left menu-icon" data-v-fac38a7d></span><span class="menu-text" data-v-fac38a7d>Menu</span></button><div class="VPLocalNavOutlineDropdown" style="--vp-vh:0px;" data-v-fac38a7d data-v-3829176f><button data-v-3829176f>Return to top</button><!----></div></div></div><aside class="VPSidebar" data-v-41df81ff data-v-78b202de><div class="curtain" data-v-78b202de></div><nav class="nav" id="VPSidebarNav" aria-labelledby="sidebar-aria-label" tabindex="-1" data-v-78b202de><span class="visually-hidden" id="sidebar-aria-label" data-v-78b202de> Sidebar Navigation </span><!--[--><!--]--><!--[--><div class="no-transition group" data-v-9195cb0b><section class="VPSidebarItem level-0" data-v-9195cb0b data-v-29a50a33><div class="item" role="button" tabindex="0" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><h2 class="text" data-v-29a50a33>Getting started</h2><!----></div><div class="items" data-v-29a50a33><!--[--><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Overview</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/quickstart.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Quickstart</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/scaffolding-agents.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Scaffold an agent with Cursor</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/concepts.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Concepts</p><!--]--></a><!----></div><!----></div><!--]--></div></section></div><div class="no-transition group" data-v-9195cb0b><section class="VPSidebarItem level-0" data-v-9195cb0b data-v-29a50a33><div class="item" role="button" tabindex="0" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><h2 class="text" data-v-29a50a33>Improving agents</h2><!----></div><div class="items" data-v-29a50a33><!--[--><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/building-with-agents.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Building agents with agents</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/evals.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Evals</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/ab.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Live A/B metrics</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/storage.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Storage</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/hillclimbing.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Hillclimbing</p><!--]--></a><!----></div><!----></div><!--]--></div></section></div><div class="no-transition group" data-v-9195cb0b><section class="VPSidebarItem level-0 has-active" data-v-9195cb0b data-v-29a50a33><div class="item" role="button" tabindex="0" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><h2 class="text" data-v-29a50a33>Guides</h2><!----></div><div class="items" data-v-29a50a33><!--[--><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/guides/webhooks.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Webhooks & custom channels</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/guides/github.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>GitHub</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/guides/slack.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Slack</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/guides/human-in-the-loop.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Human-in-the-loop approvals</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/guides/agent-to-agent.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Agent-to-agent</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/guides/mcp-oauth.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Host MCP OAuth</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/guides/cloud-runtime.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Cloud runtime</p><!--]--></a><!----></div><!----></div><!--]--></div></section></div><div class="no-transition group" data-v-9195cb0b><section class="VPSidebarItem level-0" data-v-9195cb0b data-v-29a50a33><div class="item" role="button" tabindex="0" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><h2 class="text" data-v-29a50a33>Example agents</h2><!----></div><div class="items" data-v-29a50a33><!--[--><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/example-agents/" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Choose an example</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/example-agents/weather-agent.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Weather agent</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/example-agents/slack-agent.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Slack agent</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/example-agents/concierge.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Concierge</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/example-agents/benny.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Playbook router</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/example-agents/oncall.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Alert investigator</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/example-agents/bugbot.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>PR evidence reviewer</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/example-agents/approval-buddy.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Approval Buddy</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/example-agents/security-reviewer.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Security Reviewer</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/example-agents/fsd.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Remote PR coordinator</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/example-agents/knowledge-base.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Knowledge base</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/example-agents/codebase-wiki.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Codebase wiki</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/example-agents/codeowners-review.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Codeowners review</p><!--]--></a><!----></div><!----></div><!--]--></div></section></div><div class="no-transition group" data-v-9195cb0b><section class="VPSidebarItem level-0" data-v-9195cb0b data-v-29a50a33><div class="item" role="button" tabindex="0" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><h2 class="text" data-v-29a50a33>Operating</h2><!----></div><div class="items" data-v-29a50a33><!--[--><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/deployment.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Deployment</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/troubleshooting.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Fix common problems</p><!--]--></a><!----></div><!----></div><!--]--></div></section></div><div class="no-transition group" data-v-9195cb0b><section class="VPSidebarItem level-0 collapsible" data-v-9195cb0b data-v-29a50a33><div class="item" role="button" tabindex="0" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><h2 class="text" data-v-29a50a33>Reference</h2><div class="caret" role="button" aria-label="toggle section" tabindex="0" data-v-29a50a33><span class="vpi-chevron-right caret-icon" data-v-29a50a33></span></div></div><div class="items" data-v-29a50a33><!--[--><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/reference/project-layout.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Project layout</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/reference/agent-config.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Agent config</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/reference/instructions.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Instructions</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/reference/tools.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Tools</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/reference/prompt.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>prompt</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/reference/skills.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Skills</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/reference/connections.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>MCP Connections</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/reference/subagents.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Subagents</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/reference/channels.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Channels</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/reference/schedules.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Schedules & reminders</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/reference/hooks.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Hooks</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/reference/artifacts.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Artifacts</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/reference/sessions.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Sessions & streaming</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/reference/playground.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Playground</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/reference/cli.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>CLI</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/reference/http-api.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>HTTP API</p><!--]--></a><!----></div><!----></div><!--]--></div></section></div><!--]--><!--[--><!--]--></nav></aside><div class="VPContent has-sidebar" id="VPContent" data-v-41df81ff data-v-9d9adfa7><div class="VPDoc has-sidebar has-aside" data-v-9d9adfa7 data-v-d5d7ccd1><!--[--><!--]--><div class="container" data-v-d5d7ccd1><div class="aside" data-v-d5d7ccd1><div class="aside-curtain" data-v-d5d7ccd1></div><div class="aside-container" data-v-d5d7ccd1><div class="aside-content" data-v-d5d7ccd1><div class="VPDocAside" data-v-d5d7ccd1 data-v-83378aaf><!--[--><!--]--><!--[--><!--]--><nav aria-labelledby="doc-outline-aria-label" class="VPDocAsideOutline" data-v-83378aaf data-v-5d36b21a><div class="content" data-v-5d36b21a><div class="outline-marker" data-v-5d36b21a></div><div aria-level="2" class="outline-title" id="doc-outline-aria-label" role="heading" data-v-5d36b21a>On this page</div><ul class="VPDocOutlineItem root" data-v-5d36b21a data-v-537d09da><!--[--><!--]--></ul></div></nav><!--[--><!--]--><div class="spacer" data-v-83378aaf></div><!--[--><!--]--><!----><!--[--><!--]--><!--[--><!--]--></div></div></div></div><div class="content" data-v-d5d7ccd1><div class="content-container" data-v-d5d7ccd1><!--[--><!--]--><main class="main" data-v-d5d7ccd1><div style="position:relative;" class="vp-doc _docs_guides_github" data-v-d5d7ccd1><div><h1 id="github-agents" tabindex="-1">GitHub agents <a class="header-anchor" href="#github-agents" aria-label="Permalink to &quot;GitHub agents&quot;">​</a></h1><p>Wake your agent from repository events without exposing a public webhook URL. Prefer <code>serve --cursor-events</code>: the host long-polls Cursor&#39;s SCM event stream for repos you&#39;ve connected to Cursor. You still declare a <code>githubChannel</code> so hooks decide what each event does.</p><p>The companion skill for coding agents is <a href="./../../skills/github/SKILL.html"><code>skills/github/SKILL.md</code></a>.</p><h2 id="pull-events-from-cursor" tabindex="-1">Pull events from Cursor <a class="header-anchor" href="#pull-events-from-cursor" aria-label="Permalink to &quot;Pull events from Cursor&quot;">​</a></h2><p>Connect GitHub in Cursor for the repositories you care about (Settings or <a href="https://cursor.com/dashboard" target="_blank" rel="noreferrer">cursor.com/dashboard</a>). That gives your account access and lets Cursor receive the repo&#39;s webhooks. Sign the host in (<code>agent-sdk login</code> or <code>CURSOR_API_KEY</code>), then opt the channel into the Cursor account connection:</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> githubChannel</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
21
+ <div id="app"><div class="Layout" data-v-41df81ff><!--[--><!--]--><!--[--><span tabindex="-1" data-v-c792f8ce></span><a href="#VPContent" class="VPSkipLink visually-hidden" data-v-c792f8ce>Skip to content</a><!--]--><!----><header class="VPNav" data-v-41df81ff data-v-ecf0170c><div class="VPNavBar" data-v-ecf0170c data-v-74fc79fd><div class="wrapper" data-v-74fc79fd><div class="container" data-v-74fc79fd><div class="title" data-v-74fc79fd><div class="VPNavBarTitle has-sidebar" data-v-74fc79fd data-v-38e78292><a class="title" href="/docs/" data-v-38e78292><!--[--><!--]--><!----><span data-v-38e78292>Agent SDK</span><!--[--><!--]--></a></div></div><div class="content" data-v-74fc79fd><div class="content-body" data-v-74fc79fd><!--[--><!--]--><div class="VPNavBarSearch search" data-v-74fc79fd><!--[--><!----><div id="local-search"><button type="button" class="DocSearch DocSearch-Button" aria-label="Search"><span class="DocSearch-Button-Container"><span class="vp-icon DocSearch-Search-Icon"></span><span class="DocSearch-Button-Placeholder">Search</span></span><span class="DocSearch-Button-Keys"><kbd class="DocSearch-Button-Key"></kbd><kbd class="DocSearch-Button-Key">K</kbd></span></button></div><!--]--></div><nav aria-labelledby="main-nav-aria-label" class="VPNavBarMenu menu" data-v-74fc79fd data-v-6bcb02d4><span id="main-nav-aria-label" class="visually-hidden" data-v-6bcb02d4> Main Navigation </span><!--[--><!--[--><a class="VPLink link VPNavBarMenuLink" href="/docs/quickstart.html" tabindex="0" data-v-6bcb02d4 data-v-40a52867><!--[--><span data-v-40a52867>Quickstart</span><!--]--></a><!--]--><!--[--><a class="VPLink link VPNavBarMenuLink" href="/docs/guides/webhooks.html" tabindex="0" data-v-6bcb02d4 data-v-40a52867><!--[--><span data-v-40a52867>Guides</span><!--]--></a><!--]--><!--[--><a class="VPLink link VPNavBarMenuLink" href="/docs/example-agents/" tabindex="0" data-v-6bcb02d4 data-v-40a52867><!--[--><span data-v-40a52867>Examples</span><!--]--></a><!--]--><!--[--><a class="VPLink link VPNavBarMenuLink" href="/docs/reference/project-layout.html" tabindex="0" data-v-6bcb02d4 data-v-40a52867><!--[--><span data-v-40a52867>Reference</span><!--]--></a><!--]--><!--]--></nav><!----><div class="VPNavBarAppearance appearance" data-v-74fc79fd data-v-106703d3><button class="VPSwitch VPSwitchAppearance" type="button" role="switch" title aria-checked="false" data-v-106703d3 data-v-2881b93b data-v-5009fed8><span class="check" data-v-5009fed8><span class="icon" data-v-5009fed8><!--[--><span class="vpi-sun sun" data-v-2881b93b></span><span class="vpi-moon moon" data-v-2881b93b></span><!--]--></span></span></button></div><!----><div class="VPFlyout VPNavBarExtra extra" data-v-74fc79fd data-v-53eccc99 data-v-f6ef69a3><button type="button" class="button" aria-haspopup="true" aria-expanded="false" aria-label="extra navigation" data-v-f6ef69a3><span class="vpi-more-horizontal icon" data-v-f6ef69a3></span></button><div class="menu" data-v-f6ef69a3><div class="VPMenu" data-v-f6ef69a3 data-v-00ea3a5e><!----><!--[--><!--[--><!----><div class="group" data-v-53eccc99><div class="item appearance" data-v-53eccc99><p class="label" data-v-53eccc99>Appearance</p><div class="appearance-action" data-v-53eccc99><button class="VPSwitch VPSwitchAppearance" type="button" role="switch" title aria-checked="false" data-v-53eccc99 data-v-2881b93b data-v-5009fed8><span class="check" data-v-5009fed8><span class="icon" data-v-5009fed8><!--[--><span class="vpi-sun sun" data-v-2881b93b></span><span class="vpi-moon moon" data-v-2881b93b></span><!--]--></span></span></button></div></div></div><!----><!--]--><!--]--></div></div></div><!--[--><!--]--><button type="button" class="VPNavBarHamburger hamburger" aria-label="mobile navigation" aria-expanded="false" aria-controls="VPNavScreen" data-v-74fc79fd data-v-1d6d00d8><span class="container" data-v-1d6d00d8><span class="top" data-v-1d6d00d8></span><span class="middle" data-v-1d6d00d8></span><span class="bottom" data-v-1d6d00d8></span></span></button></div></div></div></div><div class="divider" data-v-74fc79fd><div class="divider-line" data-v-74fc79fd></div></div></div><!----></header><div class="VPLocalNav has-sidebar empty" data-v-41df81ff data-v-fac38a7d><div class="container" data-v-fac38a7d><button class="menu" aria-expanded="false" aria-controls="VPSidebarNav" data-v-fac38a7d><span class="vpi-align-left menu-icon" data-v-fac38a7d></span><span class="menu-text" data-v-fac38a7d>Menu</span></button><div class="VPLocalNavOutlineDropdown" style="--vp-vh:0px;" data-v-fac38a7d data-v-3829176f><button data-v-3829176f>Return to top</button><!----></div></div></div><aside class="VPSidebar" data-v-41df81ff data-v-78b202de><div class="curtain" data-v-78b202de></div><nav class="nav" id="VPSidebarNav" aria-labelledby="sidebar-aria-label" tabindex="-1" data-v-78b202de><span class="visually-hidden" id="sidebar-aria-label" data-v-78b202de> Sidebar Navigation </span><!--[--><!--]--><!--[--><div class="no-transition group" data-v-9195cb0b><section class="VPSidebarItem level-0" data-v-9195cb0b data-v-29a50a33><div class="item" role="button" tabindex="0" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><h2 class="text" data-v-29a50a33>Getting started</h2><!----></div><div class="items" data-v-29a50a33><!--[--><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Overview</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/quickstart.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Quickstart</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/scaffolding-agents.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Scaffold an agent with Cursor</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/concepts.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Concepts</p><!--]--></a><!----></div><!----></div><!--]--></div></section></div><div class="no-transition group" data-v-9195cb0b><section class="VPSidebarItem level-0" data-v-9195cb0b data-v-29a50a33><div class="item" role="button" tabindex="0" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><h2 class="text" data-v-29a50a33>Templates</h2><!----></div><div class="items" data-v-29a50a33><!--[--><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/templates/triage.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Triage agent</p><!--]--></a><!----></div><!----></div><!--]--></div></section></div><div class="no-transition group" data-v-9195cb0b><section class="VPSidebarItem level-0" data-v-9195cb0b data-v-29a50a33><div class="item" role="button" tabindex="0" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><h2 class="text" data-v-29a50a33>Improving agents</h2><!----></div><div class="items" data-v-29a50a33><!--[--><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/building-with-agents.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Building agents with agents</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/evals.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Evals</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/ab.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Live A/B metrics</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/storage.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Storage</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/hillclimbing.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Hillclimbing</p><!--]--></a><!----></div><!----></div><!--]--></div></section></div><div class="no-transition group" data-v-9195cb0b><section class="VPSidebarItem level-0 has-active" data-v-9195cb0b data-v-29a50a33><div class="item" role="button" tabindex="0" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><h2 class="text" data-v-29a50a33>Guides</h2><!----></div><div class="items" data-v-29a50a33><!--[--><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/guides/webhooks.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Webhooks & custom channels</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/guides/github.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>GitHub</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/guides/slack.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Slack</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/guides/human-in-the-loop.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Human-in-the-loop approvals</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/guides/agent-to-agent.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Agent-to-agent</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/guides/mcp-oauth.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Host MCP OAuth</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/guides/cloud-runtime.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Cloud runtime</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/guides/opentelemetry.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>OpenTelemetry</p><!--]--></a><!----></div><!----></div><!--]--></div></section></div><div class="no-transition group" data-v-9195cb0b><section class="VPSidebarItem level-0" data-v-9195cb0b data-v-29a50a33><div class="item" role="button" tabindex="0" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><h2 class="text" data-v-29a50a33>Example agents</h2><!----></div><div class="items" data-v-29a50a33><!--[--><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/example-agents/" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Choose an example</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/example-agents/weather-agent.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Weather agent</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/example-agents/slack-agent.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Slack agent</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/example-agents/concierge.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Concierge</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/example-agents/benny.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Playbook router</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/example-agents/oncall.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Alert investigator</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/example-agents/bugbot.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>PR evidence reviewer</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/example-agents/approval-buddy.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Approval Buddy</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/example-agents/security-reviewer.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Security Reviewer</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/example-agents/fsd.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Remote PR coordinator</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/example-agents/knowledge-base.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Knowledge base</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/example-agents/codebase-wiki.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Codebase wiki</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/example-agents/codeowners-review.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Codeowners review</p><!--]--></a><!----></div><!----></div><!--]--></div></section></div><div class="no-transition group" data-v-9195cb0b><section class="VPSidebarItem level-0" data-v-9195cb0b data-v-29a50a33><div class="item" role="button" tabindex="0" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><h2 class="text" data-v-29a50a33>Operating</h2><!----></div><div class="items" data-v-29a50a33><!--[--><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/deployment.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Deployment</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/troubleshooting.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Fix common problems</p><!--]--></a><!----></div><!----></div><!--]--></div></section></div><div class="no-transition group" data-v-9195cb0b><section class="VPSidebarItem level-0 collapsible" data-v-9195cb0b data-v-29a50a33><div class="item" role="button" tabindex="0" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><h2 class="text" data-v-29a50a33>Reference</h2><div class="caret" role="button" aria-label="toggle section" tabindex="0" data-v-29a50a33><span class="vpi-chevron-right caret-icon" data-v-29a50a33></span></div></div><div class="items" data-v-29a50a33><!--[--><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/reference/project-layout.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Project layout</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/reference/agent-config.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Agent config</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/reference/instructions.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Instructions</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/reference/tools.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Tools</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/reference/prompt.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>prompt</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/reference/skills.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Skills</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/reference/connections.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>MCP Connections</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/reference/subagents.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Subagents</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/reference/channels.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Channels</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/reference/schedules.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Schedules & reminders</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/reference/hooks.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Hooks</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/reference/artifacts.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Artifacts</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/reference/sessions.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Sessions & streaming</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/reference/playground.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Playground</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/reference/cli.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>CLI</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/reference/http-api.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>HTTP API</p><!--]--></a><!----></div><!----></div><!--]--></div></section></div><!--]--><!--[--><!--]--></nav></aside><div class="VPContent has-sidebar" id="VPContent" data-v-41df81ff data-v-9d9adfa7><div class="VPDoc has-sidebar has-aside" data-v-9d9adfa7 data-v-d5d7ccd1><!--[--><!--]--><div class="container" data-v-d5d7ccd1><div class="aside" data-v-d5d7ccd1><div class="aside-curtain" data-v-d5d7ccd1></div><div class="aside-container" data-v-d5d7ccd1><div class="aside-content" data-v-d5d7ccd1><div class="VPDocAside" data-v-d5d7ccd1 data-v-83378aaf><!--[--><!--]--><!--[--><!--]--><nav aria-labelledby="doc-outline-aria-label" class="VPDocAsideOutline" data-v-83378aaf data-v-5d36b21a><div class="content" data-v-5d36b21a><div class="outline-marker" data-v-5d36b21a></div><div aria-level="2" class="outline-title" id="doc-outline-aria-label" role="heading" data-v-5d36b21a>On this page</div><ul class="VPDocOutlineItem root" data-v-5d36b21a data-v-537d09da><!--[--><!--]--></ul></div></nav><!--[--><!--]--><div class="spacer" data-v-83378aaf></div><!--[--><!--]--><!----><!--[--><!--]--><!--[--><!--]--></div></div></div></div><div class="content" data-v-d5d7ccd1><div class="content-container" data-v-d5d7ccd1><!--[--><!--]--><main class="main" data-v-d5d7ccd1><div style="position:relative;" class="vp-doc _docs_guides_github" data-v-d5d7ccd1><div><h1 id="github-agents" tabindex="-1">GitHub agents <a class="header-anchor" href="#github-agents" aria-label="Permalink to &quot;GitHub agents&quot;">​</a></h1><p>Wake your agent from repository events without exposing a public webhook URL. Prefer <code>serve --cursor-events</code>: the host long-polls Cursor&#39;s SCM event stream for repos you&#39;ve connected to Cursor. You still declare a <code>githubChannel</code> so hooks decide what each event does.</p><p>The companion skill for coding agents is <a href="./../../skills/github/SKILL.html"><code>skills/github/SKILL.md</code></a>.</p><h2 id="pull-events-from-cursor" tabindex="-1">Pull events from Cursor <a class="header-anchor" href="#pull-events-from-cursor" aria-label="Permalink to &quot;Pull events from Cursor&quot;">​</a></h2><p>Connect GitHub in Cursor for the repositories you care about (Settings or <a href="https://cursor.com/dashboard" target="_blank" rel="noreferrer">cursor.com/dashboard</a>). That gives your account access and lets Cursor receive the repo&#39;s webhooks. Sign the host in (<code>agent-sdk login</code> or <code>CURSOR_API_KEY</code>), then opt the channel into the Cursor account connection:</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> githubChannel</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
22
22
  <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> cursorAccount: {</span></span>
23
23
  <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> repos: [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;owner/repo&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">],</span></span>
24
24
  <span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> // permissions?: &quot;read&quot; | &quot;pr-write&quot; | &quot;contents-write&quot;</span></span>
25
25
  <span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> // default &quot;pr-write&quot; (comments / PR writes, no contents:write)</span></span>
26
26
  <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
27
27
  <span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> // hooks...</span></span>
28
- <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p><code>cursorAccount</code> starts the event relay and mints one short-lived GitHub credential scoped to those repositories. <code>ctx.github</code>, <code>ctx.host.github</code>, and child <code>gh</code> commands share it. The Agent SDK refreshes the credential before expiry. No GitHub App key, PAT, or separate <code>gh auth login</code> is needed on the host.</p><p>Choose <code>permissions</code> by what the agent needs:</p><table tabindex="0"><thead><tr><th><code>permissions</code></th><th>Use when</th></tr></thead><tbody><tr><td><code>&quot;read&quot;</code></td><td>Inspect PRs / issues / statuses only</td></tr><tr><td><code>&quot;pr-write&quot;</code> (default)</td><td>Comment, review, update PR/issue metadata</td></tr><tr><td><code>&quot;contents-write&quot;</code></td><td>Push code (<code>contents:write</code>)</td></tr></tbody></table><p><code>contents-write</code> is an explicit opt-up. The host holds a push-capable token shared with model-driven tools and untrusted webhook content — prefer <code>&quot;pr-write&quot;</code> unless the agent must push.</p><p>Selected repositories must share one GitHub owner (one App installation). Configuration that spans owners fails at startup / mint time.</p><p>To keep repository scope in deployment config instead, use <code>cursorAccount: true</code> and pass it at serve time:</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> serve</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> .</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --cursor-events</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --repo</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> owner/repo</span></span></code></pre></div><p>Repeat <code>--repo</code> for each repository. The stream and credential are resolved as the signed-in Cursor principal. <code>serve</code> refuses to start signed out.</p><p>Offset and consumer id live under <code>&lt;state-root&gt;/cursor-events/</code>. <code>CURSOR_API_BASE_URL</code> overrides the backend. The stream carries event metadata, not full webhook bodies, so your agent should re-read the PR or checks from GitHub instead of trusting a snapshot in the wake.</p><p>This is the preferred production path: no public URL, no repo admin webhook, and no inbound network for GitHub deliveries.</p><h2 id="define-the-channel" tabindex="-1">Define the channel <a class="header-anchor" href="#define-the-channel" aria-label="Permalink to &quot;Define the channel&quot;">​</a></h2><p>Author <code>agent/channels/github.ts</code> with <code>githubChannel()</code> from <code>@cursor/july/channels/github</code>. It mounts <code>POST /&lt;slug&gt;/v1/channels/github</code> and publishes the events it dispatches on. That event set comes from the hooks you declare, or you pin it with <code>webhookEvents</code>. Cursor event pull and local replay both use it.</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { defaultGitHubAuth, githubChannel } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/july/channels/github&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
28
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p><code>cursorAccount</code> starts the event relay and mints one short-lived GitHub credential scoped to those repositories. <code>ctx.github</code>, <code>ctx.host.github</code>, and child <code>gh</code> commands share it. The Agent SDK refreshes the credential before expiry. No GitHub App key, PAT, or separate <code>gh auth login</code> is needed on the host.</p><p>Choose <code>permissions</code> by what the agent needs:</p><table tabindex="0"><thead><tr><th><code>permissions</code></th><th>Use when</th></tr></thead><tbody><tr><td><code>&quot;read&quot;</code></td><td>Inspect PRs / issues / statuses only</td></tr><tr><td><code>&quot;pr-write&quot;</code> (default)</td><td>Comment, review, update PR/issue metadata</td></tr><tr><td><code>&quot;contents-write&quot;</code></td><td>Push code, or create commit statuses</td></tr></tbody></table><p><code>contents-write</code> is an explicit opt-up. Creating a commit status needs push-equivalent access (<code>contents:write</code>); <code>pr-write</code> alone can write comments and banners but not merge-box checks. Prefer <code>&quot;pr-write&quot;</code> unless the agent must push or post commit statuses.</p><p>Selected repositories must share one GitHub owner (one App installation). Configuration that spans owners fails at startup / mint time.</p><p>To keep repository scope in deployment config instead, use <code>cursorAccount: true</code> and pass it at serve time:</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> serve</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> .</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --cursor-events</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --repo</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> owner/repo</span></span></code></pre></div><p>Repeat <code>--repo</code> for each repository. The stream and credential are resolved as the signed-in Cursor principal. <code>serve</code> refuses to start signed out.</p><p>Offset and consumer id live under <code>&lt;state-root&gt;/cursor-events/</code>. <code>CURSOR_API_BASE_URL</code> overrides the backend. The stream carries event metadata, not full webhook bodies, so your agent should re-read the PR or checks from GitHub instead of trusting a snapshot in the wake.</p><p>This is the preferred production path: no public URL, no repo admin webhook, and no inbound network for GitHub deliveries.</p><h2 id="define-the-channel" tabindex="-1">Define the channel <a class="header-anchor" href="#define-the-channel" aria-label="Permalink to &quot;Define the channel&quot;">​</a></h2><p>Author <code>agent/channels/github.ts</code> with <code>githubChannel()</code> from <code>@cursor/july/channels/github</code>. It mounts <code>POST /&lt;slug&gt;/v1/channels/github</code> and publishes the events it dispatches on. That event set comes from the hooks you declare, or you pin it with <code>webhookEvents</code>. Cursor event pull and local replay both use it.</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { defaultGitHubAuth, githubChannel } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/july/channels/github&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
29
29
  <span class="line"></span>
30
30
  <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> githubChannel</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
31
31
  <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> botName: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;my-agent&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// or GITHUB_APP_SLUG; used to ignore self-comments</span></span>
@@ -44,8 +44,34 @@
44
44
  <span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> github</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> replay</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> owner/repo#123</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> .</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --events</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &#39;*&#39;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --conclusion</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> failure</span></span>
45
45
  <span class="line"></span>
46
46
  <span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># Inspect payloads without POSTing, and snapshot them as fixtures</span></span>
47
- <span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> github</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> replay</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> owner/repo#123</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> .</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --events</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &#39;*&#39;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dry-run</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --out</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> fixtures/github</span></span></code></pre></div><p><code>--events</code> defaults to <code>pull_request</code>, and <code>&#39;*&#39;</code> means the channel&#39;s declared set. <code>--action</code>, <code>--conclusion</code>, <code>--comment</code>, and <code>--context</code> shape each synthesized event. <code>--secret</code> (or <code>GITHUB_WEBHOOK_SECRET</code>) signs them.</p><h2 id="receive-webhooks-directly" tabindex="-1">Receive webhooks directly <a class="header-anchor" href="#receive-webhooks-directly" aria-label="Permalink to &quot;Receive webhooks directly&quot;">​</a></h2><p>Most hosts should pull events from Cursor instead. Use the HTTP channel route when you already terminate GitHub webhooks yourself, or when you are POSTing fixtures and replay locally.</p><p>With a webhook secret configured, the route admits everyone (<code>allowAll()</code>) and the channel verifies <code>X-Hub-Signature-256</code> before parsing. The HMAC becomes the request principal. Without a secret, the route is loopback-only. The exception is <code>serve --dev</code>, which admits unsigned loopback deliveries so fixtures and replay work with zero config. Non-dev targets that accept real GitHub POSTs always need the secret, and the same value must live on the server and on whatever signs deliveries.</p><h2 id="handle-high-event-volume" tabindex="-1">Handle high event volume <a class="header-anchor" href="#handle-high-event-volume" aria-label="Permalink to &quot;Handle high event volume&quot;">​</a></h2><p>These patterns come from running a PR agent against real traffic:</p><ul><li>Debounce per PR (~3 seconds, latest event wins), and re-buffer while CI settles. Skip a flush when a turn for that PR is already running.</li><li>Persist the buffer before you acknowledge a wake, and restore it on channel start. A restart must not drop buffered wakes.</li><li>Key sessions with a stable continuation token (<code>pr:owner/repo#N</code>) so every wake resumes the PR&#39;s conversation. Cross-channel resume needs an affinity store mapping PR → SDK agent id; write one from an <code>agent.bound</code> hook.</li><li>Keep payload details out of wake prompts. Send a generic &quot;re-check the PR&quot; and let the agent re-read source of truth instead of trusting a stale snapshot.</li><li>Cancel PR-scoped reminders on <code>pull_request.closed</code>.</li><li>Decide explicitly which repos the agent may act on. Without an allowlist the channel wakes for whatever deliveries reach it, and every wake spends real model budget.</li></ul><h2 id="related" tabindex="-1">Related <a class="header-anchor" href="#related" aria-label="Permalink to &quot;Related&quot;">​</a></h2><ul><li><a href="./webhooks.html">Webhooks and custom channels</a>: the HTTP mechanism under this pack</li><li><a href="./../evals.html">Evals</a>: turn replay snapshots into regression fixtures</li><li><a href="./cloud-runtime.html">Cloud runtime</a>: attach PRs to cloud VMs</li></ul></div></div></main><footer class="VPDocFooter" data-v-d5d7ccd1 data-v-a5908b0f><!--[--><!--]--><!----><nav class="prev-next" aria-labelledby="doc-footer-aria-label" data-v-a5908b0f><span class="visually-hidden" id="doc-footer-aria-label" data-v-a5908b0f>Pager</span><div class="pager" data-v-a5908b0f><a class="VPLink link pager-link prev" href="/docs/guides/webhooks.html" data-v-a5908b0f><!--[--><span class="desc" data-v-a5908b0f>Previous page</span><span class="title" data-v-a5908b0f>Webhooks & custom channels</span><!--]--></a></div><div class="pager" data-v-a5908b0f><a class="VPLink link pager-link next" href="/docs/guides/slack.html" data-v-a5908b0f><!--[--><span class="desc" data-v-a5908b0f>Next page</span><span class="title" data-v-a5908b0f>Slack</span><!--]--></a></div></nav></footer><!--[--><!--]--></div></div></div><!--[--><!--]--></div></div><!----><!--[--><!--]--></div></div>
48
- <script>window.__VP_HASH_MAP__=JSON.parse("{\"ab.md\":\"hdxsvX5M\",\"building-with-agents.md\":\"PeZaZA1P\",\"concepts.md\":\"CqOsxbMU\",\"deployment.md\":\"BHVjVqRa\",\"evals.md\":\"qeoGgPw0\",\"example-agents_approval-buddy.md\":\"CIiZ9coo\",\"example-agents_benny.md\":\"l7JTmm8X\",\"example-agents_bugbot.md\":\"Dp5JqHSQ\",\"example-agents_codebase-wiki.md\":\"D-lteFf0\",\"example-agents_codeowners-review.md\":\"BU2ZXLf-\",\"example-agents_concierge.md\":\"DA2al_NK\",\"example-agents_fsd.md\":\"DPz9ezO4\",\"example-agents_index.md\":\"xmJ87d_3\",\"example-agents_knowledge-base.md\":\"IneynQSR\",\"example-agents_oncall.md\":\"ZE0n6ZFN\",\"example-agents_security-reviewer.md\":\"Dkf1gyo6\",\"example-agents_slack-agent.md\":\"06jQXTAI\",\"example-agents_weather-agent.md\":\"DC3lINjo\",\"guides_agent-to-agent.md\":\"Bmbxy-FA\",\"guides_cloud-runtime.md\":\"V5igN4Sq\",\"guides_github.md\":\"R2QlpR75\",\"guides_human-in-the-loop.md\":\"BWvT7UqY\",\"guides_mcp-oauth.md\":\"C7G7IykG\",\"guides_slack.md\":\"zriQpU_9\",\"guides_webhooks.md\":\"DB-r_er9\",\"hillclimbing.md\":\"yXqdlv2R\",\"index.md\":\"BKpbkCa6\",\"quickstart.md\":\"rIbfahJM\",\"reference_agent-config.md\":\"CRmkoxd6\",\"reference_artifacts.md\":\"BGG4bZo-\",\"reference_channels.md\":\"BIabFUAI\",\"reference_cli.md\":\"DqEqQpGn\",\"reference_connections.md\":\"CSQiNzre\",\"reference_hooks.md\":\"BHeG-vjK\",\"reference_http-api.md\":\"DGrw_wOu\",\"reference_instructions.md\":\"CgoV-YEb\",\"reference_playground.md\":\"CPZhfYaO\",\"reference_project-layout.md\":\"_XdeMahr\",\"reference_prompt.md\":\"BaiweQxE\",\"reference_schedules.md\":\"gmfYzf_I\",\"reference_sessions.md\":\"DBVFi2Sx\",\"reference_skills.md\":\"B_jHN7JL\",\"reference_subagents.md\":\"DSrGLIuB\",\"reference_tools.md\":\"lSrsTxYJ\",\"scaffolding-agents.md\":\"mkc3B_ZW\",\"storage.md\":\"DcGSnIxX\",\"troubleshooting.md\":\"CkgwmVI0\"}");window.__VP_SITE_DATA__=JSON.parse("{\"lang\":\"en-US\",\"dir\":\"ltr\",\"title\":\"Agent SDK\",\"description\":\"Filesystem-first framework for building and serving Cursor agents.\",\"base\":\"/docs/\",\"head\":[],\"router\":{\"prefetchLinks\":true},\"appearance\":true,\"themeConfig\":{\"nav\":[{\"text\":\"Quickstart\",\"link\":\"/quickstart\"},{\"text\":\"Guides\",\"link\":\"/guides/webhooks\"},{\"text\":\"Examples\",\"link\":\"/example-agents/\"},{\"text\":\"Reference\",\"link\":\"/reference/project-layout\"}],\"search\":{\"provider\":\"local\"},\"outline\":{\"level\":[2,3]},\"sidebar\":[{\"text\":\"Getting started\",\"items\":[{\"text\":\"Overview\",\"link\":\"/\"},{\"text\":\"Quickstart\",\"link\":\"/quickstart\"},{\"text\":\"Scaffold an agent with Cursor\",\"link\":\"/scaffolding-agents\"},{\"text\":\"Concepts\",\"link\":\"/concepts\"}]},{\"text\":\"Improving agents\",\"items\":[{\"text\":\"Building agents with agents\",\"link\":\"/building-with-agents\"},{\"text\":\"Evals\",\"link\":\"/evals\"},{\"text\":\"Live A/B metrics\",\"link\":\"/ab\"},{\"text\":\"Storage\",\"link\":\"/storage\"},{\"text\":\"Hillclimbing\",\"link\":\"/hillclimbing\"}]},{\"text\":\"Guides\",\"items\":[{\"text\":\"Webhooks & custom channels\",\"link\":\"/guides/webhooks\"},{\"text\":\"GitHub\",\"link\":\"/guides/github\"},{\"text\":\"Slack\",\"link\":\"/guides/slack\"},{\"text\":\"Human-in-the-loop approvals\",\"link\":\"/guides/human-in-the-loop\"},{\"text\":\"Agent-to-agent\",\"link\":\"/guides/agent-to-agent\"},{\"text\":\"Host MCP OAuth\",\"link\":\"/guides/mcp-oauth\"},{\"text\":\"Cloud runtime\",\"link\":\"/guides/cloud-runtime\"}]},{\"text\":\"Example agents\",\"items\":[{\"text\":\"Choose an example\",\"link\":\"/example-agents/\"},{\"text\":\"Weather agent\",\"link\":\"/example-agents/weather-agent\"},{\"text\":\"Slack agent\",\"link\":\"/example-agents/slack-agent\"},{\"text\":\"Concierge\",\"link\":\"/example-agents/concierge\"},{\"text\":\"Playbook router\",\"link\":\"/example-agents/benny\"},{\"text\":\"Alert investigator\",\"link\":\"/example-agents/oncall\"},{\"text\":\"PR evidence reviewer\",\"link\":\"/example-agents/bugbot\"},{\"text\":\"Approval Buddy\",\"link\":\"/example-agents/approval-buddy\"},{\"text\":\"Security Reviewer\",\"link\":\"/example-agents/security-reviewer\"},{\"text\":\"Remote PR coordinator\",\"link\":\"/example-agents/fsd\"},{\"text\":\"Knowledge base\",\"link\":\"/example-agents/knowledge-base\"},{\"text\":\"Codebase wiki\",\"link\":\"/example-agents/codebase-wiki\"},{\"text\":\"Codeowners review\",\"link\":\"/example-agents/codeowners-review\"}]},{\"text\":\"Operating\",\"items\":[{\"text\":\"Deployment\",\"link\":\"/deployment\"},{\"text\":\"Fix common problems\",\"link\":\"/troubleshooting\"}]},{\"text\":\"Reference\",\"collapsed\":false,\"items\":[{\"text\":\"Project layout\",\"link\":\"/reference/project-layout\"},{\"text\":\"Agent config\",\"link\":\"/reference/agent-config\"},{\"text\":\"Instructions\",\"link\":\"/reference/instructions\"},{\"text\":\"Tools\",\"link\":\"/reference/tools\"},{\"text\":\"prompt\",\"link\":\"/reference/prompt\"},{\"text\":\"Skills\",\"link\":\"/reference/skills\"},{\"text\":\"MCP Connections\",\"link\":\"/reference/connections\"},{\"text\":\"Subagents\",\"link\":\"/reference/subagents\"},{\"text\":\"Channels\",\"link\":\"/reference/channels\"},{\"text\":\"Schedules & reminders\",\"link\":\"/reference/schedules\"},{\"text\":\"Hooks\",\"link\":\"/reference/hooks\"},{\"text\":\"Artifacts\",\"link\":\"/reference/artifacts\"},{\"text\":\"Sessions & streaming\",\"link\":\"/reference/sessions\"},{\"text\":\"Playground\",\"link\":\"/reference/playground\"},{\"text\":\"CLI\",\"link\":\"/reference/cli\"},{\"text\":\"HTTP API\",\"link\":\"/reference/http-api\"}]}]},\"locales\":{},\"scrollOffset\":134,\"cleanUrls\":false}");</script>
47
+ <span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> github</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> replay</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> owner/repo#123</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> .</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --events</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &#39;*&#39;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dry-run</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --out</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> fixtures/github</span></span></code></pre></div><p><code>--events</code> defaults to <code>pull_request</code>, and <code>&#39;*&#39;</code> means the channel&#39;s declared set. <code>--action</code>, <code>--conclusion</code>, <code>--comment</code>, and <code>--context</code> shape each synthesized event. <code>--secret</code> (or <code>GITHUB_WEBHOOK_SECRET</code>) signs them.</p><h2 id="receive-webhooks-directly" tabindex="-1">Receive webhooks directly <a class="header-anchor" href="#receive-webhooks-directly" aria-label="Permalink to &quot;Receive webhooks directly&quot;">​</a></h2><p>Most hosts should pull events from Cursor instead. Use the HTTP channel route when you already terminate GitHub webhooks yourself, or when you are POSTing fixtures and replay locally.</p><p>With a webhook secret configured, the route admits everyone (<code>allowAll()</code>) and the channel verifies <code>X-Hub-Signature-256</code> before parsing. The HMAC becomes the request principal. Without a secret, the route is loopback-only. The exception is <code>serve --dev</code>, which admits unsigned loopback deliveries so fixtures and replay work with zero config. Non-dev targets that accept real GitHub POSTs always need the secret, and the same value must live on the server and on whatever signs deliveries.</p><h2 id="handle-high-event-volume" tabindex="-1">Handle high event volume <a class="header-anchor" href="#handle-high-event-volume" aria-label="Permalink to &quot;Handle high event volume&quot;">​</a></h2><p>These patterns come from running a PR agent against real traffic:</p><ul><li>Debounce per PR (~3 seconds, latest event wins), and re-buffer while CI settles. Skip a flush when a turn for that PR is already running.</li><li>Persist the buffer before you acknowledge a wake, and restore it on channel start. A restart must not drop buffered wakes.</li><li>Key sessions with a stable continuation token (<code>pr:owner/repo#N</code>) so every wake resumes the PR&#39;s conversation. Cross-channel resume needs an affinity store mapping PR → SDK agent id; write it from an <code>agent.bound</code> hook with <code>ctx.host.kv</code>.</li><li>Keep payload details out of wake prompts. Send a generic &quot;re-check the PR&quot; and let the agent re-read source of truth instead of trusting a stale snapshot.</li><li>Cancel PR-scoped reminders on <code>pull_request.closed</code>.</li><li>Decide explicitly which repos the agent may act on. Without an allowlist the channel wakes for whatever deliveries reach it, and every wake spends real model budget.</li></ul><h2 id="show-pr-progress" tabindex="-1">Show PR progress <a class="header-anchor" href="#show-pr-progress" aria-label="Permalink to &quot;Show PR progress&quot;">​</a></h2><p>Autofix-style agents need a deterministic merge-box check and a sticky PR comment that converges when the turn ends. Configure that on the channel with <code>progress.commitStatus</code> and <code>progress.banner</code>. A hook can read and write <code>ctx.host.kv</code> and <code>ctx.host.files</code> after a turn. Use that for derived state. Keep GitHub status and banner writes on the channel.</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { defaultGitHubAuth, githubChannel } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/july/channels/github&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
48
+ <span class="line"></span>
49
+ <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> githubChannel</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
50
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> botName: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;autofix&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
51
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> deliverReplies: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">false</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
52
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> progress: {</span></span>
53
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> reactions: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">false</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
54
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> commitStatus: {</span></span>
55
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> context: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;autofix&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
56
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> pending: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Autofix running&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
57
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> success: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Autofix finished&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
58
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> failure: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Autofix failed&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
59
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
60
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> banner: {</span></span>
61
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> pending: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Autofix running…&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
62
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> success: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Autofix finished&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
63
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> failure: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Autofix failed&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
64
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
65
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
66
+ <span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> // commitStatus needs contents-write (push-equivalent). Banner works on pr-write.</span></span>
67
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> cursorAccount: {</span></span>
68
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> repos: [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;owner/repo&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">],</span></span>
69
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> permissions: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;contents-write&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
70
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
71
+ <span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> onPullRequest</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: (</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">ctx</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">pr</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=&gt;</span></span>
72
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> pr.action </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">===</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;opened&quot;</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> ?</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { auth: </span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">defaultGitHubAuth</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(ctx) } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> null</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
73
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p>Default stream events drive the lifecycle:</p><table tabindex="0"><thead><tr><th>Event</th><th>Commit status</th><th>Banner</th></tr></thead><tbody><tr><td><code>turn.started</code></td><td><code>pending</code></td><td>create (or keep) the sticky comment</td></tr><tr><td><code>turn.completed</code></td><td><code>success</code></td><td>PATCH the same comment</td></tr><tr><td><code>turn.failed</code> / <code>session.failed</code></td><td><code>failure</code></td><td>PATCH the same comment</td></tr></tbody></table><p>Omit <code>commitStatus</code> / <code>banner</code>, or set them to <code>false</code>, to keep today&#39;s behavior. Reactions still default on; set <code>reactions: false</code> when the eyes emoji is noise. Descriptions are optional; defaults derive from <code>botName</code> or the status <code>context</code>.</p><p>Commit status posts to <code>channel.state.headSha</code>. PR and CI wakes seed and refresh it (<code>refreshState</code> on continuation). A first wake that is only an <code>issue_comment</code> has no head SHA in the payload, so status is skipped until a PR/CI wake stores one; the banner still posts. Review-comment wakes carry <code>pull_request.head.sha</code> when GitHub includes it.</p><p>The sticky comment id lives on durable <code>GitHubChannelState</code> (session record). Each wake also passes <code>refreshState</code> so <code>headSha</code> / refs update on continuation without wiping that id. Persist other derived state with <code>ctx.host.kv</code> or <code>ctx.host.files</code>. <code>stateRoot</code> resets on hosted replace.</p><p>Override <code>events</code> when the mapping is custom. <a href="./../example-agents/approval-buddy.html">Approval Buddy</a> posts commit status from <code>turn.started</code> / <code>action.result</code> / <code>turn.failed</code> and stays never-red; that pattern still wins when you replace a default handler key. Handlers you author replace the matching defaults (same as <code>progress.reactions</code> composition today).</p><h2 id="related" tabindex="-1">Related <a class="header-anchor" href="#related" aria-label="Permalink to &quot;Related&quot;">​</a></h2><ul><li><a href="./webhooks.html">Webhooks and custom channels</a>: the HTTP mechanism under this pack</li><li><a href="./../evals.html">Evals</a>: turn replay snapshots into regression fixtures</li><li><a href="./cloud-runtime.html">Cloud runtime</a>: attach PRs to cloud VMs</li><li><a href="./../reference/hooks.html">Hooks</a>: observe-only; use channel <code>progress</code> for GitHub surfaces</li></ul></div></div></main><footer class="VPDocFooter" data-v-d5d7ccd1 data-v-a5908b0f><!--[--><!--]--><!----><nav class="prev-next" aria-labelledby="doc-footer-aria-label" data-v-a5908b0f><span class="visually-hidden" id="doc-footer-aria-label" data-v-a5908b0f>Pager</span><div class="pager" data-v-a5908b0f><a class="VPLink link pager-link prev" href="/docs/guides/webhooks.html" data-v-a5908b0f><!--[--><span class="desc" data-v-a5908b0f>Previous page</span><span class="title" data-v-a5908b0f>Webhooks & custom channels</span><!--]--></a></div><div class="pager" data-v-a5908b0f><a class="VPLink link pager-link next" href="/docs/guides/slack.html" data-v-a5908b0f><!--[--><span class="desc" data-v-a5908b0f>Next page</span><span class="title" data-v-a5908b0f>Slack</span><!--]--></a></div></nav></footer><!--[--><!--]--></div></div></div><!--[--><!--]--></div></div><!----><!--[--><!--]--></div></div>
74
+ <script>window.__VP_HASH_MAP__=JSON.parse("{\"ab.md\":\"hdxsvX5M\",\"building-with-agents.md\":\"PeZaZA1P\",\"concepts.md\":\"CqOsxbMU\",\"deployment.md\":\"Cdp4rTE4\",\"evals.md\":\"qeoGgPw0\",\"example-agents_approval-buddy.md\":\"CIiZ9coo\",\"example-agents_benny.md\":\"l7JTmm8X\",\"example-agents_bugbot.md\":\"Dp5JqHSQ\",\"example-agents_codebase-wiki.md\":\"D-lteFf0\",\"example-agents_codeowners-review.md\":\"BU2ZXLf-\",\"example-agents_concierge.md\":\"DA2al_NK\",\"example-agents_fsd.md\":\"DPz9ezO4\",\"example-agents_index.md\":\"xmJ87d_3\",\"example-agents_knowledge-base.md\":\"IneynQSR\",\"example-agents_oncall.md\":\"ZE0n6ZFN\",\"example-agents_security-reviewer.md\":\"Dkf1gyo6\",\"example-agents_slack-agent.md\":\"06jQXTAI\",\"example-agents_weather-agent.md\":\"DC3lINjo\",\"guides_agent-to-agent.md\":\"Bmbxy-FA\",\"guides_cloud-runtime.md\":\"V5igN4Sq\",\"guides_github.md\":\"DSg0j9qj\",\"guides_human-in-the-loop.md\":\"BWvT7UqY\",\"guides_mcp-oauth.md\":\"C7G7IykG\",\"guides_opentelemetry.md\":\"DmyUwC5R\",\"guides_slack.md\":\"zriQpU_9\",\"guides_webhooks.md\":\"DB-r_er9\",\"hillclimbing.md\":\"yXqdlv2R\",\"index.md\":\"CMc5FP7E\",\"quickstart.md\":\"rIbfahJM\",\"reference_agent-config.md\":\"CRmkoxd6\",\"reference_artifacts.md\":\"BGG4bZo-\",\"reference_channels.md\":\"MN8iDy8V\",\"reference_cli.md\":\"DqEqQpGn\",\"reference_connections.md\":\"CSQiNzre\",\"reference_hooks.md\":\"4cbRRIIu\",\"reference_http-api.md\":\"DGrw_wOu\",\"reference_instructions.md\":\"CgoV-YEb\",\"reference_playground.md\":\"CPZhfYaO\",\"reference_project-layout.md\":\"D3MdHM2z\",\"reference_prompt.md\":\"BaiweQxE\",\"reference_schedules.md\":\"gmfYzf_I\",\"reference_sessions.md\":\"DBVFi2Sx\",\"reference_skills.md\":\"B_jHN7JL\",\"reference_subagents.md\":\"DSrGLIuB\",\"reference_tools.md\":\"lSrsTxYJ\",\"scaffolding-agents.md\":\"mkc3B_ZW\",\"storage.md\":\"DcGSnIxX\",\"templates_triage.md\":\"CConZt1z\",\"troubleshooting.md\":\"CkgwmVI0\"}");window.__VP_SITE_DATA__=JSON.parse("{\"lang\":\"en-US\",\"dir\":\"ltr\",\"title\":\"Agent SDK\",\"description\":\"Filesystem-first framework for building and serving Cursor agents.\",\"base\":\"/docs/\",\"head\":[],\"router\":{\"prefetchLinks\":true},\"appearance\":true,\"themeConfig\":{\"nav\":[{\"text\":\"Quickstart\",\"link\":\"/quickstart\"},{\"text\":\"Guides\",\"link\":\"/guides/webhooks\"},{\"text\":\"Examples\",\"link\":\"/example-agents/\"},{\"text\":\"Reference\",\"link\":\"/reference/project-layout\"}],\"search\":{\"provider\":\"local\"},\"outline\":{\"level\":[2,3]},\"sidebar\":[{\"text\":\"Getting started\",\"items\":[{\"text\":\"Overview\",\"link\":\"/\"},{\"text\":\"Quickstart\",\"link\":\"/quickstart\"},{\"text\":\"Scaffold an agent with Cursor\",\"link\":\"/scaffolding-agents\"},{\"text\":\"Concepts\",\"link\":\"/concepts\"}]},{\"text\":\"Templates\",\"items\":[{\"text\":\"Triage agent\",\"link\":\"/templates/triage\"}]},{\"text\":\"Improving agents\",\"items\":[{\"text\":\"Building agents with agents\",\"link\":\"/building-with-agents\"},{\"text\":\"Evals\",\"link\":\"/evals\"},{\"text\":\"Live A/B metrics\",\"link\":\"/ab\"},{\"text\":\"Storage\",\"link\":\"/storage\"},{\"text\":\"Hillclimbing\",\"link\":\"/hillclimbing\"}]},{\"text\":\"Guides\",\"items\":[{\"text\":\"Webhooks & custom channels\",\"link\":\"/guides/webhooks\"},{\"text\":\"GitHub\",\"link\":\"/guides/github\"},{\"text\":\"Slack\",\"link\":\"/guides/slack\"},{\"text\":\"Human-in-the-loop approvals\",\"link\":\"/guides/human-in-the-loop\"},{\"text\":\"Agent-to-agent\",\"link\":\"/guides/agent-to-agent\"},{\"text\":\"Host MCP OAuth\",\"link\":\"/guides/mcp-oauth\"},{\"text\":\"Cloud runtime\",\"link\":\"/guides/cloud-runtime\"},{\"text\":\"OpenTelemetry\",\"link\":\"/guides/opentelemetry\"}]},{\"text\":\"Example agents\",\"items\":[{\"text\":\"Choose an example\",\"link\":\"/example-agents/\"},{\"text\":\"Weather agent\",\"link\":\"/example-agents/weather-agent\"},{\"text\":\"Slack agent\",\"link\":\"/example-agents/slack-agent\"},{\"text\":\"Concierge\",\"link\":\"/example-agents/concierge\"},{\"text\":\"Playbook router\",\"link\":\"/example-agents/benny\"},{\"text\":\"Alert investigator\",\"link\":\"/example-agents/oncall\"},{\"text\":\"PR evidence reviewer\",\"link\":\"/example-agents/bugbot\"},{\"text\":\"Approval Buddy\",\"link\":\"/example-agents/approval-buddy\"},{\"text\":\"Security Reviewer\",\"link\":\"/example-agents/security-reviewer\"},{\"text\":\"Remote PR coordinator\",\"link\":\"/example-agents/fsd\"},{\"text\":\"Knowledge base\",\"link\":\"/example-agents/knowledge-base\"},{\"text\":\"Codebase wiki\",\"link\":\"/example-agents/codebase-wiki\"},{\"text\":\"Codeowners review\",\"link\":\"/example-agents/codeowners-review\"}]},{\"text\":\"Operating\",\"items\":[{\"text\":\"Deployment\",\"link\":\"/deployment\"},{\"text\":\"Fix common problems\",\"link\":\"/troubleshooting\"}]},{\"text\":\"Reference\",\"collapsed\":false,\"items\":[{\"text\":\"Project layout\",\"link\":\"/reference/project-layout\"},{\"text\":\"Agent config\",\"link\":\"/reference/agent-config\"},{\"text\":\"Instructions\",\"link\":\"/reference/instructions\"},{\"text\":\"Tools\",\"link\":\"/reference/tools\"},{\"text\":\"prompt\",\"link\":\"/reference/prompt\"},{\"text\":\"Skills\",\"link\":\"/reference/skills\"},{\"text\":\"MCP Connections\",\"link\":\"/reference/connections\"},{\"text\":\"Subagents\",\"link\":\"/reference/subagents\"},{\"text\":\"Channels\",\"link\":\"/reference/channels\"},{\"text\":\"Schedules & reminders\",\"link\":\"/reference/schedules\"},{\"text\":\"Hooks\",\"link\":\"/reference/hooks\"},{\"text\":\"Artifacts\",\"link\":\"/reference/artifacts\"},{\"text\":\"Sessions & streaming\",\"link\":\"/reference/sessions\"},{\"text\":\"Playground\",\"link\":\"/reference/playground\"},{\"text\":\"CLI\",\"link\":\"/reference/cli\"},{\"text\":\"HTTP API\",\"link\":\"/reference/http-api\"}]}]},\"locales\":{},\"scrollOffset\":134,\"cleanUrls\":false}");</script>
49
75
 
50
76
  </body>
51
77
  </html>