Use Cursor - OpenClaw + Cursor CLI Integration

Enable OpenClaw to execute Cursor CLI for various software engineering tasks, supporting interactive mode, background tasks, CI/CD, and more.

🔒 Security Notes

Before installing, understand these security implications:

What This Skill Does

• ✅ Manages Cursor CLI tasks via tmux (stated purpose)
• ✅ Reads

  ~/.cursor/cli-config.json

  to check auth status (email redacted in output)
• ✅ Captures tmux pane output (may contain workspace code/data)
• ✅ All shell arguments are escaped to prevent injection
• ✅ Does not download remote code at install time

Privacy Considerations

~/.cursor/cli-config.json

***@domain.com

~/.cursor/credentials

$CURSOR_API_KEY

$PATH

$HOME

⚠️ Critical: tmux Pane Execution Risk

This skill sends user-provided strings into tmux panes via

tmux send-keys

How it works:

1. Script creates tmux session
2. Runs

   agent --print --trust 'TASK'

   in the pane
3. Captures pane output and returns to agent

Risk: If the pane is running a shell, any text sent via

send-keys

Mitigation:

• Use in isolated environments (container/VM) for untrusted tasks
• Don't run on production machines with live secrets
• Review task strings before sending

Recommendations

Security Features (v1.0.0+)

• ✓ Shell argument escaping via single-quote method (prevents injection)
• ✓ tmux literal mode (

  -l

  flag) for all send-keys commands
• ✓ Email redaction (

  ***@domain.com

  )
• ✓ API key/token redaction in output
• ✓ No autonomous execution (

  always: false

  )
• ✓ No remote code download
• ✓ Explicit permissions declared in manifest
• ✓ Isolated mode with minimal environment (hardcoded PATH)

🎯 Use Cases

agent "task description"

agent -p

📦 Installation

1. Install Cursor CLI

⚠️ Security Note: The following install commands use remote scripts. Review them first or use your package manager when possible.

macOS:

# Recommended: use Homebrew (review formula first)
brew install --cask cursor-cli

# Alternative: official installer (review at https://cursor.com/install)
# curl https://cursor.com/install -fsS | bash

Linux/WSL:

# Download and inspect the installer first
curl -fsS https://cursor.com/install -o cursor-install.sh
less cursor-install.sh  # Review before running
bash cursor-install.sh

# Or check if available via your package manager

Verify installation:

agent --version
# or
cursor-agent --version

Required Dependencies:

• tmux

  - Terminal multiplexer (required for background tasks)

• agent

  or

  cursor-agent

  - Cursor CLI (required)

• CURSOR_API_KEY

  - Optional, or use

  agent login

  for browser auth

2. Authentication

agent login
# or set API key
export CURSOR_API_KEY=your_api_key_here

3. Install tmux (Required for background tasks)

# Ubuntu/Debian
sudo apt install tmux

# macOS
brew install tmux

# CentOS/RHEL
sudo yum install tmux

🛠️ OpenClaw Tools

Tool List

use_cursor_spawn

use_cursor_spawn "refactor this module"

use_cursor_spawn_isolated

use_cursor_spawn_isolated "task"

use_cursor_check

use_cursor_check session-name

use_cursor_send

use_cursor_send session-name "make it async"

use_cursor_kill

use_cursor_kill session-name

use_cursor_list

use_cursor_list

use_cursor_doctor

use_cursor_doctor

Execution Modes

spawn.sh

spawn-isolated.sh

🚀 Usage

Method 1: Background Task Mode (Recommended for large jobs)

User: Help me refactor this module using Cursor in background
→ Call: use_cursor_spawn "refactor src/ directory for better performance"
→ Returns: Task ID + tmux session name

Follow-up operations:

User: Check the progress of that task
→ Call: use_cursor_check <session-name>

User: Tell that task: change to TypeScript
→ Call: use_cursor_send <session-name> "implement in TypeScript"

User: Stop that Cursor task
→ Call: use_cursor_kill <session-name>

Method 2: Direct Run Mode (Small tasks)

User: Write a unit test for me
→ Call: use_cursor_run "write unit tests for src/utils.ts"
→ Wait for completion, return result

Method 3: Interactive Mode (Local debugging)

# Start interactive session
agent

# Or with task directly
agent "fix this bug"

# Switch model
/models

# Add context
@src/api/
@src/models/

📋 Cursor CLI Command Reference

Basic Commands

agent

agent "task"

agent -p "task"

agent --model <name>

agent --resume="<id>"

agent ls

agent resume

agent models

agent update

Slash Commands (Interactive Mode)

/models

/compress

/rules

/commands

/mcp enable <server>

/mcp disable <server>

Keyboard Shortcuts

Shift+Enter

Ctrl+D

Ctrl+R

↑/↓

🔧 Background Task Architecture

