Metadata-Version: 2.4
Name: antigravity-mcp-cli
Version: 0.2.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
- **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)

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 — 17 tools
agm serve --slim         # Slim mode — 4 tools (connect, delegate, status, auto-accept)
agm serve --monitor      # Monitor mode — 8 tools (read + approve, no injection)
agm serve --transport sse --port 8765  # HTTP SSE transport
```

### MCP Tools (17 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 |

## Architecture

4-layer async-first design:

```
┌──────────────────────────────────────────────┐
│  CLI Layer (agm)          — Typer + Rich     │
│  Terminal commands, Rich formatting          │
├──────────────────────────────────────────────┤
│  MCP Layer (agm-mcp)     — FastMCP           │
│  17 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
