cursor-agent

name	cursor-agent
version	2.1.0
description	A comprehensive skill for using the Cursor CLI agent for various software engineering tasks (updated for 2026 features, includes tmux automation guide).
author	Pushpinder Pal Singh

Cursor CLI Agent Skill

This skill provides a comprehensive guide and set of workflows for utilizing the Cursor CLI tool, including all features from the January 2026 update.

Installation

Standard Installation (macOS, Linux, Windows WSL)

curl https://cursor.com/install -fsS | bash

Homebrew (macOS only)

brew install --cask cursor-cli

Post-Installation Setup

macOS:

• Add to PATH in ~/.zshrc (zsh) or ~/.bashrc (bash):

  export PATH="$HOME/.local/bin:$PATH"
  

• Restart terminal or run source ~/.zshrc (or ~/.bashrc)
• Requires macOS 10.15 or later
• Works on both Intel and Apple Silicon Macs

Linux/Ubuntu:

• Restart your terminal or source your shell config
• Verify with agent --version

Both platforms:

• Commands: agent (primary) and cursor-agent (backward compatible)
• Verify installation: agent --version or cursor-agent --version

Authentication

Authenticate via browser:

agent login

Or use API key:

export CURSOR_API_KEY=your_api_key_here

Update

Keep your CLI up to date:

agent update
# or
agent upgrade

Commands

Interactive Mode

Start an interactive session with the agent:

agent

Start with an initial prompt:

agent "Add error handling to this API"

Backward compatibility: cursor-agent still works but agent is now the primary command.

Model Switching

List all available models:

agent models
# or
agent --list-models

Use a specific model:

agent --model gpt-5

Switch models during a session:

/models

Session Management

Manage your agent sessions:

• List sessions: agent ls
• Resume most recent: agent resume
• Resume specific session: agent --resume="[chat-id]"

Context Selection

Include specific files or folders in the conversation:

@filename.ts
@src/components/

Slash Commands

Available during interactive sessions:

• /models - Switch between AI models interactively
• /compress - Summarize conversation and free up context window
• /rules - Create and edit rules directly from CLI
• /commands - Create and modify custom commands
• /mcp enable [server-name] - Enable an MCP server
• /mcp disable [server-name] - Disable an MCP server

Keyboard Shortcuts

• Shift+Enter - Add newlines for multi-line prompts
• Ctrl+D - Exit CLI (requires double-press for safety)
• Ctrl+R - Review changes (press i for instructions, navigate with arrow keys)
• ArrowUp - Cycle through previous messages

Non-interactive / CI Mode

Run the agent in a non-interactive mode, suitable for CI/CD pipelines:

agent -p 'Run tests and report coverage'
# or
agent --print 'Refactor this file to use async/await'

Output formats:

# Plain text (default)
agent -p 'Analyze code' --output-format text

# Structured JSON
agent -p 'Find bugs' --output-format json

# Real-time streaming JSON
agent -p 'Run tests' --output-format stream-json --stream-partial-output

Force mode (auto-apply changes without confirmation):

agent -p 'Fix all linting errors' --force

Media support:

agent -p 'Analyze this screenshot: screenshot.png'

⚠️ Using with AI Agents / Automation (tmux required)

CRITICAL: When running Cursor CLI from automated environments (AI agents, scripts, subprocess calls), the CLI requires a real TTY. Direct execution will hang indefinitely.

The Solution: Use tmux

# 1. Install tmux if not available
sudo apt install tmux  # Ubuntu/Debian
brew install tmux      # macOS

# 2. Create a tmux session
tmux kill-session -t cursor 2>/dev/null || true
tmux new-session -d -s cursor

# 3. Navigate to project
tmux send-keys -t cursor "cd /path/to/project" Enter
sleep 1

# 4. Run Cursor agent
tmux send-keys -t cursor "agent 'Your task here'" Enter

# 5. Handle workspace trust prompt (first run)
sleep 3
tmux send-keys -t cursor "a"  # Trust workspace

# 6. Wait for completion
sleep 60  # Adjust based on task complexity

# 7. Capture output
tmux capture-pane -t cursor -p -S -100

# 8. Verify results
ls -la /path/to/project/

Why this works:

• tmux provides a persistent pseudo-terminal (PTY)
• Cursor's TUI requires interactive terminal capabilities
• Direct agent calls from subprocess/exec hang without TTY

What does NOT work:

# ❌ These will hang indefinitely:
agent "task"                    # No TTY
agent -p "task"                 # No TTY  
subprocess.run(["agent", ...])  # No TTY
script -c "agent ..." /dev/null # May crash Cursor

Rules & Configuration

The agent automatically loads rules from:

• .cursor/rules
• AGENTS.md
• CLAUDE.md

Use /rules command to create and edit rules directly from the CLI.

MCP Integration

MCP servers are automatically loaded from mcp.json configuration.

Enable/disable servers on the fly:

/mcp enable server-name
/mcp disable server-name

Note: Server names with spaces are fully supported.

Workflows

Code Review

Perform a code review on the current changes or a specific branch:

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

Refactoring

Refactor code for better readability or performance:

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

Debugging

Analyze logs or error messages to find the root cause:

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

Git Integration

Automate git operations with context awareness:

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

Batch Processing (CI/CD)

Run automated checks in CI pipelines:

# Set API key in CI environment
export CURSOR_API_KEY=$CURSOR_API_KEY

# Run security audit with JSON output
agent -p 'Audit this codebase for security vulnerabilities' --output-format json --force

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

Multi-file Analysis

Use context selection to analyze multiple files:

agent
# Then in interactive mode:
@src/api/
@src/models/
Review the API implementation for consistency with our data models