@cursor/july 0.1.42 → 0.1.45

package/dist/docs/assets/guides_opentelemetry.md.Csn7ZI25.js

@@ -0,0 +1,27 @@
+import{_ as s,c as t,o as a,ag as o}from"./chunks/framework.CAZyNGu9.js";const k=JSON.parse('{"title":"OpenTelemetry","description":"Push session, turn, and tool traces from the serve process to an OTLP collector you run.","frontmatter":{"title":"OpenTelemetry","description":"Push session, turn, and tool traces from the serve process to an OTLP collector you run."},"headers":[],"relativePath":"guides/opentelemetry.md","filePath":"guides/opentelemetry.md"}'),n={name:"guides/opentelemetry.md"};function i(r,e,l,d,p,c){return a(),t("div",null,[...e[0]||(e[0]=[o(`<h1 id="opentelemetry" tabindex="-1">OpenTelemetry <a class="header-anchor" href="#opentelemetry" aria-label="Permalink to &quot;OpenTelemetry&quot;">​</a></h1><p>Agent SDK can push traces, metrics, and logs from the serve process to an OTLP collector you run. Point the process at the collector with standard <code>OTEL_EXPORTER_OTLP_*</code> env, or author <code>agent/otel.ts</code>. Traces cover the inbound request, the session, each turn, and every tool call.</p><p>Export is opt-in. Nothing leaves the process until you set an endpoint or a <code>defineOtel</code> config.</p><h2 id="what-does-agent-sdk-export" tabindex="-1">What does Agent SDK export? <a class="header-anchor" href="#what-does-agent-sdk-export" aria-label="Permalink to &quot;What does Agent SDK export?&quot;">​</a></h2><table tabindex="0"><thead><tr><th>Signal</th><th>Default</th><th>What you get</th></tr></thead><tbody><tr><td>Traces</td><td>on</td><td><code>agent_sdk.http</code> → <code>agent_sdk.session</code> → <code>agent_sdk.turn</code> → <code>agent_sdk.tool</code> / <code>agent_sdk.subagent</code></td></tr><tr><td>Metrics</td><td>on</td><td><code>cursor.token.usage</code>, <code>cursor.tool.calls</code>, <code>cursor.cost.usage</code>, plus <code>agent_sdk.*</code> session and turn counts</td></tr><tr><td>Logs</td><td>off</td><td>Session events as log records. Prompt text, tool payloads, and failure messages stay off unless you opt in</td></tr></tbody></table><p>Turn off a signal with <code>traces: false</code>, <code>metrics: false</code>, or <code>logs: false</code> on <code>defineOtel</code>. Logs also turn on when you set <code>OTEL_LOGS_EXPORTER</code> to anything other than <code>none</code>, or when you set the content flags below.</p><h2 id="how-do-i-turn-opentelemetry-export-on" tabindex="-1">How do I turn OpenTelemetry export on? <a class="header-anchor" href="#how-do-i-turn-opentelemetry-export-on" aria-label="Permalink to &quot;How do I turn OpenTelemetry export on?&quot;">​</a></h2><p>Set a collector URL in the serve process environment:</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:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> OTEL_EXPORTER_OTLP_ENDPOINT</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">https://otel.example.com</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> OTEL_EXPORTER_OTLP_HEADERS</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Authorization=Bearer …&quot;</span></span></code></pre></div><p>The default wire format is OTLP/HTTP protobuf. That matches <a href="https://cursor.com/docs/enterprise/opentelemetry-export" target="_blank" rel="noreferrer">Cursor enterprise OpenTelemetry Export</a>. Set <code>OTEL_EXPORTER_OTLP_PROTOCOL=http/json</code> when your collector only accepts JSON. The runtime accepts <code>http/protobuf</code> and <code>http/json</code>. <code>grpc</code> falls back to protobuf and logs a warning.</p><p><code>OTEL_EXPORTER_OTLP_ENDPOINT</code> is the base URL. The runtime appends <code>/v1/traces</code>, <code>/v1/metrics</code>, and <code>/v1/logs</code>. If you pass a signal path, it is stripped back to the base first.</p><p>To send each signal to a different collector, omit the base URL and set the per-signal vars:</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:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> OTEL_EXPORTER_OTLP_TRACES_ENDPOINT</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">https://traces.example.com/v1/traces</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> OTEL_EXPORTER_OTLP_METRICS_ENDPOINT</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">https://metrics.example.com/v1/metrics</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> OTEL_EXPORTER_OTLP_LOGS_ENDPOINT</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">https://logs.example.com/v1/logs</span></span></code></pre></div><p>Optional:</p><table tabindex="0"><thead><tr><th>Variable</th><th>Effect</th></tr></thead><tbody><tr><td><code>OTEL_SERVICE_NAME</code></td><td>Resource <code>service.name</code>. Default <code>cursor</code></td></tr><tr><td><code>OTEL_LOG_USER_PROMPTS=1</code></td><td>Include user prompt text on logs and span events</td></tr><tr><td><code>OTEL_LOG_TOOL_CONTENT=1</code></td><td>Include tool payloads and failure text (truncated)</td></tr></tbody></table><p><code>serve(dir, { otel: false })</code> turns export off even when env or <code>agent/otel.ts</code> is set.</p><h2 id="how-do-i-author-agent-otel-ts" tabindex="-1">How do I author <code>agent/otel.ts</code>? <a class="header-anchor" href="#how-do-i-author-agent-otel-ts" aria-label="Permalink to &quot;How do I author \`agent/otel.ts\`?&quot;">​</a></h2><p>Use <code>defineOtel</code> when you want the collector URL, headers, or sampling in the project instead of the environment:</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;"> { defineOtel } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/july/otel&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
+<span class="line"></span>
+<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;"> defineOtel</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  serviceName: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;cursor&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  exporters: [</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    {</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      url: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;https://otel.example.com&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      protocol: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;http/protobuf&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      headers: { Authorization: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Bearer …&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    },</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  ],</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p>Multiple <code>exporters</code> fan out to every destination. Restrict one destination with <code>signals: [&quot;traces&quot;]</code>.</p><p>You can also pass the same object to <code>serve(dir, { otel })</code>. Precedence is <code>serve({ otel })</code> over <code>agent/otel.ts</code> over env. An empty <code>defineOtel()</code> still enables export when <code>OTEL_EXPORTER_OTLP_*</code> is set.</p><p>The companion skill is <a href="./../../skills/otel/SKILL.html"><code>skills/otel/SKILL.md</code></a>.</p><h2 id="what-spans-does-a-session-produce" tabindex="-1">What spans does a session produce? <a class="header-anchor" href="#what-spans-does-a-session-produce" aria-label="Permalink to &quot;What spans does a session produce?&quot;">​</a></h2><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>agent_sdk.http          inbound channel request (W3C traceparent)</span></span>
+<span class="line"><span>  └─ agent_sdk.session  cursor.conversation.id = session id</span></span>
+<span class="line"><span>       └─ agent_sdk.turn</span></span>
+<span class="line"><span>            ├─ agent_sdk.tool</span></span>
+<span class="line"><span>            └─ agent_sdk.subagent</span></span>
+<span class="line"><span>                 └─ agent_sdk.tool</span></span></code></pre></div><p>Inbound HTTP extracts W3C <code>traceparent</code>, so a channel request parents the session span when the turn starts in that request. Turns that resume after restore, or a direct <code>callTool</code> with no <code>turn.started</code> in this process, open a synthetic turn span so tool calls still nest.</p><h2 id="which-attributes-land-on-the-wire" tabindex="-1">Which attributes land on the wire? <a class="header-anchor" href="#which-attributes-land-on-the-wire" aria-label="Permalink to &quot;Which attributes land on the wire?&quot;">​</a></h2><p>Every signal carries these resource attributes:</p><ul><li><code>service.name</code> (<code>cursor</code> unless you override it)</li><li><code>cursor.entrypoint=sdk_ts</code></li><li><code>cursor.surface=unspecified</code></li><li><code>agent_sdk.framework=@cursor/july</code></li></ul><p>Shared names (same keys as enterprise export):</p><ul><li><code>cursor.conversation.id</code>: the session id</li><li><code>cursor.model.name</code></li><li><code>cursor.token.usage</code> with <code>cursor.token.type</code> of <code>input</code>, <code>output</code>, <code>cache_read</code>, <code>cache_creation</code>, or <code>reasoning</code></li><li><code>cursor.tool.calls</code> with <code>cursor.tool.name</code>, <code>cursor.tool.kind</code>, and <code>cursor.tool.status</code></li><li><code>cursor.cost.usage</code> (USD)</li></ul><p>Agent SDK only (<code>agent_sdk.*</code>): agent name, turn id, channel, call id, subagent name, session mode, and HTTP duration (<code>agent_sdk.http.duration</code>).</p><h2 id="how-do-i-emit-my-own-metrics" tabindex="-1">How do I emit my own metrics? <a class="header-anchor" href="#how-do-i-emit-my-own-metrics" aria-label="Permalink to &quot;How do I emit my own metrics?&quot;">​</a></h2><p><code>ctx.host.otel</code> is always present on tools, hooks, and channel handlers. Counters and histograms no-op when no meter is running. <code>setAttributes</code> still tags the open session when a collector is attached.</p><p>Prefix metric names with your team or agent. First-party names (<code>cursor.token.usage</code>, <code>cursor.tool.calls</code>, <code>cursor.cost.usage</code>, <code>agent_sdk.session.count</code>, <code>agent_sdk.turn.count</code>, <code>agent_sdk.subagent.count</code>, <code>agent_sdk.http.duration</code>) and join keys (<code>cursor.conversation.id</code>, <code>agent_sdk.agent</code>, <code>agent_sdk.turn_id</code>, <code>agent_sdk.framework</code>) are reserved. Custom spans are not on this surface.</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:#24292E;--shiki-dark:#E1E4E8;">ctx.host.otel.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">setAttributes</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
+<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">  &quot;abc.ticket_id&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;INC-123&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">  &quot;abc.queue&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;p1&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">ctx.host.otel.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">increment</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;abc.ticket.resolved&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">);</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">ctx.host.otel.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">record</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;abc.approval.duration_ms&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">1420</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, {</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  outcome: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;approved&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p>A session-bound host (tools and hooks) adds <code>cursor.conversation.id</code> and <code>agent_sdk.agent</code> for you. Tags merge: later <code>setAttributes</code> calls paint open spans and later first-party metrics.</p><h2 id="what-stays-off-the-opentelemetry-wire" tabindex="-1">What stays off the OpenTelemetry wire? <a class="header-anchor" href="#what-stays-off-the-opentelemetry-wire" aria-label="Permalink to &quot;What stays off the OpenTelemetry wire?&quot;">​</a></h2><p>User prompts, tool arguments, tool results, and failure messages are omitted by default. Failure spans still record an error status with a generic message (<code>turn failed</code> / <code>session failed</code>).</p><p>Opt in with <code>OTEL_LOG_USER_PROMPTS=1</code> and <code>OTEL_LOG_TOOL_CONTENT=1</code>, or the matching <code>logs: { userPrompts, toolContent }</code> fields on <code>defineOtel</code>. Opted-in strings truncate at 2,048 characters.</p><p>Deployment URLs from <code>agent.bound</code> stay off spans unless <code>toolContent</code> is on.</p><h2 id="how-does-agent-sdk-export-relate-to-cursor-enterprise-export" tabindex="-1">How does Agent SDK export relate to Cursor enterprise export? <a class="header-anchor" href="#how-does-agent-sdk-export-relate-to-cursor-enterprise-export" aria-label="Permalink to &quot;How does Agent SDK export relate to Cursor enterprise export?&quot;">​</a></h2><p><a href="https://cursor.com/docs/enterprise/opentelemetry-export" target="_blank" rel="noreferrer">Cursor enterprise OpenTelemetry Export</a> is the team-admin path. Cursor servers send org-wide metrics and logs to a collector you configure in Team Settings.</p><p>Agent SDK export is the process-local path. The serve process sends per-run traces, and optional metrics and logs, to a collector you point it at.</p><p>Point both at the same collector when you want one view. Group on <code>cursor.conversation.id</code>. Resource defaults (<code>service.name=cursor</code>, <code>cursor.entrypoint=sdk_ts</code>) keep the streams next to each other. The <a href="https://cursor.com/docs/enterprise/opentelemetry-export/wire" target="_blank" rel="noreferrer">wire reference</a> lists the shared attribute names.</p><p>Evals (<code>defineEval</code>) stay the in-product regression check. OpenTelemetry is the graph in your observability stack.</p><h2 id="what-if-another-opentelemetry-sdk-is-already-running" tabindex="-1">What if another OpenTelemetry SDK is already running? <a class="header-anchor" href="#what-if-another-opentelemetry-sdk-is-already-running" aria-label="Permalink to &quot;What if another OpenTelemetry SDK is already running?&quot;">​</a></h2><p>OTel providers are process-global. If Cursor CLI, an extension host, or another library already registered a TracerProvider, MeterProvider, or LoggerProvider, Agent SDK reuses it. Run <code>serve</code> as its own process when the Agent SDK exporters should own the destination.</p><p>Two mounts with different <code>agent/otel.ts</code> files fail at serve start. Use the same <code>defineOtel</code> config on every mount, or configure once through <code>serve({ otel })</code> or env.</p><h2 id="what-s-next" tabindex="-1">What&#39;s next <a class="header-anchor" href="#what-s-next" aria-label="Permalink to &quot;What&#39;s next&quot;">​</a></h2><ul><li><a href="./../../skills/otel/SKILL.html"><code>skills/otel/SKILL.md</code></a>: compact <code>defineOtel</code> reference for coding agents</li><li><a href="./../reference/hooks.html">Hooks</a>: observe the same session event stream in-process</li><li><a href="./../deployment.html">Deployment</a>: env, secrets, and self-hosting</li><li><a href="https://cursor.com/docs/enterprise/opentelemetry-export" target="_blank" rel="noreferrer">Cursor enterprise OpenTelemetry Export</a></li></ul>`,50)])])}const u=s(n,[["render",i]]);export{k as __pageData,u as default};

