MetaGravity
by palladius
README.md
# 🚀 MetaGravity (`metagravity-mcp`)
[](LICENSE)
[](pyproject.toml)
[](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.
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues