Manage Cursor CLI tasks via tmux with security hardening
---
name: use-cursor
version: 1.0.4
description: Manage Cursor CLI tasks via tmux with security hardening
author: Bruce + ๅค้
license: MIT
source: https://github.com/openclaw/skills/tree/main/use-cursor
homepage: https://github.com/openclaw/skills
repository: https://github.com/openclaw/skills/tree/main/use-cursor
required:
binaries:
- tmux
- agent
env:
- CURSOR_API_KEY
clawhub:
security:
autonomous: false
always: false
userInvocable: true
---
# 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:**
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 `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:**
```bash
# 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:**
```bash
# 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:**
```bash
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
```bash
agent login
# or set API key
export CURSOR_API_KEY=your_api_key_here
```
### 3. Install tmux (Required for background tasks)
```bash
# 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)
```bash
# 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
```bash
# 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
```bash
agent -p 'Review the changes in the current branch against main. Focus on security and performance.'
```
### Refactoring
```bash
agent -p 'Refactor src/utils.ts to reduce complexity and improve type safety.'
```
### Debugging
```bash
agent -p 'Analyze the following error log and suggest a fix: [paste log here]'
```
### Git Integration
```bash
agent -p 'Generate a commit message for the staged changes adhering to conventional commits.'
```
### CI/CD
```bash
# 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:**
```bash
agent "task" # No TTY
agent -p "task" # No TTY
subprocess.run(["agent", ...]) # No TTY
```
**โ
Correct approach:**
```bash
# 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](https://cursor.com/docs)
- [Cursor CLI GitHub](https://github.com/getcursor/cursor)
- [tmux Usage Guide](https://github.com/tmux/tmux/wiki)
- [OpenClaw ACP Docs](https://docs.openclaw.ai/cli/acp)
---
*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
don't have the plugin yet? install it then click "run inline in claude" again.