Skip to content
OmnodexOmnodexOmnodex Docs

Google Antigravity Setup

Omnodex traces Google Antigravity in the Desktop App, the agy CLI, and the standalone Antigravity IDE.

What gets installed

Section titled “What gets installed”

There are two parts, and omnodex install antigravity (or omnodex install agy) sets up both:

PartWhat it does
HooksRecord completed tool calls and observed execution activity
Omnodex MCP server, through the Omnodex pluginRoutes the MCP servers you choose through the Omnodex proxy, records each call at the MCP protocol layer, and adds the omnodex_status, omnodex_connect, and omnodex_connection_status tools

--hooks or --plugin installs one of them. The command asks whether the hooks record every project or only the current one; see Installation. The plugin goes in ~/.gemini/config/plugins/omnodex-antigravity/, where the app, IDE and agy all load it, and is configured for this host automatically. The manual setups below are alternatives.

Only MCP servers listed in the Omnodex proxy configuration are recorded by the proxy. Servers you leave in Antigravity’s own mcp_config.json keep working, but need functioning hooks for Omnodex to see their calls. Direct MCP registration below does not require a plugin download or project hooks.

Choose where Antigravity runs

Section titled “Choose where Antigravity runs”

Google’s current MCP documentation uses the same global and workspace MCP files across the Desktop App, CLI, and standalone IDE:

FileDesktop App and IDEagy CLI
MCP servers, all projects~/.gemini/config/mcp_config.json~/.gemini/config/mcp_config.json
MCP servers, one project<project>/.agents/mcp_config.json<project>/.agents/mcp_config.json
Hooks, one project<project>/.agents/hooks.json<project>/.agents/hooks.json
Hooks, all projects~/.gemini/config/hooks.json~/.gemini/config/hooks.json

These paths can be shared when the surfaces run under the same user on the same host. Older CLI versions may use different locations; inspect /mcp in the version you run rather than assuming an old ~/.gemini/antigravity-cli/mcp_config.json is still loaded. CLI plugin staging remains separate from the global MCP file.

On Windows, the Desktop App is a native Windows program and uses C:\Users\<you>\.gemini\ and C:\Users\<you>\.omnodex\. The agy CLI inside WSL is a separate host with its own /home/<you>/.gemini/ and /home/<you>/.omnodex/. Set up each host you use, with that host’s path style, and never put C:\... paths in WSL configuration or /mnt/c/... paths in Windows configuration. Windows and WSL covers running both.

Installing Omnodex with npm in WSL does not install it for the native Windows Desktop App or IDE. Install and update it in PowerShell too if you use those surfaces. Each host needs its own proxy configuration and optional hosted dashboard connection.

Before you start

Section titled “Before you start”

On the host where Antigravity runs:

  1. Install Omnodex on this host, version 0.3.0 or later: from npm, or from source including the omnodex-config.json step if you plan to use hooks.
  2. Find the absolute path of Node.js. The Desktop App may not see the same PATH as your terminal, so the MCP server entry below uses an absolute path.
Terminal window
where.exe node
where.exe npx
node --version

  1. Find the full path of the proxy JavaScript file. On Windows, run this file with node.exe; Node.js cannot run npm’s .cmd wrapper.

    Run npm root -g in this host’s shell, then use <global node_modules>/omnodex/bin/omnodex-mcp-proxy.js. On Windows that is usually C:\Users\<you>\AppData\Roaming\npm\node_modules\omnodex\bin\omnodex-mcp-proxy.js; on macOS with Homebrew’s Node.js, /opt/homebrew/lib/node_modules/omnodex/bin/omnodex-mcp-proxy.js.

Register the Omnodex MCP server

Section titled “Register the Omnodex MCP server”

