Cursor Cookbook

cursor/cookbook — Cursor SDK をアプリ・CLI・クラウド運用へ接続する小さな実例集

1 — 概要
何を学ぶリポジトリか

Cursor Cookbook は、Cursor の coding agent を TypeScript から動かす @cursor/sdk の実例集。単発のローカル実行から、Ink 製 CLI、Next.js のプロトタイピング UI、Cloud Agent を一覧・作成する Kanban まで、抽象説明ではなく「動く小品」で SDK の使い方を示している。

中心にある概念はシンプル。Agent.create() で実行場所とモデルを決め、agent.send() でプロンプトを送り、run.stream() と run.wait() で進行中のイベントと結果を扱う。

Agent.create
local workspace or cloud repositories
agent.send
prompt, model, force, run options
run.stream
assistant, thinking, tool, task, status
Cloud API
agents, repositories, artifacts, PR links
4 examplesSDK cookbook
Node 22CLI examples
Next 16Web app demos
@cursor/sdkcore dependency
2 — 4つのサンプル
sdk/quickstart

最小構成。現在の作業ディレクトリにローカル agent を作り、固定プロンプトを送り、assistant の text block だけを標準出力へ流す。

sdk/coding-agent-cli

ターミナル実装。one-shot prompt、stdin prompt、Ink TUI、モデル選択、local/cloud 切り替え、キャンセル、セッションリセットを扱う。

sdk/app-builder

ローカルのアプリ生成ループ。API key を受け取り、Vite React のプレビュー環境を作り、チャット UI から agent に編集させる。

sdk/agent-kanban

Cloud Agent の運用 UI。agent をステータスやリポジトリでグループ化し、artifact preview と新規 cloud agent 作成を提供する。

学習順に並べるとこうなる

From script to operations
1
最小 SDK 呼び出し

API key、model、cwd を渡して agent を作る。

2
イベントを読む

assistant delta、thinking、tool call、task status を UI 用に整形する。

3
実行モードを選ぶ

ローカル作業ツリーか Cloud Agent かを、用途ごとに切り替える。

4
UIに接続する

SSE、Ink、Next.js API route で進行状況を画面に出す。

5
成果物を扱う

artifact、PR URL、repository cache を運用画面へ載せる。

3 — SDKの基本フロー
Local agent

quickstart と coding-agent-cli の基本はローカル実行。local: { cwd } に作業ディレクトリを渡すことで、agent はそのワークスペースを前提に回答・編集・検証できる。

sdk/quickstart/src/index.ts
const agent = await Agent.create({
  apiKey: process.env.CURSOR_API_KEY,
  name: "SDK quickstart",
  model: { id: process.env.CURSOR_MODEL ?? "composer-2" },
  local: { cwd: process.cwd() },
})

const run = await agent.send("Explain this project in one paragraph.")

for await (const event of run.stream()) {
  if (event.type !== "assistant") continue
  // text block を stdout へ流す
}
Cloud agent

coding-agent-cli の TUI と agent-kanban は、クラウド実行も扱う。Cloud 側では repository URL、branch、PR 作成、artifact など「実行結果を運用する」ための情報が前面に出る。

  • /local と /cloud で実行先を切り替える。
  • /model で Cursor.models.list() の候補を選ぶ。
  • Agent.create({ cloud: { repos } }) で Cloud Agent を作る。
  • artifact は認証付きのローカル API route 経由で preview する。
4 — APIとUIの接続
UI adapter patterns
サンプル UI / I/O SDK接続 見るべきファイル
Quickstart 標準出力 run.stream() から assistant text を抽出 sdk/quickstart/src/index.ts
Coding Agent CLI argv / stdin / Ink TUI CodingAgentSession がイベント正規化と実行モード切替を担当 sdk/coding-agent-cli/src/agent.ts
App Builder Next.js + SSE + iframe preview streamAgentResponse() を text/event-stream でブラウザへ送る sdk/app-builder/src/app/api/chat/route.ts
Agent Kanban Next.js board + artifact cards listCloudAgents() と createCloudAgent() を API route 化 sdk/agent-kanban/src/app/api/agents/route.ts
App Builder の要点

App Builder は、単に agent に返答させるだけではなく、作業用ディレクトリ、空きポート、Vite React テンプレート、dev server、SSE を束ねて「生成されたアプリをすぐ見ながら追加指示できる」体験にしている。

1
API key 検証

Cursor.me() で key を確認し、必要ならローカル保存。

2
workspace 生成

セッションごとの Vite React テンプレートを作る。

3
preview 起動

空きポートで dev server を動かし iframe に表示。

4
agent stream

assistant / thinking / tool / task を SSE で送る。

5
反復

同じ session に追加指示して、プレビューを更新する。

5 — 実行時の注意
Secrets

README は共通して CURSOR_API_KEY を必要条件にしている。Web UI 系の2例は key をローカル設定ファイルへ保存できるが、共有サービスとして公開する前提ではない。

注意: App Builder の README は、認証・ユーザー別ストレージ・より強い secret handling を足さずに共有公開しないよう明記している。
Runtime
  • CLI 系は Node.js 22 以上を要求する。
  • Next.js 系はローカルデモとして pnpm dev で起動する。
  • App Builder の agent 指示では、既存 preview server が壊れていない限り別の長時間 dev server を起動しない。
  • Agent Kanban の repository listing は Cloud Agents API の rate limit を考慮し、短時間メモリキャッシュを使う。

CLI のコマンド面

coding-agent-cli は、one-shot と TUI の分岐を入口で決める。プロンプトがあれば即実行、stdin があれば stdin を prompt として実行、TTY なら Ink のフルスクリーン TUI に入る。

TUI slash commands
/help   Show available commands
/local  Run future prompts in the local workspace
/cloud  Run future prompts in Cursor cloud
/model  Open a picker with available Cursor models
/reset  Start a fresh agent and clear context
/exit   Exit the TUI
6 — 参照ソース
Public references

このページは cursor/cookbook の README と SDK サンプルをもとに整理した。

参照 内容
README.md リポジトリ全体の目的と4つの SDK サンプルの位置づけ。
sdk/quickstart/README.md 最小ローカル agent 実行、Node.js 22、API key、stream 出力。
sdk/coding-agent-cli/README.md one-shot CLI と TUI、local/cloud execution、モデル選択。
sdk/app-builder/README.md ローカル app-building loop、React preview、ローカル key 保存の注意。
sdk/agent-kanban/README.md Cloud Agent board、repository grouping、artifact preview、create-agent flow。