Cursor Setup
Omnodex traces the agent in Cursor through Cursor’s hooks. Requires omnodex 0.15.0 or later.
What gets installed
Section titled “What gets installed”omnodex install cursor writes Cursor hooks. There is no Omnodex plugin to download for Cursor: the CLI writes Cursor’s own configuration directly.
| Part | What it does | How to get it |
|---|---|---|
| Hooks | Record 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 prompt | omnodex 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 size | Add --mcp |
Install
Section titled “Install”-
Install Omnodex on the host where Cursor runs. For the Cursor app on Windows, that is PowerShell, not WSL.
-
Set up Cursor:
Terminal window cd /path/to/your/projectomnodex install cursorThe 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:
Records Hooks are written to Every project ~/.cursor/hooks.jsonThis project .cursor/hooks.jsonin the projectWhen it finishes, the command offers to connect to the hosted dashboard. Press Ctrl+C to skip.
-
Verify:
Terminal window omnodex status -
Restart Cursor. Cursor reads
hooks.jsonwhen 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 underevent-log/sessions/in your Omnodex home, or openomnodex 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.
Route MCP servers through the proxy
Section titled “Route MCP servers through the proxy”Cursor’s hooks already record MCP tool calls. The proxy adds measured response size and parameter redaction for the servers you move into it.
omnodex mcp-proxy install # creates omnodex-proxy.json if it is missingomnodex 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.
What gets traced
Section titled “What gets traced”| Event type | When it is written |
|---|---|
session.started | A Cursor conversation starts |
session.ended | The conversation ends, with whether it completed, failed or was interrupted |
session.model_changed | The conversation’s model is first seen, or changes. Cursor names the model with every hook |
prompt.submitted | You submit a prompt. Includes the full prompt text |
tool.invoked | The agent is about to run a tool: shell commands, file reads and edits, MCP tools. Includes the tool name and parameters |
tool.completed | The tool call finishes, with success or error and how long it took |
file.read, file.written | The agent reads or writes files with its file tools |
subagent.started, subagent.stopped | The 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.
Guardrails
Section titled “Guardrails”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.
Limits
Section titled “Limits”- 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-agentCLI is not documented to run them, so this guide does not cover it.
Uninstall
Section titled “Uninstall”| To remove | Run |
|---|---|
| Omnodex from this project (or leave it out, when recording every project) | omnodex uninstall cursor |
| Every-project recording | omnodex uninstall cursor --everywhere |
| The MCP proxy entry | omnodex 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.
Troubleshooting
Section titled “Troubleshooting”No events after installing:
- Restart Cursor. It reads
hooks.jsononly at startup. - Run
omnodex statusin the project to confirm the hooks are installed. - Check
launcher.login your Omnodex home.Could not locate cursor hook shimmeans the launcher could not find Omnodex: for a source install,omnodex-config.jsonis missing acursorentry undershim_paths; for an npm install,omnodexis not on thePATHCursor runs hooks with. Start Cursor from a terminal whereomnodexworks, or reinstall from the same host.
Next steps
Section titled “Next steps”- Shadow Mode and Guardrails - Stop or hold risky calls
- MCP Proxy for Any Client - How the proxy works
- Running Detection - Risk detection works the same across all agents