Installation

System requirements

Requirement	Minimum
Node.js	24+ (uses `node:sqlite`)
npm	9+
OS	macOS, Linux, Windows (native or WSL)
Disk	About 50 MB for Omnodex, plus space for event logs

Install on the host where your agent runs

Omnodex runs on the same host as the agent it traces. On Windows, native Windows and WSL are separate hosts: each has its own home directory, its own agent configuration, and its own Omnodex data. Desktop apps such as Cowork and ChatGPT Desktop run on native Windows. Terminal tools you start inside WSL run in WSL.

Run the commands on this page in the shell of that host: PowerShell for native Windows, a WSL terminal for WSL, and your normal terminal on macOS and Linux. If you use agents on both native Windows and WSL, install on both. See Windows and WSL for how the two hosts fit together.

Install Omnodex

Install from npm unless you want to run unreleased changes. An npm install needs no clone or build and includes the hook handlers and the MCP proxy. A source install runs the latest code from the repository, which can be ahead of the last npm release.

Pick your install method once: the choice carries over to every other page in these docs.

Installed from npm
Installed from source

In the shell of the host where your agent runs:

Windows (PowerShell)
macOS / Linux / WSL

node --version
npm install -g omnodex
omnodex --version
where.exe omnodex-mcp-proxy

node --version
npm install -g omnodex
omnodex --version
command -v omnodex-mcp-proxy

omnodex --version prints the release, for example 0.3.0. The hook launchers and the Omnodex plugins find an npm install on their own, so there is nothing else to configure. Continue with Install the hooks and your agent’s setup guide.

If you are switching from a source install, remove shim_paths from omnodex-config.json and proxy_bin from omnodex-proxy.json. Those point the launchers at your source build, and they win over the npm install. Keep the rest of both files, including your upstream servers.

Windows (PowerShell)
macOS / Linux / WSL

git clone https://github.com/omnodex/omnodex.git
cd omnodex
npm install
npx tsc -b
npm install -g .\packages\cli

git clone https://github.com/omnodex/omnodex.git
cd omnodex
npm install
npx tsc -b
npm install -g ./packages/cli

The last command links the omnodex command to your build, so it works from any directory and picks up changes when you rebuild. Check it with omnodex --version: a source install prints the branch and commit, for example 0.0.0 (source: main @ a881f59). A + after the hash means the checkout has local changes.

If omnodex is not on your PATH, run the CLI directly with node <repo>/packages/cli/dist/index.js (on Windows, node <repo>\packages\cli\dist\index.js).

Point hooks at your build

Hooks call a small launcher in ~/.omnodex/bin/, which loads the hook handler from your Omnodex install. For a source install, tell the launcher where the handlers are in omnodex-config.json in your Omnodex home:

Windows (PowerShell)
macOS / Linux / WSL

C:\Users\<you>\.omnodex\omnodex-config.json. JSON strings need escaped backslashes:

{
  "shim_paths": {
    "claude-code": "C:\\path\\to\\omnodex\\packages\\hooks-provider\\dist\\bin\\claude-hook-shim.js",
    "codex": "C:\\path\\to\\omnodex\\packages\\codex-provider\\dist\\bin\\codex-hook-shim.js",
    "antigravity": "C:\\path\\to\\omnodex\\packages\\antigravity-provider\\dist\\bin\\antigravity-hook-shim.js"
  }
}

~/.omnodex/omnodex-config.json:

{
  "shim_paths": {
    "claude-code": "/path/to/omnodex/packages/hooks-provider/dist/bin/claude-hook-shim.js",
    "codex": "/path/to/omnodex/packages/codex-provider/dist/bin/codex-hook-shim.js",
    "antigravity": "/path/to/omnodex/packages/antigravity-provider/dist/bin/antigravity-hook-shim.js"
  }
}

Use absolute paths to your clone. You only need entries for the agents you use. Without this file, hooks run but the launcher cannot find a handler, and nothing is recorded (the failure is written to launcher.log in your Omnodex home).

Updating

Updating has two parts: the Omnodex runtime on each host, and, if you use one, the Omnodex plugin in your agent app. Update the runtime first. Run updates from PowerShell for native Windows agents and from a WSL terminal for WSL agents; updating one does not update the other.

Installed from npm
Installed from source

In the host’s shell:

omnodex update
omnodex --version

omnodex update installs the latest release with npm install -g, and omnodex update --check shows what is available without installing. Omnodex also checks for a new release in the background and prints a one-line notice when there is one. npm install -g omnodex@latest does the same thing by hand.

