Getting started

Quickstart

Go from no XOROX account to a working Cursor integration with automatic Ruleset context.

This walks through the shortest path from no XOROX account to a Cursor session that automatically receives your project's Ruleset context and can use XOROX's MCP tools. It takes about ten minutes.

1. Create a project

Sign up and create a workspace if you don't have one yet — a workspace holds your projects, rules, specifications, and team. Then open Projects and create a project for the codebase you're connecting.

2. Create a project credential

Open the project's Credentials tab and create a credential. This returns a one-time XOROX_TOKEN — copy it now, it cannot be viewed again. See Authentication for details.

3. Install the agent package

In the project you're coding in (the same one Cursor opens), run:

npm install @xorox-ai/agent

This registers a Cursor hook and an MCP server for the project. See Installation for what it changes on disk.

4. Add your credentials to .env

Add both values from step 2 to the project's .env file:

.env

XOROX_PROJECT_ID=your-project-id
XOROX_TOKEN=your-token

Keep XOROX_TOKEN private and don't commit it. Add .env to .gitignore if it isn't already ignored.

5. Reopen the project in Cursor

Cursor reads .cursor/hooks.json and .cursor/mcp.json when a project loads, not continuously — reopen the project so it picks up the new hook and MCP server.

6. Enable the XOROX MCP server

Cursor detects the project's MCP server automatically but doesn't enable it for you. Open Cursor Settings → Tools & MCP, find xorox, and enable it. Then start a new Agent chat — a chat already open may still be using the old tool list.

7. Create a ruleset

Back in the project's Documents tab, create a new document of type Ruleset. New documents are active by default, which is what makes them reach the agent — see Rulesets.

8. Verify the ruleset reaches the agent

In the new Agent chat, send a prompt that depends on something specific in the ruleset you just wrote — for example, ask the agent to state a convention from it. Every prompt in that project runs through the hook, so if the agent reflects the ruleset back, context is being injected correctly.

The hook fails open: if XOROX is unreachable or misconfigured, your prompt still goes through, just without the extra context. See Troubleshooting if the agent doesn't seem to know about your ruleset.

9. Use Specifications and Tasks through MCP

Create a specification and a task from the dashboard, then ask the agent to work on it — for example, "what's the next task?" or "start the next task." The agent calls XOROX's MCP tools to retrieve it. The first time it calls a XOROX tool, Cursor will ask for permission (Run or Always run).

That's the full loop: Rulesets arrive automatically, Specifications and Tasks are retrieved on demand. See Specifications, Tasks, and MCP tools for the full model.