Installation

System Requirements

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

Note

Node.js 24+ is required because Omnodex uses the built-in node:sqlite module. Earlier versions of Node.js will not work.

Install from npm

npm install -g omnodex

This installs the omnodex command globally. Verify the installation:

omnodex status

Install from Source

If you want to contribute or run the latest development code:

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

This builds all packages in the monorepo. The CLI is then available via npx omnodex from within the repo directory.

Configure OMNODEX_HOME

By default, Omnodex stores event logs and configuration in ~/.omnodex. You can override this with the OMNODEX_HOME environment variable:

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

This directory will contain:

• events.jsonl - The append-only event log (source of truth)
• omnodex.db - SQLite read model (derived, can be rebuilt from the event log)
• config.json - Local configuration

Install the Hook

Claude Code

omnodex install claude-code

This registers a Claude Code hook that fires on every tool invocation. The hook runs asynchronously and does not affect Claude’s execution speed or token usage.

To verify the hook is installed:

omnodex status

OpenAI Codex (Beta)

omnodex install codex

This creates a .codex/hooks.json file that integrates with OpenAI Codex’s hook system. Currently captures bash commands and session lifecycle events.

Caution

OpenAI Codex integration is in beta. File writes, MCP calls, and web search events are not yet intercepted by the Codex runtime. Coverage will expand as Codex adds upstream hook support.

Google Antigravity

omnodex install antigravity --hooks --mcp

This creates .agents/hooks.json for hook-based tracing and .agents/mcp_config.json for the MCP proxy. Use --hooks or --mcp individually to install only one. Works across all Antigravity surfaces (CLI, Desktop App, IDE extensions).

See the Antigravity setup guide for platform-specific details.

Multi-Root Dashboard

If you use multiple AI tools that write to different OMNODEX_HOME directories (for example, Antigravity Desktop on Windows alongside Claude Code in WSL), you can aggregate all event logs into a single dashboard:

~/.omnodex/config.json

{
  "dashboard": {
    "roots": [
      "/home/user/.omnodex",
      "/mnt/c/Users/user/.omnodex"
    ]
  }
}

The dashboard will merge sessions from all roots, tagging each with its source.

Uninstall Hooks

To remove Omnodex hooks from a project:

omnodex uninstall --confirm

This removes all installed hooks but preserves your event data. To remove hooks for a specific agent only:

omnodex uninstall claude-code --confirm

Uninstall Omnodex Completely

To fully remove Omnodex from your system:

# 1. Remove hooks from all projects where Omnodex is installed
omnodex uninstall --confirm

# 2. Delete all event data and configuration
omnodex clear --all --confirm

# 3. Remove the global npm package
npm uninstall -g omnodex

After step 3, the omnodex command will no longer be available. If you installed from source, delete the cloned repo directory as well.

Next Steps

• Claude Code Setup - Detailed guide for the Claude Code integration
• OpenAI Codex Setup - Detailed guide for the Codex integration (beta)
• Google Antigravity Setup - CLI, Desktop App, and IDE setup
• Cowork Desktop Setup - Plugin installation and proxy configuration for Cowork
• Configuration Reference - All configuration options