Use ~/.gemini/config/mcp_config.json for the current Desktop App, CLI, and IDE on this host, or <project>/.agents/mcp_config.json to limit Omnodex to one project. Register it in one scope to avoid duplicate connections. The examples use the npm proxy path; for a source install, use your build’s path from Before you start.

  1. Create the proxy configuration.

    The proxy starts the MCP servers you want Omnodex to see and forwards every call to them. Create omnodex-proxy.json in your Omnodex home:

    You can start with no upstreams: { "version": 1, "redact_parameters": false, "upstream_servers": [] }. This exposes the omnodex_* status and connection tools. The examples below add a filesystem upstream.

    C:\Users\<you>\.omnodex\omnodex-proxy.json:

    {
      "version": 1,
      "redact_parameters": false,
      "upstream_servers": [
        {
          "name": "filesystem",
          "transport": "stdio",
          "command": "C:\\Program Files\\nodejs\\npx.cmd",
          "args": ["-y", "@modelcontextprotocol/server-filesystem", "C:\\Users\\<you>\\Documents\\project"]
        }
      ]
    }

    Use the npx.cmd path that where.exe npx printed. Backslashes are doubled in JSON.

    The filesystem server is a good first upstream because its calls are easy to recognize. Replace it with the MCP servers you want Omnodex to see. Upstreams can be local (stdio) or remote (http); see the configuration reference for remote servers. Put secrets in environment variables and reference them as ${VAR} in an upstream’s env, never as literal values. See Configuration.

    Check that the proxy starts before you point Antigravity at it. It waits for input; press Ctrl+C to stop it:

    Terminal window
    omnodex-mcp-proxy --config ~/.omnodex/omnodex-proxy.json

  2. Look at your current mcp_config.json.

    If the file does not exist yet, create it with an empty { "mcpServers": {} }. If you already use MCP servers in Antigravity, it looks something like this, with one entry per server under mcpServers:

    {
      "mcpServers": {
        "issue-tracker": {
          "serverUrl": "https://mcp.example.com/mcp"
        },
        "github": {
          "command": "npx",
          "args": ["-y", "@modelcontextprotocol/server-github"],
          "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "..." }
        }
      }
    }

    Remote servers use serverUrl. Local servers use command and args.

  3. Add omnodex next to the existing entries.

    Add an omnodex key inside mcpServers. Keep every other entry as it is.

    C:\Users\<you>\.gemini\config\mcp_config.json:

    {
      "mcpServers": {
        "issue-tracker": {
          "serverUrl": "https://mcp.example.com/mcp"
        },
        "github": {
          "command": "npx",
          "args": ["-y", "@modelcontextprotocol/server-github"],
          "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "..." }
        },
        "omnodex": {
          "command": "C:\\Program Files\\nodejs\\node.exe",
          "args": [
            "C:\\Users\\<you>\\AppData\\Roaming\\npm\\node_modules\\omnodex\\bin\\omnodex-mcp-proxy.js",
            "--config",
            "C:\\Users\\<you>\\.omnodex\\omnodex-proxy.json",
            "--platform",
            "antigravity"
          ]
        }
      }
    }
    FieldValue
    commandThe absolute Node.js path from Before you start
    args[0]The absolute path to omnodex-mcp-proxy.js from Before you start: in the global npm package, or in your source build
    args[1], args[2]--config and the absolute path to your omnodex-proxy.json
    args[3], args[4]--platform and antigravity, so the dashboards label these sessions Antigravity via MCP Proxy

    Pass --config explicitly so the proxy loads the intended host’s configuration without relying on environment inheritance.

    To have Omnodex record one of the servers you already had, such as github above, move it: add it to upstream_servers in omnodex-proxy.json (with "transport": "stdio" and absolute paths), then delete its entry from mcp_config.json. If a server is in both files, the agent gets two copies of its tools, and only the copy named github__<tool> is recorded by the proxy.

  4. Reload the configuration and verify.

    • Desktop App: open Settings > Customizations > Installed MCP Servers, refresh the connection, and confirm omnodex is enabled.
    • agy: enter /mcp and confirm omnodex is listed without errors.
    • Standalone IDE: open … > MCP Servers > Manage MCP Servers > View raw config in the agent side panel to inspect the loaded configuration.

    If a refresh does not pick up the change, restart the app or CLI and start a new conversation. Follow any permission prompts for the tool calls; connecting a server does not automatically approve every tool it exposes.

    Ask the agent to call omnodex_status. It returns the proxy version and your upstream servers. Then ask it to use a routed tool. Routed tools appear as <server>__<tool>, for example filesystem__list_allowed_directories.

