Skip to content
Omnodex Omnodex Omnodex Docs

Installation

System requirements

Section titled “System requirements”
RequirementMinimum
Node.js24+ (uses node:sqlite)
npm9+
OSmacOS, Linux, Windows (native or WSL)
DiskAbout 50 MB for Omnodex, plus space for event logs

Install on the host where your agent runs

Section titled “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 from source

Section titled “Install from source”
Terminal window
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:

Terminal window
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, you can always 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

Section titled “Point hooks at your build”

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

~/.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

Section titled “Updating”

From inside your clone:

Terminal window
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.

Hooks and the proxy load your build at runtime, so there is nothing to reinstall per project after an update. Restart desktop apps (Cowork, ChatGPT Desktop) so they start the rebuilt proxy.

Where Omnodex stores data

Section titled “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:

Terminal window
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)
  • 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

Section titled “Install the hooks”

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

Terminal window
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.

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:

Terminal window
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

Section titled “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 Using the Dashboard.
  • Hosted dashboard: run omnodex connect on each host with the same account. Each host appears as its own machine.

Uninstall hooks

Section titled “Uninstall hooks”

To remove Omnodex hooks from a project:

Terminal window
omnodex uninstall --confirm

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

Terminal window
omnodex uninstall claude-code --confirm

Uninstall Omnodex completely

Section titled “Uninstall Omnodex completely”
Terminal window
# 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/cli

Then delete your clone.

Next steps

Section titled “Next steps”