# Curxor

> Curxor docs: installation, quickstart, MCP and AI agent setup, CLI reference, and troubleshooting.

## Contents

- [Installation](https://curxor.dev/docs/installation)
- [Quickstart](https://curxor.dev/docs/quickstart)
- [MCP setup](https://curxor.dev/docs/mcp)
- [AI agents](https://curxor.dev/docs/agents)
- [CLI reference](https://curxor.dev/docs/cli)
- [Troubleshooting](https://curxor.dev/docs/troubleshooting)

## Installation

Two steps: install the browser extension from the store, then the CLI with a single command. Check the environment is ready and you're good to go.

### Installation steps

#### Browser extension

**Curxor Browser Extension** — Chrome, Edge & other Chromium browsers. [Install the extension](https://chromewebstore.google.com/detail/fekbfpcglflkdklkonbpkgaofembhabg)

#### Command-line tool

Install with a single command — the service is registered and started automatically (launch at login), no manual `start` needed:

**macOS / Linux**

```
curl -fsSL https://curxor.dev/install.sh | sh -s -- --ensure-path
```

**Windows**

```
& ([scriptblock]::Create((irm https://curxor.dev/install.ps1))) -EnsurePath
```

`--ensure-path` adds the install directory (`~/.local/bin`; the user PATH on Windows) to your shell config so `curxor` works in a new terminal. Open a new terminal after installing — the current one only picks it up once you `source` that config.

To upgrade, run `curxor update` to get the latest version. To only check: `curxor update --check`.

#### Environment check

Once these three are ready, you're good to go:

- **curxor running**: `curxor status` shows a green `● running` plus `Local: http://127.0.0.1:51999`
- **Extension connected**: the toolbar badge shows `ON` (green)
- **Project in dev mode**: started with `vite` / `next dev` — production builds can't locate source (see [troubleshooting](https://curxor.dev/docs/troubleshooting))

### System requirements

- Node.js 20+ — only needed when using built-in agents like Claude Code / Pi (Claude Code requires 22+)
- macOS, Linux, and Windows (desktop)

## Quickstart

Five minutes to your first change: pick an element in the browser, describe it, and let the AI edit the code.

### Before you start

- Your project runs locally with `vite` / `next dev`
- The extension badge shows `ON`
- The CLI is running: `curxor status` shows `● running` and `Local: http://127.0.0.1:51999`

> It has to be **dev mode**. Production builds carry no source paths, so curxor cannot locate the element's source.

### Your first change

1. **Open your dev page**
2. **Select an element and describe the change**
3. **Send it — where the two routes split**
   - **MCP route**: Click `Create task`; a code (`CX-XXXXXX`) is copied to your clipboard — paste it into your editor's AI chat.
   - **Agent route**: Pick an agent (Claude Code / Cursor / Pi) from the select-agent menu and let it take over.
4. **The AI edits, hot reload shows it**
   The AI reads that element's context — source location plus screenshot — and edits the code. Hot reload shows the result right away.

### Link your project

macOS / Linux auto-detect running dev projects. **On Windows you have to link it manually**, otherwise curxor doesn't know which project to resolve source from:

**macOS / Linux**

```
curxor attach http://localhost:5173
```

**Windows**

```
curxor attach http://localhost:PORT
```

Omitting the origin makes curxor scan common ports, but writing it out is more reliable.

## MCP setup

Wire Curxor's MCP server into your AI editor. Once it's set up, the AI can read the source context of any element you select in the page.

### Install

#### Let AI install it

Copy the prompt and paste it into your editor's AI (Claude Code / Cursor / Trae / Qoder / Codex / Pi / OpenCode, and more). It reads Curxor's setup guide and writes the MCP config for you.

```
Read https://curxor.dev/SKILL.md and add the Curxor MCP server to my editor.
```

#### Or merge it manually

Run the command below to print the config snippet (`command` is the absolute path of the `curxor` binary). It writes no files and shows how to merge it per editor — just follow along:

```
curxor mcp --print-config
```

> You'll need to **restart the editor** or **open a new session** for it to take effect (e.g. Claude Code / Cursor / Codex).

#### Verify

After restarting, select an element in the browser → click `Create task` → paste the `CX-XXXXXX` into the AI. If it returns the matching source, you're connected.

### When the editor can't find PATH

Editors launched from the GUI don't inherit your shell PATH, so `command` fails to resolve. Switch it to the absolute path and write it into your editor's MCP config (e.g. the project-root `.mcp.json`):

```
{
  "mcpServers": {
    "curxor": {
      "command": "/Users/you/.local/bin/curxor",
      "args": ["mcp"]
    }
  }
}
```

Take the absolute path from the output of `curxor mcp --print-config`.

## AI agents

Let curxor hand the element you selected straight to an agent. Claude Code, Cursor and Pi are built in; any ACP-compliant agent can be wired up.

> Two integration paths, don't mix them up: MCP targets an **external editor** and hands the selected element's context to the AI there; an Agent targets the **curxor side panel** and drives the agent directly. They're independent and can run at the same time.

### Configuring agents.toml

Agents live in `~/.curxor/agents.toml`; the three built-in entries below are written on first start. Edit that file directly afterwards — saves apply on the next send:

```
[[agents]]
id = "claude"
name = "Claude Code"
command = "npx"
args = ["-y", "@agentclientprotocol/claude-agent-acp@latest"]
probe = "claude"

[[agents]]
id = "cursor"
name = "Cursor"
command = "cursor-agent"
args = ["acp"]
probe = "cursor-agent"

[[agents]]
id = "pi"
name = "Pi"
command = "npx"
args = ["-y", "@curxor/pi-acp@latest"]
probe = "pi"
env = { PI_ACP_KEEP_ALL_SESSIONS = "true" }
permissions = false
```

| Field | Meaning |
| --- | --- |
| `id` | Unique key; used to locate the agent when a request is sent |
| `name` | Label shown in the “select agent” menu |
| `command` / `args` | Command that starts the agent as an ACP server; `args` are its arguments |
| `probe` | Binary used to detect whether the agent is installed; falls back to `command`. Claude Code's `command` is `npx` (always present), so `probe = "claude"` is required to detect it correctly |
| `env` | Extra environment variables injected into the agent process (optional) |
| `permissions` | Whether the agent supports permission prompts. `pi` has no permission dialog, so `false` hides the permission-tier UI (defaults to `true`) |

Curxor only probes via `probe`; it doesn't install agents or manage their sign-in. As long as the binary is on your PATH and the agent is authenticated — via OAuth, API key, enterprise gateway, whatever you use — it just works.

Once installed, the side panel's Settings → Agent settings shows **Installed** and the agent becomes usable in the select-agent menu. Uninstalled entries are still listed, but model loading fails; see [Troubleshooting](https://curxor.dev/docs/troubleshooting).

> **ACP is the key:** as long as the command starts as an ACP server over stdin/stdout, Curxor needs no changes — OpenCode, Trae or your own agent all use the same config.

### Custom agents

Any ACP-compliant agent can be added with an `[[agents]]` entry using the fields above. For example, OpenCode:

```
[[agents]]
id = "opencode"
name = "OpenCode"
command = "opencode"
args = ["acp"]
# env = { SOME_VAR = "value" }   # optional: env vars for the agent process
```

## CLI reference

The local service stays in the background once installed; these commands are for attaching projects, checking status, and other maintenance.

### Commands

- `curxor status` — Show the install state, running state, and health-check results, and print the log path.
- `curxor attach [origin]` — Associate the current project root with a dev server origin; without an origin it scans common ports.
- `curxor mcp --print-config` — Print the editor MCP config snippet (read-only, writes no files).
- `curxor update` — Update to the latest release and restart the local service. `--check` only checks, `--version x.y.z` pins a version.
- `curxor start` — Register (first run) and start the local service; auto-starts at login, and restarts on crash on macOS / Linux.
- `curxor stop` — Stop curxor. It stays stopped until you run `curxor start`.
- `curxor uninstall` — Stop and remove the local service (keeps the binary and `~/.curxor` data).

Running `curxor` with no arguments is the same as `curxor status`. `curxor --help` lists every command; `curxor --version` prints the version.

### Port and logs

- The local service always listens on `127.0.0.1:51999` and never migrates ports; if the port is taken the service fails to start — free it first.
- The log path is printed by `curxor status` (on macOS: `~/Library/Logs/curxor/agent.err.log`).

## Troubleshooting

Diagnose by symptom. Most issues are covered in the first two groups.

### Connection and running

- **Badge shows OFF (red)**: run `curxor status` to check the local service is running; if it isn't, run `curxor start`.
- **CLI not running**: `curxor status` should show a green `● running` and `Local: http://127.0.0.1:51999`; first-time use needs `curxor start`.
- **Local service won't start because the port is taken**: it is pinned to `127.0.0.1:51999` — free that port first.

### AI side not working

- **The AI doesn't recognize the CX code**: MCP isn't active. Run `curxor mcp --print-config`, check that `command` in your editor config matches the printed absolute path, then restart the editor / open a new session.
- **Code invalid or expired**: the pasted code is misspelled, missing, or expired — copy a fresh one in the browser.
- **“Model failed to load” in the picker**: that agent's CLI is missing, not logged in, or not running. Claude Code: `claude` runs and you're logged in. Cursor: `cursor-agent` is on PATH. For any other agent, check that the binary in its `probe` field runs and is logged in.
- **Config changed but nothing happens**: MCP changes need an editor restart or a new session; `agents.toml` saves apply on the next request.

### Can't locate the source

- **Make sure the project runs in dev mode**: production builds carry no usable source paths, and curxor only resolves linked dev projects.
- **Project not linked**: on Windows link it manually with `curxor attach http://localhost:PORT`.

### Logs

`curxor status` prints the log path:

```
curxor status
# the log path is in the output
# macOS: ~/Library/Logs/curxor/agent.err.log
```

Still stuck? Take the output of `curxor status` plus the relevant log lines to [GitHub](https://github.com/curxor-dev/curxor/issues).