Alternative: omnodex install antigravity --mcp

Section titled “Alternative: omnodex install antigravity --mcp”

This command creates an explicit project MCP entry pointing at an installed plugin’s launcher. --mcp alone installs only the MCP entry. To request hooks as well, use omnodex install antigravity --hooks --mcp, subject to the hook limits below. If the launcher cannot be found, the command warns and skips MCP registration; check the resulting file.

The installer searches ~/.gemini/config/plugins/omnodex-antigravity/ and ~/.gemini/antigravity-cli/plugins/omnodex-antigravity/. It does not discover arbitrary or workspace-local plugin folders. It adds to existing project MCP entries.

Install the plugin

Section titled “Install the plugin”

omnodex install antigravity --plugin does this for you. To install by hand: Google documents directory-based plugin installation:

  1. Download omnodex-antigravity.zip and unpack it into a folder. plugin.json, mcp_config.json, and bin/launch-proxy.js should be directly inside it.

  2. For the Desktop App or standalone IDE, use ~/.gemini/config/plugins/omnodex-antigravity/ globally, or <project>/.agents/plugins/omnodex-antigravity/ for one workspace. For the CLI, run agy plugin install /absolute/path/to/unpacked/omnodex-antigravity and inspect agy plugin list; the documented CLI staging directory is ~/.gemini/antigravity-cli/plugins/omnodex-antigravity/.

  3. Point the plugin at your Omnodex install:

    Nothing to do: the launcher finds the global npm install. If the desktop app cannot find it, add proxy_bin to omnodex-proxy.json with the proxy path from Before you start.

  4. Inspect the plugin in Customizations or /plugin, then verify the MCP connection with omnodex_status in a new conversation.

The published plugin has its own MCP declaration, so do not also add a manual entry or run --mcp alongside an active plugin connection; omnodex install warns when the project already has one.

If your plugin includes bin/configure.js, run node /absolute/path/to/the/final-installed/plugin/bin/configure.js on this host after placing or staging it. This sets absolute Node.js, launcher and working-directory paths. Run it again after replacing or moving the plugin. For older bundles without this helper, use the direct MCP setup.

Install the hooks

Section titled “Install the hooks”

Use Omnodex 0.3.0 or later, or a current source build, for the hook behavior described here. Reinstall hooks after upgrading an older installation to remove its PreToolUse permission handler. See Capture behavior.

  1. Install the hooks.

    In the shell of the host where Antigravity runs:

    Terminal window
    omnodex install antigravity

    Recording every project writes an omnodex entry to ~/.gemini/config/hooks.json; recording only this project writes it to <project>/.agents/hooks.json. It covers three events:

    • PreInvocation: starts capture on first observed activity, once per conversation
    • PostToolUse: records the completed call’s name, arguments and success/error status
    • Stop: records execution completion only when fullyIdle is true

    Google’s hook contract defines these events separately from conversation boundaries. See Capture behavior for how these events are recorded.

    When it finishes, the command offers to connect this host to the hosted dashboard. Press Ctrl+C to skip; the hooks are already installed.

  2. Verify.

    Terminal window
    omnodex status

    Confirm the hooks are loaded in /hooks (CLI), Settings > Customizations > Hooks (Desktop App), or … > Customizations > Hooks (standalone IDE).

    Then start a session in the project and have the agent run a command. A session file for it appears under event-log/sessions/ in your Omnodex home.

