Claude Code Setup

Omnodex integrates with Claude Code through its hooks system. Hooks give the deepest tracing of any integration: built-in tools such as file reads, edits, and shell commands are recorded along with MCP calls.

This guide applies to every Claude Code surface that reads project settings: the claude CLI and the IDE extensions (VS Code and compatible editors).

How the integration works

Claude Code runs hooks at specific points during a session. Omnodex registers a hook that records:

Session start and end
Every prompt you submit, in full
Every tool call, with its parameters, timing, and status
Subagents Claude starts, and which tool calls each one made
Permission requests and denials
File reads and writes made by Claude Code’s file tools

The hook runs outside Claude’s context window:

Claude never sees the hook output (zero token overhead)
In monitor and shadow modes, capture does not change what Claude does. Guardrails can stop a call before it runs.
Capture hands the payload to a local background worker, which writes events and runs detection even if a short session has already ended.

Installation

Install Omnodex on the host where you run Claude Code: from npm, or from source including the omnodex-config.json step for hooks.
Set up Claude Code:
Terminal window
```
cd /path/to/your/project
omnodex install claude-code
```
The command asks whether to record every project you open (recommended) or only this one, and installs the hooks and the Omnodex plugin. See Installation.
- Every project writes Omnodex hook entries to ~/.claude/settings.json, your user settings.
- Only this project writes them to .claude/settings.local.json in the project, a file for your machine only that is normally not committed. To write to the shared .claude/settings.json instead, add --project-settings. Use one or the other: hooks in both project files record every event twice.
The plugin adds the omnodex_* tools and the MCP proxy; it is installed for your user with claude plugin install. Add --hooks to install only the hooks.

When it finishes, the command offers to connect to the hosted dashboard. Press Ctrl+C to skip.
Verify it is registered:
Terminal window
```
omnodex status
```
Start a new Claude Code session in the project. Hooks load when a session starts, so sessions that were already open are not traced. If Claude Code asks you to review new hooks, open /hooks and approve the Omnodex entries.

Hook event coverage

Claude Code exposes a growing set of hook events; it supports over 30. Omnodex subscribes to ten of them, and all ten produce traced events:

SessionStart, SessionEnd, PreToolUse, PostToolUse, PostToolUseFailure, UserPromptSubmit, SubagentStart, SubagentStop, PermissionRequest, PermissionDenied

In monitor and shadow modes, SessionStart, SessionEnd, and PreToolUse wait only for a small local handoff before Claude Code continues. Event processing and detection run in a background worker, so a short headless session can exit while that work finishes. The other hooks run asynchronously.

In guardrails mode, PreToolUse runs the decision in the foreground and can stop a call or ask for your confirmation. Claude Code ignores a background hook’s answer, so that decision must finish before the tool runs.

When Claude Code starts a subagent, the subagent’s tool calls are attributed to it, so the trace shows which subagent did what instead of an unexplained run of calls in the parent session. UserPromptSubmit also picks up the session’s title.

After updating Omnodex

A project’s hooks list the events Omnodex subscribed to when you ran omnodex install. When a new version adds events, omnodex status names the missing ones:

  Claude Code (settings.local.json): installed
    missing hooks: PermissionRequest, PermissionDenied (installed by an older version)

After updating to omnodex 0.10.0 or later, rerun omnodex install claude-code to refresh the capture handoff even if no events are missing from the registration. Choose the same installation scope as before: every project or only this project, with --project-settings if you used shared project settings. To update only the hooks, add --hooks.

The installer replaces Omnodex’s own entries rather than duplicating them and leaves your other hooks alone. Start a new session to load the updated entries. This refresh also adds any missing events named by omnodex status.

What gets traced

Event type	When it is written
`session.started`	A Claude Code session starts
`session.ended`	The session ends
`session.renamed`	The session’s title changes: you renamed it with `/rename`, or Claude Code named it. Checked at session start, at each prompt, and at session end
`session.model_changed`	The session’s model is first seen, or changes, read from Claude Code’s session transcript. Checked at session start, at each prompt, and at session end. See Which model a session used
`prompt.submitted`	You submit a prompt. Includes the full prompt text
`tool.invoked`	Claude calls any tool, including MCP tools. Includes the tool name, parameters, and working directory. Calls made inside a subagent carry its `agent_id`
`tool.completed`	The tool call finishes. Includes duration, success or error, and response size
`file.read`	Claude reads files with `Read`, `NotebookRead`, `Grep`, or `Glob`
`file.written`	Claude writes files with `Write`, `Edit`, or `NotebookEdit`
`subagent.started`	Claude starts a subagent. Includes its type (for example `Explore`)
`subagent.stopped`	The subagent finishes. Includes how long it ran and the size of its final message
`permission.requested`	Claude Code asks you to allow a tool call. Includes the tool and its parameters
`permission.denied`	A tool call is refused, by you, a permission rule, or the permission classifier. Includes the reason

Tool results and a subagent’s final message are not stored; only their size is. See Event Schema for the fields.

Viewing results

# Live dashboard
omnodex dashboard

# Run detection on collected events
omnodex detect

# Text summary
omnodex report

Troubleshooting

No events after installing:

Start a new session. Sessions opened before omnodex install do not load the hook.
Run omnodex status in the project to confirm the hook is installed.
Check launcher.log in your Omnodex home. Could not locate claude-code hook shim means the launcher could not find Omnodex: for a source install, omnodex-config.json is missing or has the wrong claude-code path; for an npm install, omnodex is not on the PATH Claude Code runs hooks with.
Look for a new session file under event-log/sessions/ in your Omnodex home.

The project is also used from another host: a project folder holds hooks for one host at a time. If you run Claude Code in both native Windows and WSL, see Windows and WSL.

Other Claude surfaces

Cowork uses a plugin and the MCP proxy instead of hooks. See Cowork Desktop Setup.
Claude Desktop (chat app) has no hooks, but you can route its MCP servers through the Omnodex proxy. See MCP Proxy for Any Client.
claude.ai on the web does not run hooks or MCP servers on your machine, so Omnodex cannot trace it locally.

Using the MCP proxy with Claude Code

Hooks already record MCP tool calls in Claude Code, so the MCP proxy is optional here. It comes with the Omnodex plugin that omnodex install claude-code installs. Use it if you want parameter redaction per MCP server or the omnodex_* tools inside Claude Code; see Configuration.

For remote MCP servers you configure alongside Omnodex, use the http (streamable HTTP) transport; sse is deprecated in Claude Code.

Next steps

Running Detection - Configure risk detection rules
Choosing a Dashboard - The local and hosted dashboards