npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@cursor/sdk

v1.4.2

Published

TypeScript SDK for Cursor agents.

Readme

@cursor/sdk

TypeScript SDK for Cursor agents.

Documentation: https://cursor.com/docs/api/sdk/typescript

No-repo cloud agents

Cloud agents can run on an empty VM with no repository. Pass cloud (omitting it selects the local platform) and leave repos unset:

const agent = await Agent.create({
  apiKey: process.env.CURSOR_API_KEY,
  cloud: { repos: [] },
});

No-repo agents must be enabled for your account or team, and repository-scoped API keys cannot create them.

Steer a running cloud run

send() throws AgentBusyError while a cloud agent has an active run. run.steer(text) sends the text into that run instead, and the run takes it at its next safe step:

const outcome = await run.steer("Also cover the error path");

if (outcome === "complete_delivered") {
  // The run has the text.
} else if (outcome === "revert_to_followup") {
  // Nothing took the text. Send it as a follow-up.
} else {
  // The text is already queued. Do not send it again.
  const result = await outcome.run?.wait();
}

When the run is no longer active, the server queues the text as the follow-up that starts the next run, and outcome.run is that run. A server that does not name the run returns { outcome: "queued" } with no run; the text is still queued. Either way the text is already queued: do not send it again. A resend sends the text twice, or fails with AgentBusyError while the queued run is active. Code that sends every outcome other than "complete_delivered" as a follow-up must handle { outcome: "queued" } first.

A cloud steer() is never retried, and it can throw: NetworkError when the request fails or the server answers 5xx, RateLimitError on 429, ConfigurationError when the agent cannot take it (for example an archived agent), and FeatureUnavailableError when the account has no steering. After a NetworkError the outcome is unknown, so it is not retryable (isRetryable is false): check the run's or agent's state instead of resending. A 429 (RateLimitError) means the steer was not delivered; it is safe to send again later.

Run a local agent on a FileSystem

Set local.fs and a local agent's own file tools (Read, Write, StrReplace, Grep, Glob, LS, Delete, and Task) run on a tree you supply instead of the host disk. The model sees its usual tools under their usual names, and nothing on the host reaches it: no host files, shell, git status, or hooks.

import { Agent, tempFs, unionFs } from "@cursor/sdk";

const agent = await Agent.create({
  apiKey: process.env.CURSOR_API_KEY,
  model: { id: "composer-2" },
  local: {
    fs: unionFs({
      "/repo": tempFs({
        "/AGENTS.md": "Answer in one paragraph.",
        "/src/greet.ts": 'export const greeting = "hello";\n',
      }),
      "/notes": tempFs(),
    }),
    reportedWorkspacePath: "/repo",
    settingSources: ["project"],
  },
});

const run = await agent.send('Change the greeting to "hello from fs" and note the change in /notes/log.md');
await run.wait();

The tree is a live handle, so the edits above are in /repo/src/greet.ts and /notes/log.md when the run finishes. Leave fs out and the agent works on the host disk as before.

Build a tree

Every helper returns a FileSystem, so they compose:

| Helper | What it gives you | | --- | --- | | tempFs(files?) | An in-memory tree seeded from a path-to-contents record. Stores text and bytes. | | unionFs({ "/repo": a, "/notes": b }) | One namespace from several trees, each mounted at a prefix. The longest prefix that covers a path owns it. | | overlayFs([top, bottom]) | A read-only view where earlier layers win. | | readOnlyFs(tree) | The same files, with write and delete refused. | | childOverlayFs(tree) | A writable view whose writes and deletes stay on a private layer, so tree never changes. | | emptyFs() | A tree with no files, for an empty mount. |

Pass a factory instead of a tree to build a new tree for each run. It's called with { agentId, sessionId }:

local: {
  fs: async ({ agentId }) => unionFs({ "/repo": await checkoutFor(agentId), "/scratch": tempFs() }),
},

Workspace and project rules

