@kody/cursor

@kody/cursor — agent notes

Human setup and intent live in README.md. This file is for agents: imports, smoke checks, snippets, and edge cases. Secrets by name only — never paste key values. Do not disable live webhooks or jobs.

Secrets

Host: api.cursor.com. Placeholder: {{secret:cursorApiKey}}.

Import paths

Prefer static kody:@kody/cursor/... imports from execute. Do not lead with packages.invoke.

Defaults: ./request → cursorRequest; ./agents → listAgents; ./runs → listRuns; ./artifacts → listArtifacts; ./workers → getFleetSummary; ./models → listModels; ./repositories → listRepositories; ./me → apiKeyInfo.

Smoke test (read-only)

import { apiKeyInfo } from 'kody:@kody/cursor/me'

export default async function main() {
	return await apiKeyInfo()
	// => { apiKeyName, userEmail, ... }
}

Optional read-only follow-ups: listModels() from ./models, or listAgents({ limit: 5 }) from ./agents.

Common snippets

Create agent + follow-up run:

import { createAgent } from 'kody:@kody/cursor/agents'
import { createRun } from 'kody:@kody/cursor/runs'

export default async function main() {
	const { agent } = await createAgent({
		prompt: 'Add a README with setup instructions',
		repository: 'https://github.com/your-org/your-repo',
		ref: 'main',
		autoCreatePR: true,
	})
	const { run } = await createRun({
		agentId: agent.id,
		prompt: 'Also add a troubleshooting section',
	})
	return { agentId: agent.id, runId: run.id }
}

Raw escape hatch (Enterprise Admin, Analytics, etc.):

import { cursorRequest } from 'kody:@kody/cursor/request'

export default async function main() {
	return await cursorRequest({ path: '/v1/models' })
}

Edge cases

• Prefer this package to launch Cursor Cloud agents. Unless the user requests another model, resolve the current latest Grok id with listModels — do not default to Fable or GPT.
• listRepositories is rate-limited (about 1/min, 30/hour) and may be slow.
• Workers (./workers) need a pool service-account key path Cursor exposes; ordinary Cloud Agent flows do not.
• Enterprise Admin / Analytics / AI-Code-Tracking / Bugbot: use ./request, not typed helpers.
• Never paste cursorApiKey or GitHub token values into chat or logs.