package/dist/docs/assets/guides_opentelemetry.md.Csn7ZI25.lean.js

@@ -0,0 +1 @@
+import{_ as s,c as t,o as a,ag as o}from"./chunks/framework.CAZyNGu9.js";const k=JSON.parse('{"title":"OpenTelemetry","description":"Push session, turn, and tool traces from the serve process to an OTLP collector you run.","frontmatter":{"title":"OpenTelemetry","description":"Push session, turn, and tool traces from the serve process to an OTLP collector you run."},"headers":[],"relativePath":"guides/opentelemetry.md","filePath":"guides/opentelemetry.md"}'),n={name:"guides/opentelemetry.md"};function i(r,e,l,d,p,c){return a(),t("div",null,[...e[0]||(e[0]=[o("",50)])])}const u=s(n,[["render",i]]);export{k as __pageData,u as default};

package/dist/docs/assets/index.md.COeoSkcF.js

@@ -0,0 +1,5 @@
+import{_ as a,c as t,o as s,ag as i}from"./chunks/framework.CAZyNGu9.js";const g=JSON.parse('{"title":"Agent SDK documentation","description":"Build and run Cursor agents with tools, approvals, channels, and evals.","frontmatter":{"title":"Agent SDK documentation","description":"Build and run Cursor agents with tools, approvals, channels, and evals."},"headers":[],"relativePath":"index.md","filePath":"README.md"}'),n={name:"index.md"};function l(r,e,o,h,d,c){return s(),t("div",null,[...e[0]||(e[0]=[i(`<h1 id="agent-sdk-documentation" tabindex="-1">Agent SDK documentation <a class="header-anchor" href="#agent-sdk-documentation" aria-label="Permalink to &quot;Agent SDK documentation&quot;">​</a></h1><p>Use the Agent SDK to define Cursor agents in TypeScript and Markdown. See <a href="./reference/project-layout.html">Project layout</a> for the directory structure.</p><p>Use Node 22.13 or newer. Bun isn&#39;t supported.</p><p>Create a project:</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;">npx</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> @cursor/july</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> init</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> ./my-agent</span></span>
+<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">cd</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> my-agent</span></span>
+<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> dev</span></span></code></pre></div><p>If <code>agent-sdk</code> isn&#39;t on <code>PATH</code>, use <code>npx @cursor/july &lt;command&gt;</code>.</p><p>Open the docs locally:</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;">npx</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> @cursor/july</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> docs</span></span></code></pre></div><h2 id="where-to-start" tabindex="-1">Where to start <a class="header-anchor" href="#where-to-start" aria-label="Permalink to &quot;Where to start&quot;">​</a></h2><table tabindex="0"><thead><tr><th>You are...</th><th>Start with</th></tr></thead><tbody><tr><td>New to the Agent SDK</td><td><a href="./quickstart.html">Quickstart</a> (PR reviewer), then <a href="./concepts.html">Concepts</a></td></tr><tr><td>Building a new agent with Cursor</td><td><a href="./scaffolding-agents.html">Scaffold an agent with Cursor</a></td></tr><tr><td>Learning from working agents</td><td><a href="./example-agents/">Example agents</a></td></tr><tr><td>Wiring an agent to Slack</td><td><a href="./guides/slack.html">Slack guide</a></td></tr><tr><td>Wiring an agent to GitHub webhooks</td><td><a href="./guides/github.html">GitHub guide</a></td></tr><tr><td>Driving an agent from Linear (or another tracker)</td><td><a href="./guides/webhooks.html#example-linear-as-the-control-plane">Webhooks guide: Linear example</a></td></tr><tr><td>Making an existing agent measurably better</td><td><a href="./evals.html">Evals</a>, then <a href="./hillclimbing.html">Hillclimbing</a></td></tr><tr><td>Comparing variants on live traffic</td><td><a href="./ab.html">Live A/B metrics</a></td></tr><tr><td>Deploying with Cursor or on your own infrastructure</td><td><a href="./deployment.html">Deployment</a></td></tr><tr><td>Debugging something that misbehaves</td><td><a href="./troubleshooting.html">Fix common agent problems</a></td></tr></tbody></table><h2 id="documentation" tabindex="-1">Documentation <a class="header-anchor" href="#documentation" aria-label="Permalink to &quot;Documentation&quot;">​</a></h2><p><strong>Core</strong></p><ul><li><a href="./quickstart.html">Quickstart</a>: build a PR reviewer that classifies changes by complexity and handles GitHub webhook events.</li><li><a href="./scaffolding-agents.html">Scaffold an agent with Cursor</a>: use the bundled skill for a guided build.</li><li><a href="./concepts.html">Concepts</a>: agent discovery, sessions, channels, runtimes, and observability.</li></ul><p><strong>Self-improving Agents</strong></p><ul><li><a href="./building-with-agents.html">Building agents with agents</a>: use a coding agent to scaffold, run, and iterate on your agent.</li><li><a href="./evals.html">Evals</a>: author <code>defineEval</code> cases, pick fixtures, and use evals as regression checks.</li><li><a href="./ab.html">Live A/B metrics</a>: assign sticky variants and compare cumulative metrics on live sessions.</li><li><a href="./storage.html">Storage</a>: point durable storage at a backend you own with <code>defineStorage</code>.</li><li><a href="./hillclimbing.html">Hillclimbing</a>: measure and improve an agent iteratively.</li></ul><p><strong>Guides</strong></p><ul><li><a href="./guides/webhooks.html">Webhooks and custom channels</a>: give the agent its own HTTP surface.</li><li><a href="./guides/github.html">GitHub</a>: trigger the agent from pull requests, CI, and comments.</li><li><a href="./guides/slack.html">Slack</a>: put the agent in Slack over Socket Mode.</li><li><a href="./guides/human-in-the-loop.html">Human-in-the-loop approvals</a>: park a tool call until a person signs off.</li><li><a href="./guides/mcp-oauth.html">Host MCP OAuth</a>: authorize <code>oauth: true</code> connections, store tokens locally, and <code>--store</code> them on hosted deployments.</li><li><a href="./guides/agent-to-agent.html">Agent-to-agent</a>: every agent is an MCP server; agents can delegate to each other.</li><li><a href="./guides/cloud-runtime.html">Cloud runtime</a>: run turns on Cursor cloud agents instead of the local harness.</li><li><a href="./guides/opentelemetry.html">OpenTelemetry</a>: push session, turn, and tool traces to an OTLP collector you run.</li></ul><p><strong>Example agents</strong></p><ul><li><a href="./example-agents/">Choose the right example</a>: compare all twelve agents by runtime, channels, tools, state, and architecture.</li><li><a href="./example-agents/weather-agent.html">Weather agent</a>: explore tools, MCP, approvals, skills, subagents, schedules, hooks, A/B metrics, and evals.</li><li><a href="./example-agents/slack-agent.html">Slack agent</a>: put a minimal agent in Slack through an account-linked transport.</li><li><a href="./example-agents/concierge.html">Concierge</a>: delegate work to a peer agent with its own context and sessions.</li><li><a href="./example-agents/benny.html">Playbook router</a>: route Slack intake through inherited repository playbooks.</li><li><a href="./example-agents/oncall.html">Alert investigator</a>: watch a Slack alerts channel and pin a self-rechecking investigation to every alert thread.</li><li><a href="./example-agents/bugbot.html">PR evidence reviewer</a>: review a host-prepared, diff-first pull-request evidence tree.</li><li><a href="./example-agents/approval-buddy.html">Approval Buddy</a>: keep approval policy in code while subagents supply review findings.</li><li><a href="./example-agents/security-reviewer.html">Security Reviewer</a>: run a staged, parallel security pipeline with live playground progress.</li><li><a href="./example-agents/fsd.html">Remote PR coordinator</a>: hand PR triage from local chat and webhooks to durable remote sessions.</li><li><a href="./example-agents/knowledge-base.html">Knowledge base</a>: turn conversations about people, systems, decisions, and preferences into shared markdown.</li><li><a href="./example-agents/codebase-wiki.html">Codebase wiki</a>: ingest merged PRs into per-feature pages with a daily digest schedule.</li><li><a href="./example-agents/codeowners-review.html">Codeowners review</a>: route PR reviews by ownership to per-area playbooks and aggregate verdicts.</li></ul><p><strong>Operating</strong></p><ul><li><a href="./deployment.html">Deployment</a>: Cursor-managed hosting, self-hosting, auth, state, and operations.</li><li><a href="./troubleshooting.html">Fix common agent problems</a>: diagnose common failures by symptom.</li></ul><p><strong>Reference</strong></p><ul><li><a href="./reference/project-layout.html">Project layout</a>: the full folder structure.</li><li><a href="./reference/agent-config.html">Agent config</a> · <a href="./reference/instructions.html">Instructions</a> · <a href="./reference/tools.html">Tools</a> · <a href="./reference/prompt.html"><code>prompt</code></a> · <a href="./reference/skills.html">Skills</a> · <a href="./reference/connections.html">MCP connections</a> · <a href="./reference/subagents.html">Subagents</a></li><li><a href="./reference/channels.html">Channels</a> · <a href="./reference/schedules.html">Schedules and reminders</a> · <a href="./reference/hooks.html">Hooks</a> · <a href="./reference/sessions.html">Sessions and streaming</a> · <a href="./reference/playground.html">Playground</a></li><li><a href="./reference/cli.html">CLI</a> · <a href="./reference/http-api.html">HTTP API</a></li></ul><h2 id="run-the-cli" tabindex="-1">Run the CLI <a class="header-anchor" href="#run-the-cli" aria-label="Permalink to &quot;Run the CLI&quot;">​</a></h2><p>Docs use <code>agent-sdk &lt;command&gt;</code>. If it isn&#39;t on <code>PATH</code>, use <code>npx @cursor/july &lt;command&gt;</code>.</p><p>From <code>packages/agent-serve</code> in a source checkout:</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:#D73A49;--shiki-dark:#F97583;">alias</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> agent-sdk</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;pnpm exec tsx </span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">$PWD</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">/src/bin/agent-serve.ts&quot;</span></span></code></pre></div><h2 id="credentials" tabindex="-1">Credentials <a class="header-anchor" href="#credentials" aria-label="Permalink to &quot;Credentials&quot;">​</a></h2><p>Sign in to Cursor or set <code>CURSOR_API_KEY</code>:</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;"> login</span></span>
+<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># or: export CURSOR_API_KEY=key_...</span></span>
+<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> whoami</span></span></code></pre></div><p>Confirm <code>agent-sdk whoami</code> shows the expected account.</p><h2 id="related-documentation" tabindex="-1">Related documentation <a class="header-anchor" href="#related-documentation" aria-label="Permalink to &quot;Related documentation&quot;">​</a></h2><ul><li>Package reference: <a href="./../README.html"><code>README.md</code></a></li><li>Coding-agent workflows: <a href="./../skills/"><code>skills/</code></a></li></ul>`,33)])])}const u=a(n,[["render",l]]);export{g as __pageData,u as default};