Capture behavior

Section titled “Capture behavior”

Execution boundaries: updated hooks start capture once per conversation and do not turn model invocations into session ends. A fully idle Stop records execution completion and elapsed time since capture began. It is an observed idle boundary, not proof that the conversation was deleted or cannot resume. Capture installed mid-conversation starts at the first event it observes.

Tool approvals and timing: installations omit PreToolUse, leaving native approvals and other permission hooks in charge. Completed calls are captured after execution, so hook-only duration and response size are unknown (recorded as zero). Use the MCP proxy for measured timing and response size on routed calls.

Guardrails: in guardrails mode, omnodex enforce guardrails adds a PreToolUse hook so Omnodex can stop a call before it runs, and leaving guardrails removes it. That hook answers deny, force_ask (Antigravity’s own prompt, with Omnodex’s reason) or allow. allow lets the call proceed under your permission rules; it never approves anything. A stale PreToolUse handler from an older installation gets the same answers.

Trust and approval

Section titled “Trust and approval”

Use the hooks and MCP panels to inspect what is loaded and enabled. Tool approvals follow Antigravity’s permissions policy, including Ask, Allow, and Deny rules; they are not just a one-time server approval. Google currently documents different desktop permission systems on Windows and macOS/Linux. Use the permissions panel to review the rules for your tools.

What gets traced

Section titled “What gets traced”
ActivityRecorded byNotes
Model invocation and stop signalsHooksFirst observed activity and fully idle execution completion, rather than each model call
The model the session usesHooksRecorded at the first activity, and as session.model_changed when it changes. See Which model a session used
Built-in tool calls (shell, file reads and edits)HooksCompleted calls produce tool.invoked and tool.completed with arguments and status; hook-only timing is unknown
MCP tool calls routed through OmnodexOmnodex MCP server and hooksThe proxy records parameters (unless redacted), timing, status, and response size
MCP servers left in mcp_config.jsonHooks onlyThe proxy does not see them

Hooks and the MCP server record different layers, so a routed call can appear once from each. Use redact_parameters in omnodex-proxy.json to keep parameter values out of the proxy’s records.

Connect to the hosted dashboard

Section titled “Connect to the hosted dashboard”

On each host, run:

Terminal window
omnodex connect

This starts a device code flow: the CLI shows a short code and a URL. Open the URL, sign in or create an account, and enter the code. The API token and stream secret are stored in stream-config.json in that host’s Omnodex home.

If you already have an API token from the dashboard:

Terminal window
omnodex connect --token omx_your_token_here

With the Omnodex MCP server connected, you can also ask the agent to call omnodex_connect, which runs the same flow without the CLI.

If the stream is revoked in the dashboard, run omnodex connect again and choose the same stream on the sign-in page to keep its history. Removing a stream from your account does not stop the machine; see Streams and Stream Controls.

View results

Section titled “View results”
Terminal window
omnodex dashboard

Antigravity events carry interceptor: "antigravity-hook" (hooks) or interceptor: "mcp-proxy" (MCP server), so you can tell the sources apart.

Updating

