cursor-acp

An ACP (Agent Client Protocol) adapter for Cursor Agent CLI. Makes Cursor a first-class ACP agent inside OpenClaw — enabling persistent, streaming Cursor sessions bound to Discord threads, with automatic file sharing.

What it does

You (Discord message)
        │
        ▼
  OpenClaw + acpx
        │  JSON-RPC over stdio
        ▼
  cursor-acp  (this adapter)
        │  cursor agent --print --output-format stream-json --trust --resume ...
        ▼
  Cursor Agent CLI → Cursor cloud (your LLM)
        │
        ▼
  Streaming response + files → back to Discord thread

• Persistent sessions — Cursor conversation context survives across messages via --resume
• Real-time streaming — responses stream chunk by chunk as Cursor generates them
• Automatic file sharing — when Cursor creates a file, it's sent to the Discord thread as an attachment automatically
• Audio/PDF/image attachments — inbound Discord attachments are transcribed or passed to Cursor
• Per-session working directory — each thread is scoped to a project folder

Requirements

• OpenClaw with Discord configured
• Cursor installed and authenticated (cursor agent status)
• Node.js 18+
• OpenClaw bot must have Manage Webhooks permission in any Discord channel where you use /cursor

Installation

npm install -g @dircha/cursor-acp

Setup

After installing, run the interactive setup:

cursor-acp setup

This walks you through all configuration steps:

1. Checks Cursor CLI is authenticated
2. Updates OpenClaw config to point to the bundled acpx fork
3. Optionally restarts the gateway
4. Creates ~/.cursor-acp/config.json with your project mappings
5. Installs the /cursor shortcut skill (also auto-installed by postinstall)

Manual setup

1. Point OpenClaw at the bundled acpx fork

Edit ~/.openclaw/openclaw.json:

"plugins": {
  "entries": {
    "acpx": {
      "enabled": true,
      "config": {
        "command": "/opt/homebrew/lib/node_modules/@dircha/cursor-acp/acpx-fork/acpx"
      }
    }
  }
}

Adjust the path if your npm global prefix differs — check with npm prefix -g.

2. Restart OpenClaw

openclaw gateway restart

3. Configure your projects

Edit ~/.cursor-acp/config.json:

{
  "baseDir": "/home/user/projects",
  "default": "my-api",
  "channels": {
    "<channelId>": {
      "default": "work-repo",
      "baseDir": "/home/user/work/work-repo"
    }
  },
  "projects": {
    "my-api": "/home/user/projects/my-api",
    "work-repo": "/home/user/work/some-repo"
  }
}

| Field | Purpose | |---|---| | baseDir | Base path for underscore-style resolution | | default | Fallback project when no name matches (or no name given) | | channels | Per-channel defaults — each channel can have its own default and baseDir | | projects | Named project shortcuts → absolute paths |

Usage

Spawn a session in Discord

Use the /cursor shortcut (reads from your config):

/cursor                         # spawns in default project (or channel default)
/cursor my-api                  # spawns in named project
/cursor my-api --n My Feature   # spawns with a custom thread label
/cursor --new new-repo          # creates directory if it doesn't exist, then spawns
/cursor --resume                # reattach to an existing thread's Cursor session

⚠️ Type /cursor from the target project channel — the thread is created in whichever channel you invoke the command from.

Once the thread is created, every message (including images) goes directly to Cursor.

File sharing

When Cursor creates a file, it automatically appears in the Discord thread as an attachment. No manual steps needed.

To opt out: set CURSOR_ACP_AUTO_ATTACH=false.

CLI Commands

cursor-acp setup                        Interactive setup
cursor-acp update                       Update to the latest version from npm
cursor-acp resolve <project>            Resolve a project name to its absolute path
cursor-acp thread-get <threadId>        Get the cwd bound to a Discord thread
cursor-acp thread-set <threadId> <cwd>  Bind a Discord thread to a project cwd
cursor-acp --version                    Print version
cursor-acp --help                       Show help

How it works

For a full technical breakdown — architecture, session flow, file attachment pipeline, acpx fork details, release process — see ARCHITECTURE.md.

Development

git clone https://github.com/ZBot-Workspace/cursor-acp.git
cd cursor-acp
npm install
npm run build

After making changes to src/, run npm run build. Install locally with npm install -g ..

License

MIT