The model's workspace is / unless local.reportedWorkspacePath names a folder in the tree, such as /repo above. Relative paths in tool calls resolve against it, and Grep, Glob, and LS search it when a call names no path. Other mounts stay reachable by absolute path.

Project rules come from the tree, never from the host: <workspace>/AGENTS.md and <workspace>/.cursor/rules/**/*.mdc, with the same parsing as on the host. They load only when settingSources includes "project", so leave it out when the tree holds a repository you don't trust. Nested AGENTS.md files, parent folders, and skills aren't discovered under fs. Pass skills to the agent yourself. User and team rules work as usual.

local.cwd stays a host directory. It decides where the SDK keeps the agent's own state and transcripts and never changes what the model sees.

Tools under fs

| Tool | Under fs | | --- | --- | | Read, Write, StrReplace, and the other edit tools, Delete | Run on the tree. Read returns images as images. | | Grep, Glob, LS | Run on the tree. Grep patterns are JavaScript RegExp source, not ripgrep syntax. LS and Glob stop at 1,000 entries. | | Task | Runs each child on the parent's tree (see below). | | WebFetch, WebSearch, MCP, GenerateImage | Work as usual. Output that spills to a file lands in /tmp. | | Todos, AskQuestion, CreatePlan, SwitchMode, Await | Work as usual. | | Shell, ReadLints, SemanticSearch, and host-only tools | Not available. Naming one in tools is a ConfigurationError. |

/tmp

Each run gets a new, empty in-memory /tmp mounted over your tree, and any /tmp in the tree is hidden for that run. WebFetch and WebSearch results over 20 KB, MCP results over 40 KB, and GenerateImage files are written there, and the model reads them back with Read or Grep:

WebFetch → Content written to file: /tmp/0b3a6c1e-5d2f-4a8b-9c7d-1e2f3a4b5c6d.txt
Grep { path: "/tmp/0b3a6c1e-5d2f-4a8b-9c7d-1e2f3a4b5c6d.txt", pattern: "License" }

/tmp is dropped when the run ends. Your tree never receives these files, so a read-only tree works.

Task children

Task children, and their own children, work on the same tree as the session that started them, the way children without fs work in the same host folder. The parent sees a child's writes and deletes as soon as they happen, including files under /tmp:

await agent.send("Use a Task to fix the failing test in src/, then show me the diff of what it changed");

Children use the parent's workspace and tool allowlist and have no shell. To keep a whole run's writes off the tree you pass in, return childOverlayFs(tree) from an fs factory; the run then writes to an in-memory layer that is dropped when the run ends.

Run a file tool outside a turn

createFileSystemTools(tree, { workspace }) returns the same native tools as plain functions, for a direct tool-call endpoint, a test, or a CLI. Each returns the tool call a run's tool_call event carries:

import { createFileSystemTools } from "@cursor/sdk";

const tools = createFileSystemTools(tree, { workspace: "/repo" });

const call = await tools.Read.execute({ path: "src/greet.ts", limit: 20 });
if (call.result?.status === "success") {
  console.log(call.result.value.content);
}

for (const tool of Object.values(tools)) {
  console.log(tool.name, tool.annotations.readOnlyHint);
}

annotations uses the MCP tool annotation shape: Read, LS, Grep, and Glob are read-only, and Write, StrReplace, and Delete are destructive.

Write your own FileSystem

A FileSystem has seven methods:

interface FileSystem {
  list(prefix?: string, options?: ListOptions): AsyncIterable<DirEntry>;
  stat(path: string): Promise<FileInfo>;
  glob(pattern: string, dir?: string, options?: GlobOptions): AsyncIterable<DirEntry>;
  read(path: string): Promise<string | Uint8Array>;
  grep(query: FSGrepQuery): AsyncIterable<FSGrepResult>;
  write(path: string, contents: string | Uint8Array): Promise<void>;
  delete(path: string): Promise<void>;
}

