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.

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.

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.

curxor status prints the log path:

bash

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.