Skip to content

Getting Started

Jump to bottom
Meyverick edited this page Jun 21, 2026 · 2 revisions

Getting Started

Platform note: omnicode is written in Node.js and designed to work cross-platform, but it has only been developed and tested on Ubuntu Linux. Running on Windows, macOS, or other Linux distributions may uncover untested edge cases. Please report any issues you encounter.

Requirements

  • Linux, macOS, or Windows
  • Node.js 22 or later (developed and tested on Node 26; OmniRoute requires Node >=22 <=24)
  • npm
  • OpenCode
  • OmniRoute
  • (Optional) GrayMatter
  • (Optional) OpenSpec

Install dependencies

omnicode requires opencode and omniroute to be on your PATH. Install them before installing omnicode:

npm install -g opencode
npm install -g omniroute

If you use GrayMatter or OpenSpec, install those too:

# GrayMatter
sudo install -m 755 graymatter /usr/local/bin/graymatter

# OpenSpec
npm install -g @fission-ai/openspec

Install omnicode

sudo npm install -g @meyverick/omnicode

No postinstall scripts run and no additional tools are installed.

Run

omnicode

This will:

  1. Verify that opencode and omniroute are available, or exit with an error.
  2. Run GrayMatter initialization quietly if installed (output captured to ~/.local/share/omnicode/graymatter-init.log).
  3. Run OpenSpec initialization quietly if installed (output captured to ~/.local/share/omnicode/openspec-init.log).
  4. Start omniroute --no-open in the background, or reuse an already running instance.
  5. Look up the latest session for the current directory in the OpenCode database.
  6. Launch opencode -s <session_id> if a session exists, or plain opencode to create a new session.

When OpenCode exits and no other OpenCode process is running, the OmniRoute process that omnicode started is stopped automatically.

Resume a specific session

omnicode -s <session_id>

This launches OpenCode with opencode -s <session_id>. OpenCode will error if that session does not exist.

Force continue last session

omnicode -c

This forces the same latest-session lookup as plain omnicode but makes it explicit. If a session exists for the current directory, it is resumed via opencode -s <session_id>.

Check runtime status

omnicode --status

This prints whether opencode and omniroute processes are currently running.

Print version

omnicode --version

Uninstall

npm uninstall -g @meyverick/omnicode

This removes only the npm-managed omnicode package and command. The following remain installed and must be removed manually if desired:

  • OmniRoute (npm uninstall -g omniroute)
  • OpenCode (npm uninstall -g opencode)
  • OpenSpec (npm uninstall -g @fission-ai/openspec)
  • GrayMatter binary (sudo rm /usr/local/bin/graymatter)
  • Your OpenCode config in ~/.config/opencode/opencode.jsonc
  • Runtime data in ~/.local/share/omnicode/

Update

sudo npm install -g @meyverick/omnicode

Reinstalling only updates the omnicode wrapper.

Clone this wiki locally