Metadata-Version: 2.4
Name: antigravity-mcp-cli
Version: 0.4.0
Summary: Unified CLI and MCP server for controlling Google Anti-Gravity IDE via CDP
Project-URL: Homepage, https://github.com/jacob-bd/the-antigravity-mcp-cli
Project-URL: Repository, https://github.com/jacob-bd/the-antigravity-mcp-cli
Project-URL: Issues, https://github.com/jacob-bd/the-antigravity-mcp-cli/issues
Author: Jacob Ben-David
License-Expression: MIT
License-File: LICENSE
Keywords: ai,antigravity,cdp,chrome-devtools-protocol,cli,ide,mcp
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.11
Requires-Dist: aiosqlite>=0.20.0
Requires-Dist: fastmcp>=0.1.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: platformdirs>=4.0.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.0.0
Requires-Dist: typer>=0.9.0
Requires-Dist: websockets>=12.0
Provides-Extra: dev
Requires-Dist: mypy>=1.0.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Description-Content-Type: text/markdown

# agm — Anti-Gravity MCP CLI

A unified CLI and MCP server for controlling [Google Anti-Gravity IDE](https://antigravity.google) 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

```bash
# 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

```bash
# 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:

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

### Gemini CLI

Add to your Gemini CLI settings:

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

### Server Modes

```bash
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

```bash
# 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](https://github.com/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](https://github.com/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](https://github.com/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](https://github.com/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](https://github.com/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](https://github.com/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](https://github.com/AvenalJ/AntigravityMobile)** — Model quota monitoring via DOM scraping patterns were studied for the quota dashboard implementation.

## License

MIT — see [LICENSE](LICENSE)

## Author

Jacob Ben-David
