antigravity-mcp-cli 0.4.0

Unified CLI and MCP server for controlling Google Anti-Gravity IDE via CDP

agm — Anti-Gravity MCP CLI

A unified CLI and MCP server for controlling Google Anti-Gravity IDE programmatically via Chrome DevTools Protocol (CDP). Built for AI coding agents (Claude Code, Gemini CLI, Cursor) and terminal power users.

What It Does

agm lets you remotely control Anti-Gravity from the terminal or any MCP-compatible AI tool:

• Send prompts to Anti-Gravity's AI agent and get responses back
• Delegate tasks with full orchestration (connect, configure model/mode, send, monitor, return)
• Switch models dynamically (Gemini, Claude, GPT — whatever AG offers)
• Handle approvals — approve, deny, or auto-accept file edits and terminal commands
• Monitor quota — per-model usage bars, refresh timers, and low-quota warnings
• Switch modes between Fast and Planning
• Interact with implementation plans — detect, open, read, review, and proceed on plan chips
• Take screenshots of the Anti-Gravity window
• Health checks — verify CDP connectivity, DOM selectors, and chat input reachability

All exposed as both CLI commands and MCP tools.

Installation

# With uv (recommended)
uv tool install antigravity-mcp-cli

# With pip
pip install antigravity-mcp-cli

# From source
git clone https://github.com/jacob-bd/antigravity-mcp-cli.git
cd antigravity-mcp-cli
uv venv && uv pip install -e ".[dev]"

Quick Start

# 1. Launch Anti-Gravity with CDP enabled and connect
agm connect

# 2. Verify everything is working
agm doctor

# 3. Send a prompt
agm send "explain the authentication flow in this codebase"

# 4. Full task delegation (connects, sends, monitors, returns)
agm delegate "fix the login bug in auth.py" --project ~/myapp

CLI Reference

agm — Anti-Gravity MCP CLI

Connection:
  agm connect [-p PATH] [--port N]    Connect to workspace (auto-launches AG with CDP)
  agm disconnect                      Disconnect from CDP
  agm status                          Show connection status
  agm doctor                          Health check (8 checks: Python, config, process, CDP, targets, WebSocket, DOM)

Prompts:
  agm send PROMPT [--timeout N]       Send prompt, display response
  agm delegate TASK [-p PATH]         Full delegation (connect + model + mode + send + monitor)
                [--model NAME]        Model override (fuzzy match: "claude", "gemini 3.1")
                [--mode fast|planning] Mode override
                [--auto-approve]       Auto-approve actions (blacklist enforced)
                [--timeout N]          Timeout in seconds

Models:
  agm model                           Show current model
  agm model list                      List all available models + quota warnings
  agm model set NAME                  Switch model (fuzzy match supported)
  agm model quota                     Per-model quota dashboard (usage bars, status, refresh timers)

Mode:
  agm mode                            Show current mode (fast / planning)
  agm mode [fast|planning]            Switch execution mode

Approvals:
  agm approve                         Approve pending action
  agm deny                            Deny pending action
  agm auto-accept [true|false]        Toggle auto-accept (safety blacklist always enforced)

Plans (planning mode):
  agm plan list                       Check if an implementation plan chip is showing
  agm plan open                       Click Open to expand the plan in the editor
  agm plan view                       Extract and display the full plan markdown
  agm plan proceed                    Click Proceed to accept and execute the plan
  agm plan review "COMMENT"           Submit review feedback — model revises the plan

Other:
  agm screenshot [-o FILE]            Capture AG screen as PNG
  agm serve [--slim|--monitor]        Start MCP server
  agm --version                       Show version
  agm --json COMMAND                  JSON output for scripting

MCP Server Integration

Claude Code

Add to your Claude Code MCP settings:

{
  "mcpServers": {
    "agm": {
      "command": "agm-mcp"
    }
  }
}

Gemini CLI

Add to your Gemini CLI settings:

{
  "mcpServers": {
    "agm": {
      "command": "agm-mcp"
    }
  }
}

Server Modes

agm serve                # Full mode — 22 tools
agm serve --slim         # Slim mode — 4 tools (connect, delegate, status, auto-accept)
agm serve --monitor      # Monitor mode — 13 tools (read + approve + plan, no injection)
agm serve --transport sse --port 8765  # HTTP SSE transport

MCP Tools (22 total)

Tool	Description
agm_connect	Connect to Anti-Gravity workspace via CDP
agm_disconnect	Disconnect from CDP
agm_status	Connection status, model, mode, pending approvals
agm_send_prompt	Send prompt, optionally wait for response
agm_delegate_task	Full delegation: connect + configure + send + monitor + return
agm_stop	Interrupt active generation
agm_screenshot	Capture screen as PNG
agm_list_approvals	Check for pending approval requests
agm_approve	Click Allow
agm_deny	Click Deny
agm_always_allow	Allow This Conversation
agm_auto_accept	Toggle auto-accept (safety blacklist enforced)
agm_list_models	List available models (dynamic discovery)
agm_switch_model	Switch model (fuzzy match)
agm_get_mode	Get current mode
agm_set_mode	Switch between fast/planning
agm_server_info	Server version and capabilities
agm_list_plans	Check if an implementation plan chip is showing
agm_open_plan	Click Open to expand the plan in the editor
agm_get_plan_content	Extract the full plan markdown text
agm_proceed_plan	Click Proceed to accept and execute the plan
agm_review_plan	Submit review feedback — model revises the plan

