@viralengine/cursor-agent

Embeddable SDK for local Cursor agent interaction. Spawns the agent CLI directly via a lightweight local HTTP bridge or mountable route handlers.

Prerequisites

• Cursor Agent CLI installed
• agent login completed on the machine

Install

npm install @viralengine/cursor-agent

Subpath exports

| Import | Purpose | |---|---| | @viralengine/cursor-agent/agent | CLI core (Node) | | @viralengine/cursor-agent/server | HTTP bridge + route handlers | | @viralengine/cursor-agent/client | Browser client | | @viralengine/cursor-agent/react | <FloatingChat /> widget | | @viralengine/cursor-agent/vite | Vite dev plugin | | @viralengine/cursor-agent/styles.css | Widget styles |

Integration modes

Pick one per project:

1. Standalone bridge

npx @viralengine/cursor-agent serve --cwd /path/to/project

Use the printed bridge token with mutating requests.

import { FloatingChat } from "@viralengine/cursor-agent/react";
import "@viralengine/cursor-agent/styles.css";

<FloatingChat
  cwd="/path/to/project"
  token="<bridge-token>"
  serverUrl="http://127.0.0.1:4317"
/>

2. Vite dev plugin

import { cursorAgentSdk } from "@viralengine/cursor-agent/vite";

export default defineConfig({
  plugins: [cursorAgentSdk({ cwd: process.cwd(), port: 4317 })],
});

3. Own backend (Next.js, Express, Hono)

import { createRouteHandlers, chatRouteConfig } from "@viralengine/cursor-agent/server";

export const { runtime, dynamic, maxDuration } = chatRouteConfig;
const { chatPOST } = createRouteHandlers({ requireToken: false });
export const POST = chatPOST;

Client uses same-origin requests:

import { createAgentClient } from "@viralengine/cursor-agent/client";

const client = createAgentClient({ baseUrl: "" });

Browser client

import { createAgentClient } from "@viralengine/cursor-agent/client";

const client = createAgentClient({
  baseUrl: "http://127.0.0.1:4317",
  token: process.env.BRIDGE_TOKEN,
  cwd: "/path/to/project",
  storageKeyPrefix: "my-app",
});

await client.waitForHealth();
await client.sendMessage({
  prompt: "Explain this codebase",
  agentId,
  onEvent: (event, data) => {},
  signal: abortController.signal,
});

Bridge endpoints

| Method | Path | Auth | |---|---|---| | GET | /health | No | | GET | /connect | No | | GET | /sessions | Token | | GET | /sessions/:id | Token | | POST | /chat | Token |

Security

The bridge binds to 127.0.0.1 by default and requires a bearer token for mutating requests.

Localhost CSRF: Any webpage can POST to localhost while the bridge runs. CORS does not prevent this. The bridge token mitigates unauthorized runs. The CLI uses -f (auto-approved tools) — treat as dev-only.

Environment variables:

• AGENT_CWD — default workspace
• AGENT_CLI — path to agent binary
• AGENT_SDK_PORT — default 4317
• AGENT_SDK_ORIGINS — CORS allowlist
• AGENT_CWD_ALLOWLIST — optional workspace roots

Publish

npm publish --access public

Requires the @viralengine npm org.

Scripts

npm run build -w @viralengine/cursor-agent
npm run test -w @viralengine/cursor-agent
npx @viralengine/cursor-agent serve --cwd .