Google Antigravity Setup

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

What gets installed

There are two independent parts. You can use either one, and the full setup uses both.

Part	What it does	How you install it
Hooks	Record completed tool calls and observed execution activity	omnodex install antigravity in each project
Omnodex MCP server	Routes 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	An omnodex entry in Antigravity’s mcp_config.json

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

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

File	Desktop App and IDE	agy 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

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.

Windows (PowerShell)

where.exe node
where.exe npx
node --version

macOS / Linux / WSL

which node
which npx
node --version

3. 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.

   Installed from npm

   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.

   Installed from source

   <repo>/packages/mcp-proxy/dist/bin/omnodex-mcp-proxy.js in your clone.

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.

   Windows

   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.

   macOS / Linux / WSL

   ~/.omnodex/omnodex-proxy.json:

   {
     "version": 1,
     "redact_parameters": false,
     "upstream_servers": [
       {
         "name": "filesystem",
         "transport": "stdio",
         "command": "/usr/local/bin/npx",
         "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/<you>/project"]
       }
     ]
   }

   Use the npx path that which npx printed.

   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:

   Installed from npm

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

   Installed from source

   node /path/to/omnodex/packages/mcp-proxy/dist/bin/omnodex-mcp-proxy.js --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.

   Windows

   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"
         ]
       }
     }
   }

   macOS / Linux / WSL

   ~/.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": "/usr/local/bin/node",
         "args": [
           "/usr/local/lib/node_modules/omnodex/bin/omnodex-mcp-proxy.js",
           "--config",
           "/Users/<you>/.omnodex/omnodex-proxy.json",
           "--platform",
           "antigravity"
         ]
       }
     }
   }

   JSON does not expand ~, so write the full home path.

   Field	Value
   command	The 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

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

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:

   Installed from npm

   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.

   Installed from source

   Add proxy_bin to omnodex-proxy.json, pointing at your build’s omnodex-mcp-proxy.js.

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. Install project hooks separately with the Omnodex CLI.

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

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 into the project.

   From the project directory, in the shell of the host where Antigravity runs:

   macOS / Linux / WSL

   omnodex install antigravity

   Windows (PowerShell)

   Run from PowerShell, not WSL, so the hook commands use Windows paths:

   omnodex install antigravity

   If a source install’s CLI is not on PATH, use node "C:\path\to\omnodex\packages\cli\dist\index.js" install antigravity "C:\path\to\your\project".

   This writes an omnodex entry to <project>/.agents/hooks.json for 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.

   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.

Windows: one project, one host

The hook commands in .agents/hooks.json contain the paths of the host that installed them. Hooks installed from WSL cannot run in the Windows Desktop App, and hooks installed from PowerShell cannot run in agy inside WSL. To use both on one project, reinstall from the host you are about to use, or keep a separate copy of the project for each.

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: updated 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. An older hook configuration must be reinstalled; the updated shim returns ask if a stale PreToolUse handler still calls it.

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

Activity	Recorded by	Notes
Model invocation and stop signals	Hooks	First observed activity and fully idle execution completion, rather than each model call
Built-in tool calls (shell, file reads and edits)	Hooks	Completed calls produce tool.invoked and tool.completed with arguments and status; hook-only timing is unknown
MCP tool calls routed through Omnodex	Omnodex MCP server and hooks	The proxy records parameters (unless redacted), timing, status, and response size
MCP servers left in mcp_config.json	Hooks only	The 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

On each host, run:

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 sync passphrase are stored in stream-config.json in that host’s Omnodex home.

If you already have an API token from the dashboard:

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 a stream is disconnected or revoked in the dashboard, run omnodex connect again. Your earlier history stays under the original stream.

View results

omnodex dashboard

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

Updating

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

   Installed from npm

   Run omnodex update.

   Installed from source

   Run omnodex update from your clone.

   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. Update the plugin only if you use it and its version changed. Runtime and plugin releases are independent. 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

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.

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.
• 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

• Plugins - Public downloads and release versions
• MCP Proxy for Any Client - How the proxy works with other clients
• Running Detection - Risk detection works the same across all interceptors
• Events and Traces - The event model