Skip to content
OmnodexOmnodexOmnodex Docs

Installation

The Quick Start covers the usual path: npm install -g omnodex, then omnodex install. This page covers the choices behind it, updating, removing, and installing from source.

Requirements

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

Install Omnodex

Section titled “Install Omnodex”

Install on the host where your agents run.

Terminal window
npm install -g omnodex
omnodex --version

To run unreleased code instead, see Install from source.

Set up your agents

Section titled “Set up your agents”
Terminal window
omnodex install

With no agent named, Omnodex looks for Claude Code, Codex and Antigravity on this machine, shows what it will write, and asks once before writing anything. Each agent gets two parts:

  • Hooks, which record what the agent does: tool calls, shell commands, file edits and session events.
  • The Omnodex plugin, which runs the MCP proxy and gives the agent Omnodex’s own tools, such as omnodex_status.

To set up one agent, name it:

Terminal window
omnodex install claude-code
omnodex install codex
omnodex install antigravity   # or: omnodex install agy

--hooks or --plugin installs only that part. --yes answers the questions with the recommended choices, for scripts and setups without a terminal.

Every project, or one project

Section titled “Every project, or one project”

omnodex install asks whether to record every project you open or only the current one.

  • Every project (recommended) puts the hooks in the agent’s own user settings, so new projects are recorded without another install.
  • Only this project puts them in the project folder, as earlier versions did.

--everywhere and --this-project answer the question up front. Without a terminal and without either flag, hooks go into the project.

RecordsHooks are written to
Every project~/.claude/settings.json
This project.claude/settings.local.json in the project (--project-settings for .claude/settings.json)

The plugin is installed for your user with claude plugin install. Start a new session to load both.

On Windows the same files live under C:\Users\<you>\.

Leave a project out

Section titled “Leave a project out”

To stop recording one project while every other project is still recorded, run this in that project:

Terminal window
omnodex uninstall codex

Name the agent, or leave it out to apply to all of them. omnodex status in the project shows it as left out, and omnodex install codex there records it again. A folder inside a left-out project is left out too.

Check what is set up

Section titled “Check what is set up”
Terminal window
omnodex status         # this project
omnodex status --all   # everything on this host

Plugin versions

Section titled “Plugin versions”

Each release of Omnodex installs the plugin version it was tested with, downloaded from downloads.omnodex.com and checked against the checksum the release carries. If the download fails, for example on a network that blocks the domain, the hooks are still installed and the command prints how to retry.

ToRun
Install the newest published pluginomnodex install codex --plugin --plugin-version latest
Install a specific published versionomnodex install codex --plugin --plugin-version 0.1.2
Install a plugin file you downloadedomnodex install codex --plugin --from omnodex-codex.plugin

A file passed with --from must match a published checksum. For a file that is not published, add --sha256 <checksum> to confirm you trust it. The files, and the release list with each version’s checksum, are on Plugins.

Updating

Section titled “Updating”
Terminal window
omnodex update

This installs the latest release with npm, then brings each installed plugin to the version that release ships. A plugin version you chose with --plugin-version is kept until a release ships a newer one. Hooks need no reinstall: they run a small launcher in ~/.omnodex/bin/ that finds the updated install by itself. Start a new agent session afterwards.

omnodex update --check shows what would change without installing. Omnodex also checks for releases in the background and prints a one-line notice when there is one.

Update each host separately: on Windows, PowerShell and WSL each have their own install. A source install updates with the same command; see Install from source.

Uninstalling

Section titled “Uninstalling”
To removeRun
Omnodex from this project (or leave it out, when recording every project)omnodex uninstall [agent]
Every-project recordingomnodex uninstall [agent] --everywhere
An agent’s pluginomnodex uninstall <agent> --plugin

Each command shows what it will change and asks first; --confirm skips the question. Only what Omnodex added is removed: other hooks, plugins and settings in the same files stay, and so does your event data.

Remove Omnodex completely

Section titled “Remove Omnodex completely”
Terminal window
omnodex uninstall --everywhere --confirm      # hooks in every agent's user settings
omnodex uninstall claude-code --plugin --confirm
omnodex uninstall codex --plugin --confirm
omnodex uninstall antigravity --plugin --confirm
omnodex clear --all --confirm                 # events, settings and the dashboard connection
npm uninstall -g omnodex

Projects installed with “only this project” keep their hooks until you run omnodex uninstall in each; omnodex status --all lists them.

Where Omnodex stores data

Section titled “Where Omnodex stores data”

Event logs and settings are in ~/.omnodex on each host (C:\Users\<you>\.omnodex on native Windows). Set OMNODEX_HOME to use another folder.

  • event-log/: the append-only event log, one JSONL file per session (the source of truth)
  • traces.db: a SQLite read model built from the event log, safe to delete
  • installations.json and hook-scope.json: what Omnodex installed, and which projects are recorded
  • omnodex-proxy.json: MCP proxy settings (optional)
  • stream-config.json: the hosted dashboard connection, written by omnodex connect
  • launcher.log: hook and proxy launcher failures

See Configuration for the full layout. To see several hosts together, add the other host’s folder to the local dashboard (omnodex dashboard --roots <path>, see Local Dashboard), or connect each host to the same hosted dashboard account.

Install from source

Section titled “Install from source”

A source install runs the latest code from the repository, which can be ahead of the last npm release.

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

omnodex --version then prints the branch and commit, for example 0.0.0 (source: main @ a881f59); a + after the hash means local changes. omnodex update from inside the clone runs git pull --ff-only, npm install and the build.

Point hooks at your build

Section titled “Point hooks at your build”

omnodex install checks that the hook launchers can find your build, and when they cannot, it records the build’s location in omnodex-config.json in your Omnodex home for you. Check it with omnodex status. To set it by hand, use absolute paths to your clone:

{
  "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"
  }
}

On Windows, write the paths with escaped backslashes ("C:\\path\\to\\omnodex\\..."). When you switch back to an npm install, remove shim_paths from omnodex-config.json and proxy_bin from omnodex-proxy.json; they point at your build and win over the npm install.

Next steps

Section titled “Next steps”