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 tool call, with its parameters, timing, and status
• 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

1. Install Omnodex on the host where you run Claude Code. See Installation, including the omnodex-config.json step for hooks.

2. Install the hook into your project:

   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.

3. Verify it is registered:

   omnodex status

4. 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. As of August 2026 the platform supports over 30. Omnodex subscribes to eight of them:

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

Five of those currently produce traced events. UserPromptSubmit, SubagentStart, and SubagentStop are received but not yet recorded, because the Omnodex event model does not yet define types for prompt and subagent lifecycle. The hooks are already registered, so once those event types ship, the additional coverage begins working with no reinstallation and no config change.

Subagent tracing is the most valuable of the three. When Claude Code spawns a subagent, its tool calls will appear in the trace attributed to that subagent rather than showing up as an unexplained gap in the parent session.

What gets traced

Event type	When it is written
session.started	A Claude Code session starts
session.ended	The session ends
tool.invoked	Claude calls any tool, including MCP tools. Includes the tool name, parameters, and working directory
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

Tool results 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 omnodex-config.json is missing or has the wrong claude-code path.
• 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
• Using the Dashboard - Navigate the real-time dashboard