How to Set Up and Use the antigravity-cli Provider in ModLens

The antigravity-cli provider is the default, key‑less vision backend for ModLens that wraps the local agy binary to process images through Google's Gemini model in 15–45 seconds without requiring an API key.

The antigravity-cli provider (also aliased as agy or antigravity) serves as the zero-configuration default in the liustack/modlens repository. It enables free image analysis by spawning a local subprocess rather than calling paid APIs directly, making it the go-to option for users who want to avoid managing cryptographic keys while still receiving structured JSON output conforming to the ModLens schema.

Architecture and Implementation

The provider is implemented across four distinct layers in the codebase.

Provider Registration occurs in src/providers/index.ts, which registers the antigravityCliProvider object under the names antigravity-cli, agy, and antigravity. This registration exposes a unified VisionProvider interface that the analyzer consumes.

Subprocess Orchestration lives in src/providers/antigravity.ts. This file defines the buildAntigravityInvocation function to construct the command line and parseAntigravityOutput to parse stdout. These are exposed via the buildInvocation and parseOutput fields of the provider object.

Analyzer Integration happens in src/analyzer.ts, which selects antigravity-cli automatically when no other provider is explicitly configured via the -p flag or environment variables.

Result Validation is handled by src/util/json.ts and src/schema.ts, which validate the JSON returned by the CLI against the ModLens schema and record timing metadata.

Installation and Setup

Install the Antigravity CLI

The provider requires the agy binary to be present on your system PATH. Install it via the official installer:

curl -fsSL https://antigravity.google/cli/install.sh | bash

The provider’s availability check in src/providers/availability.ts simply verifies that agy can be found in PATH by attempting to spawn the process.

Authenticate Once

Run the CLI interactively to complete the OAuth flow:

agy

This opens a browser window for Google authentication. After approval, credentials are stored in ~/.gemini/antigravity-cli/. ModLens reuses this session automatically; subsequent runs do not require re-authentication unless the key-ring is locked or the weekly quota resets.

No API Key Required

Because the Antigravity CLI handles authentication independently, ModLens does not need environment variables such as ANTIGRAVITY_API_KEY or GEMINI_API_KEY. This eliminates key management entirely for users who stick with this provider.

Performance and Speed Characteristics

Latency Benchmarks

The antigravity-cli provider exhibits typical latency of 15–45 seconds per image, depending on image complexity and current Gemini quota availability. This is significantly slower than the inline API providers (gemini-api, openai, anthropic), which return results in 5–10 seconds, because the subprocess incurs startup overhead and the free tier has lower priority queueing.

Failover Behavior

Newer ModLens releases (v3.2+ and v3.17+) place inline API providers ahead of antigravity-cli in the automatic failover chain. If you have configured a paid API key, ModLens selects the 5–10 second path first and only falls back to antigravity-cli if the primary provider fails or is unavailable.

Usage Examples

Default Provider Selection

When no provider is specified, ModLens defaults to antigravity-cli as implemented in src/analyzer.ts:

modlens -i screenshot.png

No -p flag is required. The tool automatically detects that agy is available and routes the image through it.

Explicit Provider Selection

To force the use of the CLI even when other providers are configured:

modlens -i screenshot.png -p antigravity-cli

This bypasses the failover chain and guarantees the subprocess-based execution.

Custom Model Configuration

You can adjust the Gemini model used by the CLI through the ModLens configuration system:

modlens config set providers.antigravity-cli.model gemini-3.1-pro-high
modlens -i complex-diagram.png

The buildAntigravityInvocation function in src/providers/antigravity.ts injects this model parameter into the subprocess arguments.

Inspecting Timing Metadata

To verify the exact latency for a specific run:

modlens -i screenshot.png --json | jq '.meta.attempts'

Expected output showing the 15–45 second window:

[
  {
    "provider": "antigravity-cli",
    "ok": true,
    "durationSeconds": 27.3
  }
]

The durationSeconds field reflects the total time spent in buildInvocation through parseOutput.

Troubleshooting Common Issues

Symptom	Root Cause	Resolution
agy not on PATH error from modlens doctor	Binary not installed or not in PATH	Re-run the install script or manually add the install directory to your shell configuration.
"not logged into antigravity"	Missing or expired session	Execute agy manually to re-authenticate; inspect logs at ~/.gemini/antigravity-cli/log for OAuth errors.
Quota exhausted message	Weekly free tier limit reached	Switch to a paid provider via modlens config set provider gemini-api or wait for the quota reset.

Summary

• The antigravity-cli provider offers a free, zero-API-key solution for ModLens users by wrapping the local agy binary.
• Expect 15–45 seconds per image, slower than paid alternatives but cost-free.
• Core logic resides in src/providers/antigravity.ts with registration in src/providers/index.ts.
• Requires one-time installation of the Antigravity CLI and browser-based authentication.
• Automatically selected when no other provider is configured, or explicitly via -p antigravity-cli.

Frequently Asked Questions

How does antigravity-cli differ from the gemini-api provider?

The antigravity-cli provider spawns a local subprocess (agy) that handles its own authentication and quota management, resulting in 15–45 second latency but requiring no API key. The gemini-api provider makes direct HTTPS calls to Google's API using a user-supplied key, delivering results in 5–10 seconds but requiring paid credentials stored in ModLens configuration.

Why is my antigravity-cli provider taking longer than 45 seconds?

Extended latency usually indicates quota exhaustion on the free tier or high image complexity (resolution or token count). Check ~/.gemini/antigravity-cli/log for rate-limit errors. If the quota is depleted, you must wait for the weekly reset or switch to a paid provider like gemini-api.

Where does ModLens verify that the agy binary is installed?

The availability check occurs in src/providers/availability.ts, which attempts to locate the agy executable in the system PATH. If the binary is missing, the provider is marked unavailable and ModLens skips it during provider selection unless explicitly requested with -p antigravity-cli.

Can I use antigravity-cli without installing the agy binary?

No. The provider is strictly a wrapper around the local Antigravity CLI. Unlike API-based providers that only need an environment variable, this provider requires the curl -fsSL https://antigravity.google/cli/install.sh | bash installation step to place the binary on your PATH before ModLens can invoke it.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}