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
INLINECODE1	Check auth status	Email redacted (shows ***@domain.com)
INLINECODE3

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:

1. 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 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 INLINECODE13
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:
CODEBLOCK0

Linux/WSL:
CODEBLOCK1

Verify installation:
CODEBLOCK2

Required Dependencies:

• - tmux - Terminal multiplexer (required for background tasks)
• INLINECODE16 or cursor-agent - Cursor CLI (required)
• INLINECODE18 - Optional, or use agent login for browser auth

2. Authentication

CODEBLOCK3

3. Install tmux (Required for background tasks)

CODEBLOCK4

---

🛠️ OpenClaw Tools

Tool List

Tool	Description	Example
INLINECODE20	Start background Cursor task (standard mode)	INLINECODE21
INLINECODE22

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	INLINECODE34	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)

CODEBLOCK5

Follow-up operations:
CODEBLOCK6

Method 2: Direct Run Mode (Small tasks)

CODEBLOCK7

Method 3: Interactive Mode (Local debugging)

CODEBLOCK8

---

📋 Cursor CLI Command Reference

Basic Commands

Command	Description
INLINECODE36	Start interactive session
INLINECODE37

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
INLINECODE45	Switch models
INLINECODE46

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
INLINECODE51	New line
INLINECODE52

Exit (requires double-press) | | Ctrl+R | Review changes | | ↑/↓ | History messages |

---

🔧 Background Task Architecture

CODEBLOCK9

tmux Session Management

CODEBLOCK10

---

📊 Workflows

Code Review

CODEBLOCK11

Refactoring

CODEBLOCK12

Debugging

CODEBLOCK13

Git Integration

CODEBLOCK14

CI/CD

CODEBLOCK15

---

⚠️ Notes

TTY Issues

❌ These will hang:
CODEBLOCK16

✅ Correct approach:
CODEBLOCK17

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. 1. ✅ tmux installed
2. ✅ agent CLI executable
3. ✅ Authentication status (CURSORAPIKEY 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 INLINECODE59

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

CODEBLOCK18

---

🔗 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 childprocess is safe
• ✅ Clarified: Static analysis flag (childprocess) 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