Use Cursor

Manage Cursor CLI tasks via tmux with security hardening

Install

openclaw skills install use-cursor

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

Data Access	Purpose	Protection
`~/.cursor/cli-config.json`	Check auth status	Email redacted (shows `***@domain.com`)
`~/.cursor/credentials`	Check auth status	Not read, only existence checked
`$CURSOR_API_KEY`	Optional auth	Not logged or stored
`$PATH`, `$HOME`, etc.	Inherited by child processes	Not modified or logged
tmux output	Return task results	May contain workspace data

⚠️ Critical: tmux Pane Execution Risk

This skill sends user-provided strings into tmux panes via tmux send-keys.

How it works:

Script creates tmux session
Runs agent --print --trust 'TASK' in the pane
Captures pane output and returns to agent

Risk: If the pane is running a shell, any text sent via send-keys will be executed. While we escape arguments at the JavaScript level, special characters/control sequences could still affect the shell.

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

Environment	Recommendation
Personal dev machine	✅ Safe for normal projects
Open source work	✅ Safe
Corporate environment	⚠️ Review with security team first
Production server	❌ Not recommended
Machine with high-value secrets	❌ Use isolated container/VM

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

Scenario	Recommended Mode	Description
Quick tasks	Interactive	Direct `agent "task description"`
Long-running coding	Background	tmux-managed, no timeout
CI/CD automation	Non-interactive	`agent -p` + JSON output
Code review	Interactive/Background	With context analysis
Large refactoring	Background	Interruptible, resumable

📦 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

Tool	Description	Example
`use_cursor_spawn`	Start background Cursor task (standard mode)	`use_cursor_spawn "refactor this module"`
`use_cursor_spawn_isolated`	Start task with minimal environment	`use_cursor_spawn_isolated "task"`
`use_cursor_check`	Check task status	`use_cursor_check session-name`
`use_cursor_send`	Send additional instructions	`use_cursor_send session-name "make it async"`
`use_cursor_kill`	End task	`use_cursor_kill session-name`
`use_cursor_list`	List all tasks	`use_cursor_list`
`use_cursor_doctor`	Diagnose environment	`use_cursor_doctor`

Execution Modes

Mode	Script	Use Case
Standard	`spawn.sh`	Normal development, trusted tasks
Isolated	`spawn-isolated.sh`	Untrusted inputs, shared machines
Container	Docker/Podman	Maximum isolation (manual setup)

🚀 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

Command	Description
`agent`	Start interactive session
`agent "task"`	Execute task directly
`agent -p "task"`	Print mode (for scripts)
`agent --model <name>`	Specify model
`agent --resume="<id>"`	Resume session
`agent ls`	List sessions
`agent resume`	Resume most recent session
`agent models`	List available models
`agent update`	Update CLI

Slash Commands (Interactive Mode)

Command	Description
`/models`	Switch models
`/compress`	Compress session history
`/rules`	Manage rules
`/commands`	Manage custom commands
`/mcp enable <server>`	Enable MCP server
`/mcp disable <server>`	Disable MCP server

Keyboard Shortcuts

Shortcut	Description
`Shift+Enter`	New line
`Ctrl+D`	Exit (requires double-press)
`Ctrl+R`	Review changes
`↑/↓`	History messages

🔧 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

✅ tmux installed
✅ agent CLI executable
✅ Authentication status (CURSOR_API_KEY or login)
✅ Working directory permissions
✅ 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

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