Section titled “Updating”

  1. Update your Omnodex runtime on each host where Antigravity runs: PowerShell for native Windows, a WSL terminal for WSL agents.

    Run omnodex update.

    See Updating. Updating WSL does not update the native Windows install.

    Existing MCP entries can keep using the same runtime path after an in-place update. If you move the source clone or change the npm installation location, update those paths and reinstall any project hooks from this host. If your entry predates the --platform antigravity arguments shown in Register the Omnodex MCP server, add them now.

    For an older Antigravity hook installation, run omnodex install antigravity in each project after updating. This removes the old permission handler and per-model-call end handler while preserving other named hooks.

  2. A plugin installed by omnodex install is updated by omnodex update. Skip the rest of this step unless you installed it by hand and its version changed; compare your plugin with the release manifest.

    For a manually unpacked Desktop App/IDE plugin, replace that plugin folder with a fresh extraction of the latest ZIP, keeping the same path. Run node /absolute/path/to/the/installed/plugin/bin/configure.js again if the bundle includes it; otherwise reapply your absolute paths to its MCP declaration.

    For a CLI-installed plugin, updating the download folder alone does not replace the staged copy. Use agy plugin uninstall omnodex-antigravity, then agy plugin install /absolute/path/to/the/newly-unpacked/plugin and inspect agy plugin list. Run bin/configure.js from the final staged plugin folder if it includes the helper. If a project --mcp entry points at that launcher, confirm the installed path still matches it. Keep your proxy configuration and event data.

    Skip this step for a direct MCP entry that points at the runtime rather than a plugin launcher. Google’s marketplace synchronization does not establish automatic updates for this manually downloaded Omnodex bundle.

  3. Reload or restart Antigravity. Refresh the MCP connection or restart the app/CLI, then start a new conversation. Check Settings > Customizations > Installed MCP Servers or /mcp, and ask for omnodex_status and omnodex_connection_status. If hooks are enabled, verify a new command appears in the event log too.

Troubleshooting

Section titled “Troubleshooting”

omnodex is missing or shows an error in MCP settings or /mcp:

  • Run the command and args from the entry yourself, in the host’s shell. The proxy should start and wait for input. If it exits, fix omnodex-proxy.json: the proxy starts even when an upstream is down, but a config file it cannot parse is still an error.
  • Check that the JSON is valid and that omnodex sits inside mcpServers, next to your other servers, not beside mcpServers.
  • Check that every path is absolute, uses the host’s path style, and uses doubled backslashes on Windows.
  • Confirm the loaded configuration: current Google docs use ~/.gemini/config/mcp_config.json for all three surfaces, with .agents/mcp_config.json for the workspace. Older CLI versions may differ.
  • Fully restart Antigravity after changing MCP servers.

omnodex connects but tools are unavailable: inspect the server’s enabled state, disabledTools, permissions, and connection logs. Refresh or restart and test in a new conversation. Manually creating a tool cache folder is not part of the current documented installation flow.

A tool name ends in a short code: Antigravity drops any tool whose full name, with its own mcp_<plugin>_<server>_ prefix, is longer than 64 characters. The proxy shortens longer names to fit, for example filesystem__list_director_fbe497 for list_directory_with_sizes. The call still reaches the right tool, and Omnodex records it under its full name.

Hooks not firing:

  • Run omnodex status in the project and confirm .agents/hooks.json has an omnodex entry.
  • Confirm the hook is loaded and enabled in the surface’s Hooks panel. The Omnodex installer manages project hooks; it does not install global hooks.
  • On Windows, confirm the hooks were installed from the same host (PowerShell or WSL) that runs Antigravity.
  • If omnodex status says a hooks file names paths this machine does not have, the file came from another machine, for example through a shared repo or a synced folder. Run the reinstall command it prints. Until then the hooks fail on every call, and the agent may offer to create the missing folders itself, for example with sudo. Decline that.
  • Check launcher.log in your Omnodex home. For source installs, Could not locate antigravity hook shim means omnodex-config.json is missing or has the wrong antigravity path. For npm installs, omnodex is not on the PATH Antigravity runs hooks with; run omnodex status from the project to see where the launcher looks.

Events not appearing in the dashboard:

  • On Windows with both hosts in use, events are split between C:\Users\<you>\.omnodex and /home/<you>/.omnodex. See Windows and WSL to view both.
  • Run omnodex replay to rebuild the read model.

For hosted delivery, ask for omnodex_connection_status or check omnodex status. Rebuilding the local read model does not establish that cloud credentials are configured or that a hosted upload succeeded.

Next steps

Section titled “Next steps”