The tools depend on this contract:

  • Paths are absolute POSIX paths rooted at /, with no trailing slash except / itself. Prefixes match by path segment: /agent covers /agent/skills but not /agent-tools.
  • list and glob yield each path once, in lexicographic order. grep yields by path, then line number.
  • A missing path is a value, not an error: list and glob yield nothing, and stat returns { kind: "missing" }.
  • read, write, and delete throw a PathError subclass, such as FileNotFoundError or ReadOnlyMountError. Its message is what the model sees.
  • ListOptions.excludes, limit, and maxDepth and FSGrepQuery.maxResults let a remote tree stop early, and you can ignore them, because the tools apply the same limits afterwards. With maxDepth, yield one { path, kind: "directory" } entry for each subtree the depth cuts off. LS lists one level at a time this way instead of walking a whole remote repository.
  • write gets bytes as well as text, for example a GenerateImage file. A tree that stores only text should throw WriteFailedError for bytes rather than corrupt them.
  • grep patterns are JavaScript RegExp source. Throw InvalidGrepPatternError for one that doesn't compile.

Wrapping an existing tree is the shortest path. This one records every change the agent makes:

import type { FileSystem } from "@cursor/sdk";

function auditedFs(inner: FileSystem, onChange: (change: string) => void): FileSystem {
  return {
    list: (prefix, options) => inner.list(prefix, options),
    stat: (path) => inner.stat(path),
    glob: (pattern, dir, options) => inner.glob(pattern, dir, options),
    read: (path) => inner.read(path),
    grep: (query) => inner.grep(query),
    async write(path, contents) {
      await inner.write(path, contents);
      onChange(`wrote ${path}`);
    },
    async delete(path) {
      await inner.delete(path);
      onChange(`deleted ${path}`);
    },
  };
}

Limits

  • fs is for local agents. Setting it on a cloud agent is a ConfigurationError.
  • The Python SDK has no fs, because the tree is an in-process TypeScript object.
  • fs can't be combined with local.subagentInherit or local.resourceProviderOptions. Task children already run on the tree.
  • Resuming an agent that was created with fs needs fs again.
  • LocalSendOptions.fs replaces the tree for one send and keeps the agent's reportedWorkspacePath unless the send sets its own.

Summarize the conversation

agent.summarize() condenses a local agent's conversation into a summary, the same action as /summarize in the Cursor CLI. Later sends give the model the summary instead of the full transcript, so a long session gets its context window back. It returns a Run the way send() does:

const run = await agent.summarize();
const result = await run.wait();

if (result.status === "finished") {
  console.log(result.result);
}

When the run finishes, result.result holds the summary text, or the trimmed transcript when the agent falls back to one. Check for a fallback before you show it to a user.

Summarizing is all or nothing: if you cancel the run while it's summarizing, or it ends with status error, later sends still see the full conversation.

summarize() throws a ConfigurationError instead of starting a run when the agent was created with cloud, including agents on a self-hosted pool or machine, or when it has no saved conversation yet, such as a new agent that hasn't sent a message. Cloud agents summarize on their own as their context fills. Like send(), it also throws while another run on the agent is active, so wait for that run or cancel it first.

Summary events

A summarize run streams summary messages (SDKSummaryMessage): one with status: "running" when it starts, then one with "completed" or "error". The agent also summarizes on its own when a conversation nears the model's context limit, on local and cloud agents alike, and those send() runs carry the same messages. One handler covers both:

for await (const message of run.stream()) {
  if (message.type !== "summary") {
    continue;
  }
  if (message.status === "running") {
    spinner.start("Summarizing the conversation");
  } else if (message.status === "error") {
    spinner.fail("Couldn't summarize; the conversation is unchanged");
  } else if (message.fallback === true) {
    spinner.warn("Summarized from a trimmed transcript");
  } else {
    spinner.succeed("Conversation summarized");
  }
}

"error" leaves the conversation unchanged. fallback: true means the model couldn't write the summary, so the agent saved a trimmed copy of the transcript instead. Context is still freed, but the copy may cut long messages short or leave some out.