# Cursor ACP Extension for pi

Connect pi to Cursor's AI agent via the [Agent Client Protocol (ACP)](https://agentclientprotocol.com/).

## Quick Start

```bash
# 1. Install Cursor CLI
curl -fsSL https://cursor.sh/install.sh | sh

# 2. Authenticate  
agent login

# 3. Symlink extension (best practice)
ln -s ~/Documents/code/meep/pi-cursor/extensions/cursor-acp.ts \
      ~/.pi/agent/extensions/cursor-acp.ts

# 4. Restart pi and run:
/cursor:connect
```

## Features

- **Full Tool Access**: Use Cursor's agent with file editing, terminal commands, and more
- **Planning Mode**: Read-only planning with `cursor:mode plan`
- **Q&A Mode**: Ask questions without file modifications
- **Permission Handling**: Get prompted before Cursor runs dangerous tools
- **Streaming Output**: See agent responses as they're generated

## Prerequisites

### 1. Install Cursor CLI

```bash
# Download and install
curl -fsSL https://cursor.sh/install.sh | sh

# Or via Homebrew
brew install --cask cursor

# Verify installation
agent --version
```

### 2. Authenticate

```bash
# Interactive login
agent login

# Or with API key
export CURSOR_API_KEY="your-api-key"
agent login --api-key "$CURSOR_API_KEY"
```

## Installation

### Best Practice: Symlink (Recommended)

This keeps the source in your project repo for version control while allowing pi to load it:

```bash
# Create symlink from pi extensions directory to your source
ln -s ~/Documents/code/meep/pi-cursor/extensions/cursor-acp.ts \
      ~/.pi/agent/extensions/cursor-acp.ts

# Restart pi (or it will auto-reload)
```

### Project-local Extension (Alternative)

```bash
# Create .pi directory in your project
mkdir -p .pi/extensions

# Symlink to your extension
ln -s ../path/to/extensions/cursor-acp.ts .pi/extensions/
```

### Copy (Not Recommended)

```bash
# Simple but loses version control
cp cursor-acp.ts ~/.pi/agent/extensions/
```

## Usage

### Commands

| Command | Description |
|---------|-------------|
| `cursor:connect` | Connect to Cursor agent |
| `cursor:mode [mode]` | Set mode (agent/plan/ask) |
| `cursor:help` | Show help |
| `cursor:status` | Check connection status |

### Tools

| Tool | Description |
|------|-------------|
| `cursor_agent` | Run Cursor agent with a prompt |
| `cursor_status` | Check if connected |
| `cursor_disconnect` | Disconnect from agent |

### Example Usage

```
# Connect to Cursor
/cursor:connect

# Run an agent task
@cursor_agent What files were modified in this PR?

# Ask a question
/cursor:mode ask
@cursor_agent Explain this function

# Plan a refactor (read-only)
/cursor:mode plan
@cursor_agent Plan how to refactor this module
```

## Modes

| Mode | Description | Can Edit Files? |
|------|-------------|-----------------|
| `agent` | Full tool access (default) | ✅ Yes |
| `plan` | Planning mode | ❌ Read-only |
| `ask` | Q&A mode | ❌ Read-only |

## Permissions

When Cursor wants to run tools (bash commands, file edits, etc.), you'll be prompted:

```
┌─────────────────────────────────────────┐
│ Permission Required                     │
├─────────────────────────────────────────┤
│ Cursor wants to run: bash               │
│ Args: git status                        │
│                                         │
│                    [Cancel] [Allow]      │
└─────────────────────────────────────────┘
```

Options:
- **Allow Once**: Allow just this execution
- **Reject Once**: Block just this execution

## Troubleshooting

### "Agent not found"

```bash
# Check if Cursor CLI is installed
which agent
agent --version

# If not found, reinstall
curl -fsSL https://cursor.sh/install.sh | sh
```

### "Authentication failed"

```bash
# Re-authenticate
agent login

# Or set API key
export CURSOR_API_KEY="your-key"
```

### "Connection refused"

Make sure no other process is using the same port or stdio connection.

```bash
# Disconnect first
@cursor_disconnect

# Then reconnect
/cursor:connect
```

## Architecture

```
┌─────────────┐     spawn("agent acp")     ┌─────────────┐
│  pi         │ ─────────────────────────► │  Cursor CLI │
│             │                            │             │
│ cursor-acp  │ ◄──── JSON-RPC ──────────► │  ACP Server │
│ extension   │     stdio streams          │             │
└─────────────┘                            └─────────────┘
     ▲                                           │
     │         ctx.ui.confirm()                  │
     └───────────────────────────────────────────┘
                  (permission requests)
```

## Protocol Flow

1. **Start**: `spawn("agent", ["acp"])`
2. **Initialize**: Exchange protocol version/capabilities
3. **Authenticate**: `authenticate({ methodId: "cursor_login" })`
4. **Session**: Create/resume session with `session/new`
5. **Prompt**: Send requests with `session/prompt`
6. **Updates**: Receive streaming via `session/update`
7. **Permissions**: Handle `session/request_permission`
8. **Done**: Session ends or `session/cancel`

## License

MIT - This extension is provided as-is.