Skip to content

Cursor Setup

Omnodex traces the agent in Cursor through Cursor’s hooks. Requires omnodex 0.15.0 or later.

omnodex install cursor writes Cursor hooks. There is no Omnodex plugin to download for Cursor: the CLI writes Cursor’s own configuration directly.

PartWhat it doesHow to get it
HooksRecord sessions, prompts, tool calls before and after they run, failed calls, subagents and the model in use. In guardrails mode they can stop a call or raise Cursor’s own promptomnodex install cursor
MCP proxy entry (optional)Routes the MCP servers you choose through the Omnodex proxy, which records each call with its timing and response sizeAdd --mcp
  1. Install Omnodex on the host where Cursor runs. For the Cursor app on Windows, that is PowerShell, not WSL.

  2. Set up Cursor:

    Terminal window
    cd /path/to/your/project
    omnodex install cursor

    The command asks whether to record every project you open (recommended) or only this one. Omnodex adds its entries to Cursor’s hooks file and leaves your other hooks alone:

    RecordsHooks are written to
    Every project~/.cursor/hooks.json
    This project.cursor/hooks.json in the project

    When it finishes, the command offers to connect to the hosted dashboard. Press Ctrl+C to skip.

  3. Verify:

    Terminal window
    omnodex status
  4. Restart Cursor. Cursor reads hooks.json when it starts, so a window that was already open does not run the new hooks. Then have the agent run a command, and look for a new session file under event-log/sessions/ in your Omnodex home, or open omnodex dashboard.

Project hooks name this machine’s paths. Recording every project keeps them in your home folder; if you record only this project, keep .cursor/hooks.json out of commits so it does not reach machines where those paths do not exist.

Cursor’s hooks already record MCP tool calls. The proxy adds measured response size and parameter redaction for the servers you move into it.

Terminal window
omnodex mcp-proxy install # creates omnodex-proxy.json if it is missing
omnodex install cursor --mcp

--mcp adds an omnodex server to ~/.cursor/mcp.json and keeps every other server in the file. Then move the servers you want recorded from that file into upstream_servers in omnodex-proxy.json; see MCP Proxy for Any Client.

Event typeWhen it is written
session.startedA Cursor conversation starts
session.endedThe conversation ends, with whether it completed, failed or was interrupted
session.model_changedThe conversation’s model is first seen, or changes. Cursor names the model with every hook
prompt.submittedYou submit a prompt. Includes the full prompt text
tool.invokedThe agent is about to run a tool: shell commands, file reads and edits, MCP tools. Includes the tool name and parameters
tool.completedThe tool call finishes, with success or error and how long it took
file.read, file.writtenThe agent reads or writes files with its file tools
subagent.started, subagent.stoppedThe agent starts or finishes a subagent

Events carry interceptor: "cursor-hook" and platform: "cursor". Tool output is measured, not stored. Cursor includes your signed-in email address in every hook; Omnodex drops it before anything is written, so it never reaches the event log or a dashboard.

In guardrails mode, Omnodex answers each tool call before it runs:

  • Stop: Cursor refuses the call, and the agent sees Omnodex’s reason.
  • Hold for confirmation: shell commands, MCP calls and file reads raise Cursor’s own permission prompt, with Omnodex’s reason. Other tools, such as file edits, are stopped instead, and the agent is told to ask you before trying again.

Nothing changes in Cursor’s hooks when you switch modes. When something goes wrong inside Omnodex, its hooks still answer with valid JSON and no decision, so the call goes through your own Cursor settings as usual.

  • Only some tools can ask. Cursor gives its permission prompt to shell commands, MCP calls and file reads. Its general tool hook can only allow or refuse, so a held call to any other tool is stopped rather than held.
  • Model replies are not captured. Omnodex records what the agent does, not what it says, and does not subscribe to Cursor’s hooks for the model’s replies and reasoning.
  • Tab completions are not captured. They are editor suggestions, not agent actions.
  • The editor’s agent. Cursor documents its hooks for the agent in the Cursor editor. Its cursor-agent CLI is not documented to run them, so this guide does not cover it.
To removeRun
Omnodex from this project (or leave it out, when recording every project)omnodex uninstall cursor
Every-project recordingomnodex uninstall cursor --everywhere
The MCP proxy entryomnodex uninstall cursor --mcp (0.15.1 or later)

Each command shows what it will change and asks first. Other hooks and MCP servers stay, and so does your event data. Restart Cursor afterwards. See Uninstalling.

No events after installing:

  • Restart Cursor. It reads hooks.json only at startup.
  • Run omnodex status in the project to confirm the hooks are installed.
  • Check launcher.log in your Omnodex home. Could not locate cursor hook shim means the launcher could not find Omnodex: for a source install, omnodex-config.json is missing a cursor entry under shim_paths; for an npm install, omnodex is not on the PATH Cursor runs hooks with. Start Cursor from a terminal where omnodex works, or reinstall from the same host.