Architecture

4-layer async-first design:

┌──────────────────────────────────────────────┐
│  CLI Layer (agm)          — Typer + Rich     │
│  Terminal commands, Rich formatting          │
├──────────────────────────────────────────────┤
│  MCP Layer (agm-mcp)     — FastMCP           │
│  22 tools for AI agent integration           │
├──────────────────────────────────────────────┤
│  Services Layer           — Business logic   │
│  Connection, Prompt, Delegation, Approval    │
├──────────────────────────────────────────────┤
│  Core Layer               — CDP engine       │
│  WebSocket, DOM selectors, monitors          │
└──────────────────────────────────────────────┘
         │
         ▼
   Anti-Gravity IDE (Electron/Chromium via CDP)

Key principle: CLI and MCP tools are thin wrappers that call Services, which call Core. Core has zero knowledge of presentation layers.

CDP Port Strategy

Anti-Gravity uses a dedicated port range (9500-9510) to avoid conflicts with other tools that use CDP for authentication (e.g., notebooklm-mcp-cli, gemini-web-mcp-cli use ports 9222-9231 for Chrome auth).

When agm connect launches Anti-Gravity, it automatically selects a free port from 9500-9510. When scanning for an already-running AG instance, it checks both the dedicated range and legacy ports (9222-9225, 9333).

Safety

• Auto-accept blacklist: Even with auto-accept enabled, dangerous commands are always blocked: rm -rf, git push --force, npm publish, git reset --hard, git clean -f, DROP TABLE, etc.
• Auto-accept resets on restart: Auto-accept mode is never persisted — it must be explicitly enabled each session.
• CDP binds to localhost only: The CDP port (9500) is only accessible from 127.0.0.1.

Development

# Install dev dependencies
uv venv && uv pip install -e ".[dev]"

# Run tests
uv run pytest tests/ -v

# Lint
uv run ruff check src/ tests/

# Type check
uv run mypy src/

# Reinstall after changes
uv cache clean && uv tool install --force .

Disclaimer

This project is an independent, community-built tool created for educational and personal productivity purposes. It is not affiliated with, endorsed by, or associated with Google LLC or any of its products or services. "Anti-Gravity" and "Google" are trademarks of Google LLC.

This tool interacts with Anti-Gravity IDE solely through the publicly available Chrome DevTools Protocol (CDP), which is a standard debugging interface built into all Chromium-based applications. No proprietary APIs are reverse-engineered, no authentication is bypassed, and no terms of service are violated.

Use at your own discretion. The author assumes no responsibility for how this tool is used.

Acknowledgments & References

This project was built by studying and drawing inspiration from several open-source projects. Credit and thanks to their authors:

CDP Engine & DOM Interaction

• optimistengineer/remoat — Primary CDP reference. The response monitoring system (COMBINED_POLL pattern, stop-button-gone completion detection, scored selector fallback chains, activity log filtering, quota error detection) was ported from remoat's responseMonitor.ts. The message injection sequence (focus → clear → insertText → enter), approval detection script, and cross-platform keyboard modifier handling also draw from remoat's implementation. A well-engineered project that proved CDP-based AG control is production-viable.

• tokyoweb3/LazyGravity — Multi-workspace connection pool architecture, callWithRetry reconnection pattern, and workspace discovery probing (title match → CDP probe → folder path → URL param match) were informed by LazyGravity's approach. Shares a common ancestor with remoat.

Approval & Auto-Accept

• yazanbaker94/AntiGravity-AutoAccept — The MutationObserver approach to approval detection (instant reaction vs polling), session heartbeat for observer health validation, and the configurable command blacklist concept for safe auto-accept were all informed by this project.

MCP Architecture

• jbendavi/notebooklm-mcp-cli — The architectural template for this project. The 4-layer design (Core → Services → MCP → CLI), FastMCP server setup with tool registry pattern, Typer CLI with Rich formatting, Pydantic data types, pyproject.toml with Hatchling, uv package management, and the doctor health check command pattern were all mirrored from notebooklm-mcp-cli.

• ChromeDevTools/chrome-devtools-mcp — Google's official CDP-over-MCP server informed the MCP tool design patterns: tool categorization, parameter validation, unified error/response format, and the "slim mode" concept for exposing a minimal tool subset.

Other References

• su-kaka/gcli2api — Credential rotation and model mapping patterns studied for potential future API gateway features. Note: anti-commercial license — no code was copied.

• AvenalJ/AntigravityMobile — Model quota monitoring via DOM scraping patterns were studied for the quota dashboard implementation.

License

MIT — see LICENSE

Author

Jacob Ben-David