User (Discord/Feishu) 
  → OpenClaw Agent 
  → use_cursor_spawn tool 
  → tmux session 
  → Cursor CLI Agent

tmux Session Management

# Create session
tmux new-session -d -s cursor-task-001

# Send command
tmux send-keys -t cursor-task-001 "agent 'task description'" Enter

# Capture output
tmux capture-pane -t cursor-task-001 -p -S -100

# End session
tmux kill-session -t cursor-task-001

📊 Workflows

Code Review

agent -p 'Review the changes in the current branch against main. Focus on security and performance.'

Refactoring

agent -p 'Refactor src/utils.ts to reduce complexity and improve type safety.'

Debugging

agent -p 'Analyze the following error log and suggest a fix: [paste log here]'

Git Integration

agent -p 'Generate a commit message for the staged changes adhering to conventional commits.'

CI/CD

# Security audit (JSON output)
agent -p 'Audit this codebase for security vulnerabilities' --output-format json --force

# Test coverage
agent -p 'Run tests and generate coverage report' --output-format text

⚠️ Notes

TTY Issues

❌ These will hang:

agent "task"                    # No TTY
agent -p "task"                 # No TTY  
subprocess.run(["agent", ...])  # No TTY

✅ Correct approach:

# Use tmux for pseudo-terminal
tmux new-session -d -s cursor
tmux send-keys -t cursor "agent 'task'" Enter

Timeout Protection

• Small tasks (<5 min): Use

  use_cursor_run

  directly
• Medium tasks (5-30 min): Background mode + periodic checks
• Large tasks (>30 min): Background mode +分段 execution

Resource Management

• Each tmux session uses ~50-100MB memory
• Recommend max 3-5 concurrent background tasks
• Use

  use_cursor_kill

  to clean up completed tasks

🏥 Troubleshooting

use_cursor_doctor

Checklist

1. ✅ tmux installed
2. ✅ agent CLI executable
3. ✅ Authentication status (CURSOR_API_KEY or login)
4. ✅ Working directory permissions
5. ✅ Network connectivity

Common Issues

Q: Task exits immediately after starting

• Check Cursor authentication status
• Ensure working directory has code

Q: tmux session not found

• Run

  use_cursor_list

  to check active sessions
• May have been killed or timed out

Q: Garbled output

• tmux encoding issue, try

  export LANG=en_US.UTF-8

Security FAQs

Q: Does this skill send my code to external servers?

• A: No. Code stays on your machine. Cursor CLI may send to Anthropic/Claude API (that's how Cursor works).

Q: Can this skill access my Cursor API key?

• A: It can detect if

  $CURSOR_API_KEY

  is set, but doesn't log or transmit it.

Q: Is my email address exposed?

• A: No. Email is redacted to

  ***@domain.com

  in all outputs.

Q: Can malicious input cause shell injection?

• A: v1.0.0+ escapes all shell arguments. Earlier versions had this risk.

📁 File Structure

use-cursor/
├── SKILL.md              # This document
├── scripts/
│   ├── spawn.sh          # Start background task
│   ├── check.sh          # Check status
│   ├── send.sh           # Send instructions
│   ├── kill.sh           # End task
│   └── doctor.sh         # Diagnose environment
├── extensions/
│   └── use-cursor/
│       └── index.js      # OpenClaw tool definitions
└── examples/
    └── openclaw.json     # Configuration example

🔗 References

• Cursor Official Docs
• Cursor CLI GitHub
• tmux Usage Guide
• OpenClaw ACP Docs

Version: 1.0.1 Merged from: cursor-agent (2.1.0) + openclaw-cursor-agent (1.0.0) Authors: Bruce + 凤雏 🦞 Skill Name: use-cursor

Changelog

v1.0.4 (2026-03-31)

• ✅ Fixed: Newline/control character injection vulnerability - now sanitized before escaping
• ✅ Added: Control char removal (/[\x00-\x1f\x7f]/g) to prevent all tmux control sequence attacks
• ✅ Updated: SECURITY.md with sanitization documentation
• ✅ Fixed: Documentation mismatch - changed "JSON.stringify()" to "single-quote method" in SECURITY.md
• ✅ Fixed: Repository/homepage URLs updated to openclaw/skills (no more placeholders)
• ✅ Fixed: Added source field to manifest.json for provenance tracking
• ✅ Enhanced: Detailed code comments explaining why child_process is safe
• ✅ Clarified: Static analysis flag (child_process) is FALSE POSITIVE for this use case
• ✅ Updated: manifest.json notes with child_process justification

v1.0.1 (2026-03-31)

• ✅ Fixed: spawn-isolated.sh

  cd

  command now uses

  -l

  flag
• ✅ Verified: ALL tmux send-keys use literal mode (-l)
• ✅ Updated: manifest.json with detailed security notes
• ✅ Clarified: Default mode inherits env, isolated mode uses env -i

v1.0.0 (2026-03-31)

• Initial release with security hardening