Set up OmniKey and master the agent workflow.

Install the CLI

Use Homebrew on macOS, or npm anywhere Node.js is available.

brew install GurinderRawala/omnikey/omnikey-cli

# or
npm install -g omnikey-cli

Configure your first provider

The onboarding flow writes your local OmniKey config and validates the provider details before the daemon starts.

omnikey onboard

Start the backend daemon

Keep the daemon running while the desktop app, Telegram bridge, and agent sessions are active.

omnikey daemon

Install the desktop app

Download the native app and sign in to the same local daemon from your machine.

Add or select a task instruction

Task instructions define the specialist behavior: how omniAgent should inspect context, which tools it can use, what quality bar to follow, how to validate the work, and what to include in the final answer. Save reusable instructions for common roles, then select the right one before starting a chat.

Give omniAgent the target and goal

Type the outcome you want in natural language. For project work, include the local path, such as /Users/you/projects/app, plus the exact task: fix a bug, review changes, add a feature, investigate logs, write docs, or run a release check. omniAgent uses the path as the working context and begins from there.

Let connected tools do the work

While the task runs, omniAgent can use every enabled tool it is connected to, including MCP servers, terminal commands, filesystem access, web fetch, and an authenticated browser profile for pages that require login. Tool availability depends on your local setup, enabled MCP servers, and browser access settings.

Enable usage recording

Open Settings → Agent Access in the desktop app and turn on Usage recording. When enabled, OmniKey stores the model, mode, thread/session, and token counts for each AI call. Self-hosted installs keep detailed recording off by default, so enable it if you want the Usage page to populate from that point forward.

Open the Usage page

In the desktop Settings window, choose Usage. The page reads recorded metrics from /api/usage and lets you filter by time range and provider. It reports token counts only, using values recorded from actual AI calls instead of estimated provider pricing.

Review consumption by model and session

The Usage page shows total tokens, input tokens, output tokens, request count, average daily tokens, daily token split, tokens by provider/model, and recent sessions with recorded token totals. Use it to spot heavy workflows, compare models, and understand how much context each agent session consumes.

Windows remote debugging port

Modern Chrome-based browsers require --remote-debugging-port to use a dedicated --user-data-dir, not your everyday browser profile. Create a profile folder, close every browser window, and launch the browser from PowerShell.

mkdir "$env:USERPROFILE\.omnikey\browser-debug-profiles\chrome-default"

& "C:\Program Files\Google\Chrome\Application\chrome.exe" `
  '--remote-debugging-port=9222' `
  "--user-data-dir=$env:USERPROFILE\.omnikey\browser-debug-profiles\chrome-default" `
  '--no-first-run' '--no-default-browser-check'

Sign in inside the fresh window. To start it on login, add the same command as a Registry Run value under HKCU\Software\Microsoft\Windows\CurrentVersion\Run.

macOS remote debugging port

For Chrome-based browsers on macOS, create a dedicated profile folder, quit the browser fully with ⌘Q, and launch it from Terminal with a debug port.

mkdir -p ~/.omnikey/browser-debug-profiles/chrome-default

"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" \
  --remote-debugging-port=9222 \
  --user-data-dir="$HOME/.omnikey/browser-debug-profiles/chrome-default" \
  --no-first-run --no-default-browser-check

Replace the app path for Brave, Edge, Arc, Vivaldi, Opera, or Chromium. To auto-start on login, create a launchd agent at ~/Library/LaunchAgents/com.omnikey.browser-debug.plist with RunAtLoad = true pointing to the same command.

macOS Apple Events access

Chrome, Brave, Edge, Arc, Vivaldi, Opera, and Chromium can expose tab content through Apple Events. In the browser menu bar, open View → Developer → Allow JavaScript from Apple Events, make sure it is checked, then restart the browser.

For Safari, go to Safari → Settings → Advanced, enable Show features for web developers, then open Develop → Allow JavaScript from Apple Events and make sure it is checked.

Open Scheduled Jobs in the desktop app

From the OmniKey menu bar on macOS or system tray on Windows, choose Scheduled Jobs. The window shows each job, whether it is enabled, and when it will run next.

Create the job

Click Add Job, enter a clear label, write the prompt OmniAgent should run, choose the model or instruction set if needed, and select either a recurring schedule or a one-time run time.

Manage and test it

Use Enable/Disable to pause work without deleting it, Edit to adjust prompts or timing, and Run Now to verify the job immediately.

Create a Telegram bot

Open @BotFather, run /newbot, and save the token as TELEGRAM_BOT_TOKEN.

Find your chat ID

Send your bot a message, then fetch updates and copy the chat.id. Group and channel IDs are negative.

curl "https://api.telegram.org/bot<TELEGRAM_BOT_TOKEN>/getUpdates"

Start the Telegram daemon

The CLI prompts for missing credentials, validates the token, and installs the local service.

omnikey telegram start

# or start the backend and Telegram bridge together
omnikey daemon --telegram