Skip to main content
Glama
README.md
# 🚀 MetaGravity (`metagravity-mcp`)

[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
[![Python](https://img.shields.io/badge/python-3.9+-brightgreen.svg)](pyproject.toml)
[![MCP](https://img.shields.io/badge/MCP-standard-orange.svg)](https://modelcontextprotocol.io/)

> **MetaGravity** is a Model Context Protocol (MCP) Server and Python SDK for orchestrating **Google Antigravity** agents and CLI sessions. Inspired by T3 Code's autonomous multi-chat spawning, MetaGravity enables one lead chat or script to spawn, steer, and archive multiple child agent sessions across GitHub issues or feature folders.

---

## 💡 Why MetaGravity?

In harnesses like **T3 Code**, an agent can effortlessly say:
> *"Open 3 parallel chats in this repo, one for each of these 3 GitHub issues, execute them in background, and give them initial prompts."*

Antigravity natively supports reading and continuing threads via `agy`, but lacked an effortless, standardized MCP interface for programmatic multi-chat dispatch. **MetaGravity bridges that gap.**

### Core Primitives
1. **`launch_chat`**: Spawns a dedicated Antigravity session in target project folder `X`, with configurable permissions (`turbo` / `--dangerously-skip-permissions`, `auto`, `plan`), and an initial trigger prompt.
2. **`add_comment`**: Injects follow-up prompts or answers interactive choices (e.g., auto-selecting option `4` when a session is paused waiting for user confirmation).
3. **`archive_chat`**: Formally archives / tombstones completed conversations in Antigravity's metadata (`annotations/<cid>.pbtxt`) so active monitoring stays clean.
4. **`list_chats`**: Discovers active and past threads directly from Antigravity's internal SQLite database (`conversation_summaries.db`).
5. **`get_transcript`**: Reads step-by-step logs and tool outputs from Antigravity's brain transcript.

---

## 🛠️ Quickstart

### 1. Installation

```bash
git clone https://github.com/palladius/metagravity-mcp.git
cd metagravity-mcp
pip install -e .
```

Or run directly with `uv`:
```bash
uv run --project . metagravity mcp
```

### 2. Configure with your MCP Client (Claude Desktop, Cursor, Hermes, T3)

Add to your `claude_desktop_config.json` or MCP settings:

```json
{
  "mcpServers": {
    "metagravity": {
      "command": "python3",
      "args": ["-m", "metagravity.server"],
      "cwd": "/path/to/metagravity-mcp"
    }
  }
}
```

---

## 🧰 Available MCP Tools

| Tool | Parameters | Description |
|---|---|---|
| `metagravity_launch_chat` | `project`, `prompt`, `mode` (`auto`), `turbo` (`true`), `background` (`true`) | Spawns a new Antigravity agent in the project directory. |
| `metagravity_add_comment` | `conversation_id`, `comment`, `choice` (optional int) | Appends a comment or resolves a 1-2-3-4 selection prompt. |
| `metagravity_archive_chat` | `conversation_id` | Tombstones and archives a conversation. |
| `metagravity_list_chats` | `limit` (int, default 20), `open_only` (bool) | Lists active/past threads with status and step count. |
| `metagravity_get_transcript`| `conversation_id`, `limit` (int, default 30) | Inspects recent tool calls and steps from the agent's brain. |

---

## 💻 CLI Usage

MetaGravity also doubles as a standalone command-line manager:

```bash
# List active chats
metagravity list --open

# Launch a new autonomous chat on a GitHub issue
metagravity launch --project ~/git/my-repo --prompt "Fix issue #12: add healthcheck endpoint" --turbo

# Answer option 4 on a waiting chat
metagravity comment 96b7e2e7 --choice 4

# Archive a finished conversation
metagravity archive 96b7e2e7
```

---

## 🐍 Python SDK Example

```python
from metagravity import MetaGravityClient

client = MetaGravityClient()

# Launch 3 parallel agent chats for 3 GitHub issues
issues = [
    (101, "Fix memory leak in cache poller"),
    (102, "Add dark mode toggle to UI"),
    (103, "Update integration test suite"),
]

sessions = []
for issue_id, title in issues:
    res = client.launch_chat(
        project="/Users/riccardo/git/my-project",
        prompt=f"Please solve GitHub Issue #{issue_id}: {title}. Run tests when done.",
        turbo=True,
        background=True,
    )
    print(f"Spawned Issue #{issue_id} -> PID: {res['pid']}")
    sessions.append(res)
```

---

## 📄 License
Apache-2.0 - Built with 💛 by Riccardo Carlesso & Ermete Bottazzi.