Cursor Background Agent Api

🚀 Cursor Background Agent API Client

A powerful Node.js API client and CLI tool for automating Cursor's Background Composer

This TypeScript-based API client offers programmatic access to Cursor's Background Composer functionality. You can create, manage, and monitor background coding tasks, with support for both the CLI and the MCP (Model Context Protocol) server.

✨ Features

• CLI Interface 🔧 - A command-line tool for managing background composers.
• MCP Server 🤖 - A Model Context Protocol server for integrating with AI assistants.
• TypeScript Support 💪 - Ensures full type safety and IntelliSense.
• Background Composer Management 📋 - Allows you to create, list, and monitor coding tasks.
• User Settings Control ⚙️ - Manage privacy mode and web access settings.
• Repository Integration 🔗 - Automatically detects Git repositories.
• Multiple Output Formats 📄 - Supports JSON, table, and raw output formats.

📦 Installation

You can install the tool globally via npm:

npm install -g cursor-api-client

Or clone the repository and build it locally:

git clone https://github.com/mjdierkes/cursor-background-agent-api.git
cd cursor-background-agent-api
npm install
npm run build

🚀 Quick Start

1. Get Your Session Token

You need a Cursor session token to authenticate API requests. You have two options:

Option A: Environment Variable (Recommended)

export CURSOR_SESSION_TOKEN="your_session_token_here"

Option B: Cookies File Create a cookies.json file with your Cursor session cookies:

[
  {
    "name": "WorkosCursorSessionToken", 
    "value": "your_session_token_here"
  }
]

2. Verify Setup

Test your configuration with the following command:

cursor-api test

💻 Usage Examples

CLI Usage

List Background Composers

cursor-api list
cursor-api list --format json

Create Background Composer

cursor-api create --task-description "Add user authentication to the app"
cursor-api create -d "Fix bug in payment processing" -r "https://github.com/user/repo.git"

Get Composer Details

cursor-api details --composer-id "your-composer-id"

Check Settings

cursor-api web-access    # Check agent web access
cursor-api privacy       # Check privacy mode settings  
cursor-api settings      # Get user settings

Available Commands

• list - List all background composers.
• create - Create a new background composer task.
• details - Get detailed composer information.
• web-access - Check the agent's web access status.
• privacy - Get privacy mode settings.
• settings - Get user settings.
• test - Test all API endpoints.
• mcp-server - Start the MCP server.

Global Options

• --format, -f - Output format: json, table, raw (default: table).
• --verbose, -v - Enable verbose logging.
• --token, -T - Override the session token.
• --help, -h - Show help.

GitHub Workflow Integration

You can automatically trigger background agents for every new issue using the included GitHub Actions workflow.

Setup

1. Add the workflow file (already included in this repository):
   • .github/workflows/issue-background-agent.yml
2. Configure the Cursor session token secret:
   • Go to your repository's Settings > Secrets and variables > Actions.
   • Add a new repository secret named CURSOR_SESSION_TOKEN.
   • Set the value to your Cursor session token.
3. Enable the workflow:
   • The workflow will automatically trigger when new issues are created.
   • It will analyze the issue and create a background composer task.
   • A comment will be posted on the issue confirming the agent was triggered.

How it Works

When a new issue is created, the workflow:

1. Makes a direct API call to Cursor's background composer endpoint.
2. Passes the complete issue information (title, body, author, labels, URL).
3. Posts a comment on the issue confirming the agent was triggered.

The background agent will receive:

• Issue title and description.
• Author information.
• Labels.
• Repository context.
• Direct link to the issue.

Results will be available in the Cursor Background Composer interface.

Workflow Features

• Automatic Triggering ⚡ - Runs on every new issue.
• Fast Execution 🏎️ - Makes a direct API call with no setup steps.
• Rich Context 📚 - Passes complete issue information to the agent.
• User Feedback 💬 - Comments on the issue to confirm activation.
• Repository Aware 🔍 - Automatically uses the current repository URL.

API Client Usage

import { CursorAPIClient } from 'cursor-api-client';

const client = new CursorAPIClient('your-session-token');

// Create background composer
const result = await client.createBackgroundComposer({
  taskDescription: 'Add user authentication',
  repositoryUrl: 'https://github.com/user/repo.git',
  branch: 'main',
  model: 'claude-4-sonnet-thinking'
});

// List composers
const composers = await client.listComposers();

// Get settings
const settings = await client.getUserSettings();

📄 License

This project is licensed under the MIT License. See the LICENSE file for details.