Cursor Integration

Cursor supports custom rules that can guide the AI to use external tools. By adding supyagent tool documentation to your Cursor rules, you give the AI knowledge of your custom tools and how to invoke them.

Cursor Rules Setup

Create a .cursorrules file in your project root that describes your available tools:

.cursorrules

You have access to supyagent tools via the terminal. These tools are
Python scripts in the powers/ directory, executed via the supypowers CLI.

## Available Tools

Run `supypowers docs --format md` to see all available tools and their schemas.

## How to Use Tools

Execute a tool:
  supypowers run <script>:<function> '<json_input>'

Output format:
  {"ok": true, "data": {...}}  on success
  {"ok": false, "error": "..."} on failure

## Common Tools

- Search code: supypowers run search:search '{"pattern": "...", "glob": "*.py"}'
- Read file: supypowers run files:read_file '{"path": "..."}'
- Edit file: supypowers run edit:edit_replace '{"file": "...", "old_text": "...", "new_text": "..."}'
- Run command: supypowers run shell:run_command '{"command": "..."}'
- Git status: supypowers run git:git_status '{}'

## Cloud Integrations

For tasks involving external services (email, Slack, GitHub), delegate to a supyagent:
  supyagent run assistant "<task description>"

Generating Tool Documentation

Generate a comprehensive tool reference for Cursor:

# Generate markdown documentation of all tools
supypowers docs --format md --output TOOLS.md

# Generate skill files (can be referenced in rules)
supypowers skills --stdout > .cursor/skills.md

Include the generated documentation in your rules:

.cursorrules

Refer to TOOLS.md for the complete list of available tools and their input schemas.
When a task requires file operations, code search, or external services, use the
supypowers CLI to execute the appropriate tool.

Direct Tool Execution

Cursor's AI can execute terminal commands. Your supypowers tools are available through the terminal:

# Search for patterns in the codebase
supypowers run search:search '{"pattern": "deprecated", "glob": "*.py", "context_lines": 2}'

# Apply a multi-file patch
supypowers run patch:apply_patch '{"patch": "*** Update File: src/config.py\n@@ DEBUG = False\n-DEBUG = False\n+DEBUG = True\n"}'

# Check git status
supypowers run git:git_status '{}'

Using supyagent Agents from Cursor

For complex multi-step tasks, Cursor can delegate to a supyagent:

# Run a task using an agent
supyagent run coder "Refactor the authentication module to use JWT tokens"

# Get structured output
supyagent run reviewer "Review the changes in the current branch" --output json

This is particularly useful for tasks that require:

Multiple tool calls in sequence
Cloud integration access (email, Slack, GitHub)
Multi-agent delegation
Complex reasoning about tool outputs

Project Setup

Recommended project structure for Cursor + supyagent:

my-project/
  .cursorrules          # Cursor rules with tool instructions
  TOOLS.md              # Generated tool reference (supypowers docs --format md)
  agents/
    coder.yaml          # Agent for coding tasks
    reviewer.yaml       # Agent for code review
  powers/
    shell.py            # Default tools
    files.py
    search.py
    my_custom_tool.py   # Your custom tools

Tips

Keep .cursorrules concise -- list the most common tools and their invocation patterns
Generate TOOLS.md periodically and commit it for reference
Use supyagent run for complex tasks that benefit from an agent's reasoning loop
Use supypowers run for simple, single-tool invocations
Cursor's terminal integration means any CLI tool works -- no special adapter needed

What's Next

Claude Code -- SKILL.md integration
MCP Protocol -- Future native integration via MCP
Execution Mode -- CI/CD and automation

Cursor

On this page