package/dist/docs/assets/index.md.COeoSkcF.lean.js

@@ -0,0 +1 @@
+import{_ as a,c as t,o as s,ag as i}from"./chunks/framework.CAZyNGu9.js";const g=JSON.parse('{"title":"Agent SDK documentation","description":"Build and run Cursor agents with tools, approvals, channels, and evals.","frontmatter":{"title":"Agent SDK documentation","description":"Build and run Cursor agents with tools, approvals, channels, and evals."},"headers":[],"relativePath":"index.md","filePath":"README.md"}'),n={name:"index.md"};function l(r,e,o,h,d,c){return s(),t("div",null,[...e[0]||(e[0]=[i("",33)])])}const u=a(n,[["render",l]]);export{g as __pageData,u as default};

package/dist/docs/assets/{quickstart.md.rIbfahJM.js → quickstart.md.DZxBu44y.js}

@@ -1,28 +1,6 @@
-import{_ as i,c as a,o as n,ag as t}from"./chunks/framework.CAZyNGu9.js";const o=JSON.parse('{"title":"Build your first PR approver","description":"Create an agent that reviews pull requests by complexity, approves the safe ones, and wakes from GitHub webhooks.","frontmatter":{"title":"Build your first PR approver","description":"Create an agent that reviews pull requests by complexity, approves the safe ones, and wakes from GitHub webhooks."},"headers":[],"relativePath":"quickstart.md","filePath":"quickstart.md"}'),e={name:"quickstart.md"};function h(l,s,p,k,r,d){return n(),a("div",null,[...s[0]||(s[0]=[t(`<h1 id="build-your-first-pr-approver" tabindex="-1">Build your first PR approver <a class="header-anchor" href="#build-your-first-pr-approver" aria-label="Permalink to &quot;Build your first PR approver&quot;">​</a></h1><p>Build an agent that reviews GitHub pull requests. It fetches the diff, rates the change&#39;s complexity in plain TypeScript, approves the safe ones, and flags the rest for a human. Then wire it to GitHub webhooks and watch a pull request wake it.</p><p>The split is the point of the exercise: deterministic policy lives in typed tools, judgment lives in the model, and every decision is inspectable in the playground.</p><h2 id="prerequisites" tabindex="-1">Prerequisites <a class="header-anchor" href="#prerequisites" aria-label="Permalink to &quot;Prerequisites&quot;">​</a></h2><p>You need:</p><ul><li>Node 22.13 or newer. Bun isn&#39;t supported.</li><li>The <code>agent-sdk</code> CLI. <code>npx @cursor/july init ./pr-approver</code> bootstraps it with no prior install: <code>init</code> scaffolds the project, runs <code>npm install</code>, links <code>agent-sdk</code> onto your PATH, and offers a Cursor sign-in. See <a href="/docs/#run-the-cli">Run the CLI</a> for other setups, such as a monorepo source checkout.</li><li>A Cursor credential for model turns. Sign in once:</li></ul><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;"> login</span></span></code></pre></div><p>You can also set <code>CURSOR_API_KEY</code> instead of signing in.</p><ul><li>A GitHub credential. <code>gh auth login</code> is enough, or set <code>GITHUB_TOKEN</code>. The tools you write resolve either one automatically. Reading pull requests works on any public repo; posting reviews needs write access to the repo you review.</li></ul><h2 id="first-run-in-10-minutes" tabindex="-1">First run in 10 minutes <a class="header-anchor" href="#first-run-in-10-minutes" aria-label="Permalink to &quot;First run in 10 minutes&quot;">​</a></h2><p>Want a working agent before the full tutorial? Four commands get you there:</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;">npx</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> @cursor/july</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> init</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> ./pr-approver</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">     # scaffold + npm install + PATH link + sign-in offer</span></span>
-<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">cd</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> pr-approver</span></span>
-<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> dev</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">                           # serve, and print the playground URL</span></span></code></pre></div><p>Open the playground URL and chat with the scaffold. Then, in a second terminal (<code>dev</code> keeps running), run one turn from the command line:</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;"> run</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;"> --message</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;Introduce yourself in one sentence.&quot;</span></span></code></pre></div><p>That&#39;s the whole loop: files become an agent, <code>dev</code> serves it, and <code>run</code> exercises it. The rest of this page turns that scaffold into a real PR approver.</p><h2 id="scaffolding-agents" tabindex="-1">Scaffolding Agents <a class="header-anchor" href="#scaffolding-agents" aria-label="Permalink to &quot;Scaffolding Agents&quot;">​</a></h2><p>Have Cursor read <a href="./../skills/create-agent/SKILL.html"><code>skills/create-agent/SKILL.md</code></a> and describe what you want:</p><blockquote><p>Build me a PR approver for the playground. Start with one tool that inspects a pull request and guide me through the remaining decisions.</p></blockquote><p>Cursor asks for missing choices, shows you the plan, then builds and verifies the agent. Continue below to do the same by hand.</p><p>See <a href="./scaffolding-agents.html">Scaffold an agent with Cursor</a> for the full guided workflow.</p><h2 id="create-your-project" tabindex="-1">Create your project <a class="header-anchor" href="#create-your-project" aria-label="Permalink to &quot;Create your project&quot;">​</a></h2><p>Start with the built-in scaffold:</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;">npx</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> @cursor/july</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> init</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> ./pr-approver</span></span>
-<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">cd</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> pr-approver</span></span>
-<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> dev</span></span></code></pre></div><p>The scaffold creates the files the Agent SDK discovers, plus empty capability folders (each with a <code>.gitkeep</code>) so you can drop tools, channels, and evals in place:</p><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>pr-approver/</span></span>
-<span class="line"><span>├── agent/</span></span>
-<span class="line"><span>│   ├── agent.ts</span></span>
-<span class="line"><span>│   ├── instructions.md</span></span>
-<span class="line"><span>│   ├── tools/</span></span>
-<span class="line"><span>│   │   └── echo.ts</span></span>
-<span class="line"><span>│   ├── skills/</span></span>
-<span class="line"><span>│   ├── mcp-connections/</span></span>
-<span class="line"><span>│   ├── subagents/</span></span>
-<span class="line"><span>│   ├── channels/</span></span>
-<span class="line"><span>│   ├── hooks/</span></span>
-<span class="line"><span>│   │   └── memory.ts</span></span>
-<span class="line"><span>│   ├── ab/</span></span>
-<span class="line"><span>│   ├── schedules/</span></span>
-<span class="line"><span>│   ├── sandbox/workspace/</span></span>
-<span class="line"><span>│   └── lib/</span></span>
-<span class="line"><span>├── evals/</span></span>
-<span class="line"><span>├── package.json</span></span>
-<span class="line"><span>└── tsconfig.json</span></span></code></pre></div><p><code>agent.ts</code> holds the model and runtime settings. <code>instructions.md</code> is the always-on system prompt, and the scaffold&#39;s version includes a memory section that tells the agent how to consult its journal. Each file under <code>agent/tools/</code> becomes a tool, and <code>agent/hooks/memory.ts</code> journals every turn so future sessions can recall past work (delete it to opt out). <code>tsconfig.json</code> type-checks the project (<code>npm run check</code>); the framework runs your TypeScript directly, so nothing compiles.</p><p><code>agent-sdk dev</code> blocks until you stop it. Keep it running and open a second terminal for every other command on this page, starting with these checks:</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;"> validate</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> .</span></span>
-<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> info</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> .</span></span></code></pre></div><p>These commands inspect the project without starting a model turn.</p><h2 id="run-your-agent" tabindex="-1">Run your agent <a class="header-anchor" href="#run-your-agent" aria-label="Permalink to &quot;Run your agent&quot;">​</a></h2><p>The scaffold already works. Run one turn from the terminal:</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;"> run</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;"> \\</span></span>
-<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  --message</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;Introduce yourself in one sentence.&quot;</span></span></code></pre></div><p><code>run</code> starts the agent, sends the message, and waits for the final reply. It prints a JSON trajectory with the response, tool calls, and token usage. It also writes an NDJSON trace under <code>.agent-serve/traces/</code>.</p><h2 id="teach-it-to-review" tabindex="-1">Teach it to review <a class="header-anchor" href="#teach-it-to-review" aria-label="Permalink to &quot;Teach it to review&quot;">​</a></h2><p>Replace <code>agent/instructions.md</code>:</p><div class="language-md vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">md</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#005CC5;--shiki-light-font-weight:bold;--shiki-dark:#79B8FF;--shiki-dark-font-weight:bold;"># PR approver</span></span>
+import{_ as i,c as a,o as n,ag as h}from"./chunks/framework.CAZyNGu9.js";const g=JSON.parse('{"title":"Build your first PR reviewer","description":"Create an agent that reviews pull requests by complexity, approves safe changes, and handles GitHub webhook events.","frontmatter":{"title":"Build your first PR reviewer","description":"Create an agent that reviews pull requests by complexity, approves safe changes, and handles GitHub webhook events."},"headers":[],"relativePath":"quickstart.md","filePath":"quickstart.md"}'),t={name:"quickstart.md"};function l(p,s,e,k,r,E){return n(),a("div",null,[...s[0]||(s[0]=[h(`<h1 id="build-your-first-pr-reviewer" tabindex="-1">Build your first PR reviewer <a class="header-anchor" href="#build-your-first-pr-reviewer" aria-label="Permalink to &quot;Build your first PR reviewer&quot;">​</a></h1><p>Build a GitHub PR reviewer that classifies changes as <code>trivial</code>, <code>moderate</code>, or <code>large</code>, then approves safe changes or requests human review. Add GitHub event handling so pull requests can trigger reviews.</p><h2 id="getting-started" tabindex="-1">Getting started <a class="header-anchor" href="#getting-started" aria-label="Permalink to &quot;Getting started&quot;">​</a></h2><ul><li><strong>Get started with an agent in Cursor:</strong> follow <a href="./scaffolding-agents.html">Scaffold an agent with Cursor</a> and ask Cursor to read <a href="./../skills/create-agent/SKILL.html"><code>skills/create-agent/SKILL.md</code></a>.</li><li><strong>Get started in the CLI:</strong> continue below.</li></ul><h2 id="prerequisites" tabindex="-1">Prerequisites <a class="header-anchor" href="#prerequisites" aria-label="Permalink to &quot;Prerequisites&quot;">​</a></h2><ul><li>Node 22.13 or newer. Bun isn&#39;t supported.</li><li>Run commands as <code>agent-sdk &lt;command&gt;</code>, or use <code>npx @cursor/july &lt;command&gt;</code> when the CLI isn&#39;t on <code>PATH</code>. See <a href="/docs/#run-the-cli">Run the CLI</a> for monorepo checkouts and other setups.</li><li>A Cursor credential for model turns. Sign in once:</li></ul><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;"> login</span></span></code></pre></div><p>You can also set <code>CURSOR_API_KEY</code> instead of signing in.</p><ul><li>Authenticate with <code>gh auth login</code> or <code>GITHUB_TOKEN</code>. You can read public pull requests. Posting reviews requires repository write access.</li></ul><h2 id="create-and-run-the-project" tabindex="-1">Create and run the project <a class="header-anchor" href="#create-and-run-the-project" aria-label="Permalink to &quot;Create and run the project&quot;">​</a></h2><p>Initialize the project and start the development server:</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;">npx</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> @cursor/july</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> init</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> ./sdk-pr-reviewer</span></span>
+<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">cd</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> sdk-pr-reviewer</span></span>
+<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> dev</span></span></code></pre></div><p>Keep <code>agent-sdk dev</code> running. In a second terminal, run:</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;"> run</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;"> --message</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;Introduce yourself in one sentence.&quot;</span></span></code></pre></div><p>Confirm the agent replies.</p><h2 id="add-review-instructions" tabindex="-1">Add review instructions <a class="header-anchor" href="#add-review-instructions" aria-label="Permalink to &quot;Add review instructions&quot;">​</a></h2><p>Replace <code>agent/instructions.md</code>:</p><div class="language-md vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">md</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#005CC5;--shiki-light-font-weight:bold;--shiki-dark:#79B8FF;--shiki-dark-font-weight:bold;"># PR reviewer</span></span>
 <span class="line"></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">You review GitHub pull requests. Be specific and brief.</span></span>
 <span class="line"></span>
@@ -42,7 +20,7 @@ import{_ as i,c as a,o as n,ag as t}from"./chunks/framework.CAZyNGu9.js";const o
 <span class="line"><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">3.</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> Never approve a draft. Point out anything surprising, even when you</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">   approve.</span></span>
 <span class="line"></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">End with one sentence: the verdict and why.</span></span></code></pre></div><p>Remove the demo echo tool:</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;">rm</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> agent/tools/echo.ts</span></span></code></pre></div><h2 id="add-a-shared-helper" tabindex="-1">Add a shared helper <a class="header-anchor" href="#add-a-shared-helper" aria-label="Permalink to &quot;Add a shared helper&quot;">​</a></h2><p>Both tools need to split a PR URL into its parts. Shared code lives in <code>agent/lib/</code>, which the framework never loads as tools.</p><p>Create <code>agent/lib/github.ts</code>:</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;"> interface</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> PullRef</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">End with one sentence: the verdict and why.</span></span></code></pre></div><p>Remove the demo echo tool:</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;">rm</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> agent/tools/echo.ts</span></span></code></pre></div><h2 id="add-a-shared-helper" tabindex="-1">Add a shared helper <a class="header-anchor" href="#add-a-shared-helper" aria-label="Permalink to &quot;Add a shared helper&quot;">​</a></h2><p>Create <code>agent/lib/github.ts</code>:</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;"> interface</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> PullRef</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
 <span class="line"><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">  owner</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> string</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
 <span class="line"><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">  repo</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> string</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
 <span class="line"><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">  number</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> number</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
@@ -63,7 +41,7 @@ import{_ as i,c as a,o as n,ag as t}from"./chunks/framework.CAZyNGu9.js";const o
 <span class="line"></span>
 <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> type</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> Complexity</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;trivial&quot;</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> |</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;moderate&quot;</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> |</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;large&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
 <span class="line"></span>
-<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">/** Deterministic policy: the tool rates the change, not the model. */</span></span>
+<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">/** Rate complexity from fixed line and file-count thresholds. */</span></span>
 <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">function</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> rateComplexity</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">linesChanged</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> number</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">changedFiles</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> number</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> Complexity</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
 <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">  if</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> (linesChanged </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;=</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> 25</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> &amp;&amp;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> changedFiles </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;=</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> 2</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) {</span></span>
 <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">    return</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;trivial&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
@@ -127,16 +105,9 @@ import{_ as i,c as a,o as n,ag as t}from"./chunks/framework.CAZyNGu9.js";const o
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      })),</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    };</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  },</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p>The file adds one tool named <code>inspect_pr</code>:</p><ul><li><code>description</code> tells the model when to call it.</li><li><code>inputSchema</code> defines and validates the arguments.</li><li><code>execute</code> runs on the server and returns data to the model.</li></ul><p>Two details carry the design. <code>rateComplexity</code> is the review policy, and it lives in code: the model never decides what counts as a big change. And <code>ctx.host.github</code> is the shared host GitHub client, so the tool inherits whatever credential the host has (a token, <code>gh auth</code>, or a GitHub App) without parsing any of it.</p><h2 id="try-the-inspect-tool" tabindex="-1">Try the inspect tool <a class="header-anchor" href="#try-the-inspect-tool" aria-label="Permalink to &quot;Try the inspect tool&quot;">​</a></h2><p>Call the tool directly first, on a real merged pull request:</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;"> call</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> inspect_pr</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;"> \\</span></span>
-<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  --input</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &#39;{&quot;prUrl&quot;:&quot;https://github.com/facebook/react/pull/35623&quot;}&#39;</span></span></code></pre></div><p><code>call</code> validates the input and runs <code>execute</code> without a model turn. This PR is a one-character typo fix, so the result comes back rated <code>trivial</code> with the whole patch inline:</p><div class="language-json vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">json</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">{</span></span>
-<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  &quot;title&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Fix typo: accomodate -&gt; accommodate&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
-<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  &quot;additions&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">1</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
-<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  &quot;deletions&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">1</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
-<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  &quot;changedFiles&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">1</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
-<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  &quot;complexity&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;trivial&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
-<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  &quot;files&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: [{ </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">&quot;path&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;compiler/packages/...&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">&quot;patch&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;@@ -1315,7 ...&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }]</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><p>Now call it on the PR that added <code>experimental_useEvent</code> to React: 1,027 additions across 26 files.</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;"> call</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> inspect_pr</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;"> \\</span></span>
-<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  --input</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &#39;{&quot;prUrl&quot;:&quot;https://github.com/facebook/react/pull/25229&quot;}&#39;</span></span></code></pre></div><p>The rating flips to <code>large</code> and the patches disappear from the result. The policy in the tool decides how much the model gets to see, before any model turn spends a token on it.</p><h2 id="add-the-review-tool" tabindex="-1">Add the review tool <a class="header-anchor" href="#add-the-review-tool" aria-label="Permalink to &quot;Add the review tool&quot;">​</a></h2><p>The approver needs a way to act on its verdict. Create <code>agent/tools/submit_review.ts</code>:</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;"> { defineTool } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/july/tools&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><h2 id="verify-complexity-classification" tabindex="-1">Verify complexity classification <a class="header-anchor" href="#verify-complexity-classification" aria-label="Permalink to &quot;Verify complexity classification&quot;">​</a></h2><p>Run <code>inspect_pr</code> against a small pull request:</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;"> call</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> inspect_pr</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;"> \\</span></span>
+<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  --input</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &#39;{&quot;prUrl&quot;:&quot;https://github.com/facebook/react/pull/35623&quot;}&#39;</span></span></code></pre></div><p>Confirm the result contains <code>&quot;complexity&quot;: &quot;trivial&quot;</code>.</p><p>Run it against a large pull request:</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;"> call</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> inspect_pr</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;"> \\</span></span>
+<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  --input</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &#39;{&quot;prUrl&quot;:&quot;https://github.com/facebook/react/pull/25229&quot;}&#39;</span></span></code></pre></div><p>Confirm the result contains <code>&quot;complexity&quot;: &quot;large&quot;</code> and no <code>patch</code> fields.</p><h2 id="add-the-review-tool" tabindex="-1">Add the review tool <a class="header-anchor" href="#add-the-review-tool" aria-label="Permalink to &quot;Add the review tool&quot;">​</a></h2><p>Create <code>agent/tools/submit_review.ts</code> to post each verdict:</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;"> { defineTool } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/july/tools&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
 <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { z } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;zod&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
 <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { parsePullUrl } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;../lib/github.js&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
 <span class="line"></span>
@@ -156,10 +127,10 @@ import{_ as i,c as a,o as n,ag as t}from"./chunks/framework.CAZyNGu9.js";const o
 <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">    const</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">owner</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">repo</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">number</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> parsePullUrl</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(prUrl);</span></span>
 <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">    const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> review</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      verdict </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">===</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;approve&quot;</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">        ?</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { event: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;APPROVE&quot;</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> as</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> const</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, body: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">\`PR approver: \${</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">summary</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">}\`</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">        ?</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { event: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;APPROVE&quot;</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> as</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> const</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, body: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">\`PR reviewer: \${</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">summary</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">}\`</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span>
 <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">        :</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">            event: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;COMMENT&quot;</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> as</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> const</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">            body: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">\`PR approver: this change needs a human review. \${</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">summary</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">}\`</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">            body: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">\`PR reviewer: this change needs a human review. \${</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">summary</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">}\`</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">          };</span></span>
 <span class="line"></span>
 <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">    const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> octokit</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> await</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> ctx.host.github.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">getOctokit</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">();</span></span>
@@ -172,8 +143,8 @@ import{_ as i,c as a,o as n,ag as t}from"./chunks/framework.CAZyNGu9.js";const o
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    });</span></span>
 <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">    return</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { posted: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">true</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">...</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">review };</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  },</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p>The tool posts a real review: an APPROVE when the agent approves, a comment asking for a human otherwise. Two GitHub rules shape how you test it. Your credential needs write access to the repo it reviews, and GitHub rejects approving your own pull request, so hand the agent a teammate&#39;s PR rather than one you authored. When a post fails, the tool call reports the GitHub error to the model and the turn keeps going.</p><p>Want a person to sign off before the review lands? Set <code>needsApproval: true</code> on the tool and the call parks until someone approves it from the playground or Slack. <a href="./guides/human-in-the-loop.html">Human-in-the-loop approvals</a> shows the flow.</p><h2 id="review-a-pull-request" tabindex="-1">Review a pull request <a class="header-anchor" href="#review-a-pull-request" aria-label="Permalink to &quot;Review a pull request&quot;">​</a></h2><p>Run the whole loop on a pull request your credential can review. A teammate&#39;s open PR is the right pick: write access to the repo, and not authored by you.</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;"> run</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;"> \\</span></span>
-<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  --message</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;Review https://github.com/acme/checkout/pull/42&quot;</span></span></code></pre></div><p>The trajectory shows two tool calls. The agent inspects the PR, reads the patches, and submits its verdict. A small, clean change gets an APPROVE review on the spot, with a one-line summary of what it checked. A large one gets a comment asking for a human review, pointing at the files a reviewer should start with. Same instructions, different behavior, because the policy in the tool decided how much the model got to see.</p><p>Open the PR on GitHub: the review is on the timeline, posted by whatever identity your credential belongs to.</p><h2 id="wake-it-from-github" tabindex="-1">Wake it from GitHub <a class="header-anchor" href="#wake-it-from-github" aria-label="Permalink to &quot;Wake it from GitHub&quot;">​</a></h2><p>A reviewer you have to prompt is only half useful. Give the agent a GitHub channel so pull requests wake it. Create <code>agent/channels/github.ts</code>:</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;"> {</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p>Use a GitHub credential with write access and a pull request you didn&#39;t author.</p><h2 id="review-a-pull-request" tabindex="-1">Review a pull request <a class="header-anchor" href="#review-a-pull-request" aria-label="Permalink to &quot;Review a pull request&quot;">​</a></h2><p>Review an open pull request:</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;"> run</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;"> \\</span></span>
+<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  --message</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;Review https://github.com/acme/checkout/pull/42&quot;</span></span></code></pre></div><p>Confirm <code>inspect_pr</code> runs before <code>submit_review</code>, then verify the review on GitHub.</p><h2 id="trigger-reviews-from-github" tabindex="-1">Trigger reviews from GitHub <a class="header-anchor" href="#trigger-reviews-from-github" aria-label="Permalink to &quot;Trigger reviews from GitHub&quot;">​</a></h2><p>Create <code>agent/channels/github.ts</code>:</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;"> {</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  defaultGitHubAuth,</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  githubChannel,</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">} </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>
@@ -181,10 +152,8 @@ import{_ as i,c as a,o as n,ag as t}from"./chunks/framework.CAZyNGu9.js";const o
 <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> REVIEW_ACTIONS</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> new</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> Set</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">([</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;opened&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;reopened&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;ready_for_review&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">]);</span></span>
 <span class="line"></span>
 <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>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  botName: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;pr-approver&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  botName: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;sdk-pr-reviewer&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  webhookEvents: [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;pull_request&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">],</span></span>
-<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">  // submit_review owns every GitHub write. Without these flags the channel</span></span>
-<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">  // also posts chat replies and reactions to the PR when the token allows it.</span></span>
 <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>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  progress: { reactions: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">false</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
 <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 style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
@@ -200,8 +169,8 @@ import{_ as i,c as a,o as n,ag as t}from"./chunks/framework.CAZyNGu9.js";const o
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      ],</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    };</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  },</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p>The channel mounts <code>POST /v1/channels/github</code> and dispatches on the <code>pull_request</code> events you declared. Opened, reopened, and undrafted PRs start a model turn; everything else returns <code>null</code> and is skipped.</p><p>Serve the agent, then replay a real PR at it from a second terminal. <code>replay</code> reads the PR through <code>gh api</code>, synthesizes a GitHub-shaped webhook delivery, and POSTs it to the channel. No repo admin, no tunnel:</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;"> dev</span></span>
-<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># second terminal:</span></span>
-<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;"> https://github.com/acme/checkout/pull/42</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
-<span class="line"><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;"> --action</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> opened</span></span></code></pre></div><p>The replay prints the delivery, and the serve terminal shows the wake:</p><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>[agent-sdk] replaying acme/checkout#42 (pull_request) → 1 channel</span></span>
-<span class="line"><span>[agent-sdk]   pull_request.opened → pr-approver/github 200</span></span></code></pre></div><p>The agent runs the same inspect-then-submit loop, unprompted this time. Replay the same PR again and the channel resumes that PR&#39;s session instead of starting a new one: each pull request keeps one running conversation.</p><h2 id="open-the-playground" tabindex="-1">Open the playground <a class="header-anchor" href="#open-the-playground" aria-label="Permalink to &quot;Open the playground&quot;">​</a></h2><p>Keep <code>agent-sdk dev</code> running and open the playground URL it printed. The webhook session is in the session list, titled <code>Review acme/checkout#42</code>, with the trigger message, both tool calls, and the verdict laid out. Start a new chat there and ask for another review to watch a turn stream live.</p><h2 id="go-live" tabindex="-1">Go live <a class="header-anchor" href="#go-live" aria-label="Permalink to &quot;Go live&quot;">​</a></h2><p>Replay is for development. For real deliveries, serve with <code>--cursor-events --repo owner/repo</code> to pull events for repositories connected to Cursor with no public URL, or run <code>agent-sdk github forward</code> to relay webhooks to your dev server. The <a href="./guides/github.html">GitHub guide</a> compares the options. In production, give the host GitHub App credentials so reviews post as your app&#39;s bot identity instead of a personal account.</p><h2 id="where-to-go-next" tabindex="-1">Where to go next <a class="header-anchor" href="#where-to-go-next" aria-label="Permalink to &quot;Where to go next&quot;">​</a></h2><ul><li><a href="./../examples/approval-buddy/"><code>examples/approval-buddy</code></a>: the production-shaped sibling, with commit statuses, review subagents, and a deterministic stamp policy</li><li><a href="./evals.html">Evals</a>: freeze these two PRs as regression checks so prompt changes can&#39;t flip a verdict</li><li><a href="./reference/tools.html">Tools</a>: more on typed tools, approvals, and direct calls</li><li><a href="./guides/github.html">GitHub</a>: fixtures, forwarding, and pulling events from Cursor</li><li><a href="./building-with-agents.html">Building agents with agents</a>: have a coding agent extend the project for you</li></ul>`,81)])])}const g=i(e,[["render",h]]);export{o as __pageData,g as default};
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p>Keep <code>agent-sdk dev</code> running. In a second terminal, replay an open pull request. Pull access is enough; repo admin isn&#39;t required:</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;"> github</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> replay</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> https://github.com/acme/checkout/pull/42</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
+<span class="line"><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;"> --action</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> opened</span></span></code></pre></div><p>Open the playground and confirm <code>Review acme/checkout#42</code> contains the trigger, both tool calls, and the verdict.</p><h2 id="run-options" tabindex="-1">Run options <a class="header-anchor" href="#run-options" aria-label="Permalink to &quot;Run options&quot;">​</a></h2><ol><li><p><strong>CLI message</strong></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;"> run</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;"> --message</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;Review https://github.com/acme/checkout/pull/42&quot;</span></span></code></pre></div></li><li><p><strong>Local replay</strong></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;"> github</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> replay</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> https://github.com/acme/checkout/pull/42</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
+<span class="line"><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;"> --action</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> opened</span></span></code></pre></div></li><li><p><strong>Forward or <code>--cursor-events</code></strong></p><p>Pull Cursor events:</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>Forward GitHub webhooks:</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;"> github</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> forward</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> .</span></span></code></pre></div><p>Keep the local <code>dev</code> or <code>serve</code> process running.</p></li><li><p><strong>Hosted deployment</strong></p><p>Deploy once, set the GitHub App secrets, then redeploy:</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;"> deploy</span></span>
+<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> secrets</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> set</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> sdk-pr-reviewer</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> GITHUB_APP_ID</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> GITHUB_APP_PRIVATE_KEY</span></span>
+<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> deploy</span></span></code></pre></div></li></ol><p>See <a href="./guides/github.html">GitHub</a> for local event delivery and <a href="./deployment.html">Deployment</a> for hosting.</p><h2 id="where-to-go-next" tabindex="-1">Where to go next <a class="header-anchor" href="#where-to-go-next" aria-label="Permalink to &quot;Where to go next&quot;">​</a></h2><ul><li><a href="./../examples/approval-buddy/"><code>examples/approval-buddy</code></a>: an example with commit statuses, review subagents, and a deterministic stamp policy</li><li><a href="./evals.html">Evals</a>: freeze these two PRs as regression checks so prompt changes can&#39;t flip a verdict</li><li><a href="./reference/tools.html">Tools</a>: more on typed tools, approvals, and direct calls</li><li><a href="./guides/github.html">GitHub</a>: fixtures, forwarding, and pulling events from Cursor</li><li><a href="./building-with-agents.html">Building agents with agents</a>: have a coding agent extend the project for you</li></ul>`,52)])])}const o=i(t,[["render",l]]);export{g as __pageData,o as default};

package/dist/docs/assets/quickstart.md.DZxBu44y.lean.js

@@ -0,0 +1 @@
+import{_ as i,c as a,o as n,ag as h}from"./chunks/framework.CAZyNGu9.js";const g=JSON.parse('{"title":"Build your first PR reviewer","description":"Create an agent that reviews pull requests by complexity, approves safe changes, and handles GitHub webhook events.","frontmatter":{"title":"Build your first PR reviewer","description":"Create an agent that reviews pull requests by complexity, approves safe changes, and handles GitHub webhook events."},"headers":[],"relativePath":"quickstart.md","filePath":"quickstart.md"}'),t={name:"quickstart.md"};function l(p,s,e,k,r,E){return n(),a("div",null,[...s[0]||(s[0]=[h("",52)])])}const o=i(t,[["render",l]]);export{g as __pageData,o as default};