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)
The hook cannot change what Claude does
The hook exits quickly after appending events, so it does not hold up the session

Installation

Install Omnodex on the host where you run Claude Code: from npm, or from source including the omnodex-config.json step for hooks.
Install the hook into your project:
Terminal window
```
cd /path/to/your/project
omnodex install claude-code
```
This writes Omnodex hook entries to .claude/settings.local.json in the project. That file is for your machine only and is normally not committed. To write to the shared .claude/settings.json instead, add --project-settings. Use one or the other: hooks in both files record every event twice.

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

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)

Run omnodex install claude-code in that project again (with --project-settings if you installed there). It adds the missing hooks, replaces Omnodex’s own entries rather than duplicating them, and leaves your other hooks alone. Start a new session to load them.

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
`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. 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