Getting started

Installation

Install the @xorox-ai/agent package, what it configures, and how to update or remove it.

Prerequisites

• Node.js 18 or later.
• A XOROX project and a project credential — see Authentication.
• Cursor or Claude Code — both are supported.

Supported platforms

The local runtime ships as a prebuilt binary for:

• macOS — Apple Silicon and Intel
• Linux — x64 and arm64
• Windows — x64 and ARM64

Install

Run this inside the project you're coding in — not globally:

npm install @xorox-ai/agent

The package has no command-line entry point. It's a dependency that configures Cursor and Claude Code through a postinstall step; there's nothing to run by hand.

What postinstall does

Installing (or reinstalling) the package runs a postinstall script that configures both agents:

• Adds a beforeSubmitPrompt entry to .cursor/hooks.json and an xorox entry to .cursor/mcp.json's mcpServers, creating either file if it doesn't exist yet.
• Adds a SessionStart hook entry to .claude/settings.json and an xorox entry to .mcp.json's mcpServers (at the project root), creating either file if needed.
• Existing entries from other tools in any of these files are left alone.
• Checks that your OS and architecture have a matching runtime binary, and warns (without failing the install) if not.

None of these files store your credentials — the hooks and the MCP server read them from your project's .env at call time.

The local runtime

XOROX also includes a small background process — a prebuilt binary matching your platform — that serves Ruleset context to the Cursor hook. You don't start it yourself: the hook starts it automatically the first time it's needed, not during installation. Claude Code doesn't use this process at all — its SessionStart hook and MCP server talk to the XOROX API directly.

• It binds 127.0.0.1 only and is never reachable from outside your machine.
• It picks the first free port in the 47821–47921 range.
• It records non-secret bookkeeping — project id, port, process id, package version — in the project's .xorox/runtime.json.
• If a stale runtime from an older package version is still running, the hook replaces it automatically the next time it fires.

Updating

Re-run the install command to update to the latest version:

npm install @xorox-ai/agent@latest

Postinstall runs again and migrates your .cursor/hooks.json, .cursor/mcp.json, .claude/settings.json, and .mcp.json entries if needed, without duplicating them. The background runtime process Cursor uses updates itself automatically the next time it's used.

Uninstalling

1. Remove the xorox entry from .cursor/mcp.json and from .mcp.json.
2. Remove the beforeSubmitPrompt entry whose command references @xorox-ai/agent/hooks/before-submit.js from .cursor/hooks.json, and the SessionStart entry referencing hooks/claude-session-start.js from .claude/settings.json.
3. Delete the project's .xorox/ directory.
4. Run npm uninstall @xorox-ai/agent.

The background runtime process is detached from Node, so it keeps running until your machine stops it or you end it yourself — removing the files above stops anything from starting it again.