On each host where you installed Omnodex, from inside your clone:

omnodex update

This runs git pull --ff-only, npm install, and npm run build, and warns you first if the checkout has uncommitted changes. To see what is available without installing, run omnodex update --check. Omnodex also checks for updates in the background and prints a one-line notice when one is available.

If your clone lives under /mnt/c/... and you build it from WSL, tsc -b can skip changed files because of how file timestamps cross the WSL boundary. If a change does not show up after a build, run npx tsc -b --force.

Hooks and the MCP proxy load your install at runtime, so most updates need no per-project reinstall. Releases that change which hook events are installed still require reinstalling those hooks. For the Antigravity hook migration, run omnodex install antigravity in each project after updating. An MCP entry keeps working while the paths it names remain valid.

Then update each agent

Agent	How it uses Omnodex	After updating the runtime
Claude Code	Project hooks	Start a new session
Cowork	Plugin	Replace the plugin if a new plugin version is available, then fully quit and reopen Cowork
OpenAI Codex	Project hooks, and the Omnodex plugin or a manual MCP server entry	Update the plugin if needed and restart Codex, then start a new conversation
Google Antigravity	Project hooks and an MCP entry or plugin	Update the runtime, update the plugin only if needed, and reload Antigravity

Plugin versions are independent of npm and source runtime versions. A runtime update alone does not require a plugin reinstall. The current version of each plugin is listed in the release manifest, and all downloads are on Plugins. When a plugin changes, follow your agent’s update instructions and replace the existing installation rather than adding a second copy.

Where Omnodex stores data

By default, Omnodex stores event logs and configuration in ~/.omnodex on the host where the agent runs (C:\Users\<you>\.omnodex on native Windows). Override it with the OMNODEX_HOME environment variable:

export OMNODEX_HOME=/path/to/your/omnodex/data

The directory contains:

event-log/ - the append-only event log, one JSONL file per session (source of truth)
traces.db - SQLite read model, derived from the event log and safe to delete
config.json - local configuration
omnodex-config.json - hook handler locations (source installs) and extra workspace roots
omnodex-proxy.json - MCP proxy configuration (optional)
stream-config.json - cloud dashboard connection, written by omnodex connect
launcher.log - hook and proxy launcher failures

See Configuration for the full layout.

Install the hooks

Hooks are installed per project. Run the command from the project directory, or pass the project path as an argument.

omnodex install claude-code

Writes Omnodex hook entries to .claude/settings.local.json in the project. Claude Code loads them when a session starts, so start a new session afterwards. See the Claude Code guide.

omnodex install codex

Writes Omnodex hook entries to .codex/hooks.json in the project. Codex asks you to trust new hooks before they run. This command installs hooks only; install the Omnodex plugin separately for the MCP connection, or register the server manually.

omnodex install antigravity

Writes Omnodex hook entries to .agents/hooks.json in the project. See Antigravity capture behavior for the events they record. Registering the Omnodex MCP server is separate: use the direct MCP setup for capture without project hooks. --mcp alone requests only a project MCP entry pointing at an installed plugin launcher; use --hooks --mcp to explicitly request both.

After installing, omnodex install offers to connect this host to the hosted dashboard. If you do not want to connect yet, press Ctrl+C at that prompt; the hooks are already installed.

To check what is installed in a project:

omnodex status

Cowork does not use project hooks. It uses a plugin and the MCP proxy; see the Cowork guide.

Combine data from several hosts

Each host keeps its own Omnodex data. You can view them together in two ways:

Local dashboard: add the other host’s Omnodex directory as an extra root (dashboard.roots in config.json, or omnodex dashboard --roots <path>). See Local Dashboard.
Hosted dashboard: run omnodex connect on each host with the same account. Each host appears as its own machine.

Uninstall hooks

To remove Omnodex hooks from a project:

omnodex uninstall --confirm

This removes all Omnodex hooks from the project and keeps your event data. To remove hooks for one agent only:

omnodex uninstall claude-code --confirm

Uninstall Omnodex completely

# 1. Remove hooks from every project where Omnodex is installed
#    (omnodex status --all lists them)
omnodex uninstall --confirm

# 2. Delete the Omnodex home: events, configuration, and cloud connection
omnodex clear --all --confirm

# 3. Remove the global command
npm uninstall -g omnodex        # installed from npm
npm uninstall -g @omnodex/cli   # installed from source; then delete your clone