Skip to content
Omnodex Omnodex Omnodex Docs

Installation

System Requirements

Section titled “System Requirements”
RequirementMinimum
Node.js24+ (uses node:sqlite)
npm9+
OSmacOS, Linux, Windows (WSL recommended)
Disk~50 MB for Omnodex + space for event logs

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

This builds all packages in the monorepo. The CLI is then available at packages/cli/dist/index.js or via npx omnodex.

Configure OMNODEX_HOME

Section titled “Configure OMNODEX_HOME”

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

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

Section titled “Install the Hook”
Terminal window
npx 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:

Terminal window
npx omnodex status

Multi-Root Dashboard

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

Section titled “Uninstall”

To remove the hook without deleting your data:

Terminal window
npx omnodex uninstall

To remove everything including event logs:

Terminal window
npx omnodex uninstall --purge

Next Steps

Section titled “Next Steps”