supergravity 1.0.1
Framework for Google Antigravity IDE - Workflows, Rules, and MCP Configurations
License: MIT
Requires Python: >=3.8
Keywords: antigravity, google, ide, ai, gemini, mcp, workflows, development, automation

<div align="center">

# 🚀 SuperGravity

### **The Ultimate Framework for Google Antigravity IDE**

<p align="center">
  <strong>Transform your AI-powered development experience with structured workflows, intelligent skills, and seamless MCP integrations.</strong>
</p>

<p align="center">
  <a href="https://pypi.org/project/supergravity/"><img src="https://img.shields.io/pypi/v/supergravity?style=for-the-badge&logo=pypi&logoColor=white&color=3775A9" alt="PyPI"></a>
  <a href="https://pypi.org/project/supergravity/"><img src="https://img.shields.io/pypi/dm/supergravity?style=for-the-badge&logo=pypi&logoColor=white&color=3775A9" alt="Downloads"></a>
  <a href="https://github.com/mithun50/SuperGravity/actions/workflows/test.yml"><img src="https://img.shields.io/github/actions/workflow/status/mithun50/SuperGravity/test.yml?style=for-the-badge&logo=github-actions&logoColor=white&label=Tests" alt="Tests"></a>
  <a href="https://github.com/mithun50/SuperGravity/blob/main/LICENSE"><img src="https://img.shields.io/github/license/mithun50/SuperGravity?style=for-the-badge&color=yellow" alt="License"></a>
</p>

<p align="center">
  <a href="https://www.python.org/"><img src="https://img.shields.io/pypi/pyversions/supergravity?style=for-the-badge&logo=python&logoColor=white" alt="Python"></a>
  <a href="https://github.com/mithun50/SuperGravity"><img src="https://img.shields.io/badge/Antigravity-Compatible-00A67E?style=for-the-badge&logo=google&logoColor=white" alt="Antigravity"></a>
  <a href="https://github.com/mithun50/SuperGravity"><img src="https://img.shields.io/badge/MCP-Enabled-8B5CF6?style=for-the-badge&logo=anthropic&logoColor=white" alt="MCP"></a>
  <a href="https://github.com/mithun50/SuperGravity"><img src="https://img.shields.io/badge/AI_Skills-12-FF6B6B?style=for-the-badge&logo=robot&logoColor=white" alt="Skills"></a>
</p>

<p align="center">
  <a href="https://github.com/mithun50/SuperGravity/stargazers"><img src="https://img.shields.io/github/stars/mithun50/SuperGravity?style=for-the-badge&logo=github&color=gold" alt="Stars"></a>
  <a href="https://github.com/mithun50/SuperGravity/network/members"><img src="https://img.shields.io/github/forks/mithun50/SuperGravity?style=for-the-badge&logo=github&color=silver" alt="Forks"></a>
  <a href="https://github.com/mithun50/SuperGravity/issues"><img src="https://img.shields.io/github/issues/mithun50/SuperGravity?style=for-the-badge&logo=github&color=red" alt="Issues"></a>
  <a href="https://github.com/mithun50/SuperGravity/pulls"><img src="https://img.shields.io/github/issues-pr/mithun50/SuperGravity?style=for-the-badge&logo=github&color=blue" alt="PRs"></a>
</p>

<p align="center">
  <a href="#-quick-start">Quick Start</a> •
  <a href="#-features">Features</a> •
  <a href="#-workflows">Workflows</a> •
  <a href="#-skills">Skills</a> •
  <a href="#-mcp-servers">MCP Servers</a> •
  <a href="#-documentation">Docs</a>
</p>

---

<img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="line" width="100%">

</div>

## 🎯 What is SuperGravity?

**SuperGravity** supercharges Google Antigravity IDE by providing a structured, enterprise-ready development framework. It bridges the gap between AI assistance and professional software development practices.

<div align="center">

```
┌─────────────────────────────────────────────────────────────────┐
│                     🚀 SUPERGRAVITY                             │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│   ┌─────────────┐  ┌─────────────┐  ┌─────────────┐            │
│   │  9 Global   │  │  12 AI      │  │  10 MCP     │            │
│   │  Workflows  │  │  Skills     │  │  Servers    │            │
│   └──────┬──────┘  └──────┬──────┘  └──────┬──────┘            │
│          │                │                │                    │
│          └────────────────┼────────────────┘                    │
│                           ▼                                     │
│              ┌────────────────────────┐                         │
│              │  Google Antigravity    │                         │
│              │        IDE             │                         │
│              └────────────────────────┘                         │
│                           │                                     │
│                           ▼                                     │
│              ┌────────────────────────┐                         │
│              │   Your Project         │                         │
│              │   .agent/ workspace    │                         │
│              └────────────────────────┘                         │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
```

</div>

---

## ✨ Features

<table>
<tr>
<td width="50%">

### 🔄 9 Global Workflows
Slash commands for common development tasks:
- `/scaffold` - Generate project structures
- `/implement` - Build features with patterns
- `/security` - OWASP security audits
- `/test` - Comprehensive test generation
- `/deploy` - Safe deployments
- `/review` - Code quality reviews
- `/document` - Auto documentation
- `/refactor` - Safe refactoring
- `/debug` - Systematic debugging

</td>
<td width="50%">

### 🧠 12 AI Skills
Specialized capabilities that activate on-demand:
- `fullstack-architect`
- `backend-engineer`
- `frontend-specialist`
- `api-designer`
- `database-expert`
- `security-engineer`
- `test-engineer`
- `devops-engineer`
- `code-reviewer`
- `refactoring-expert`
- `performance-optimizer`
- `documentation-writer`

</td>
</tr>
<tr>
<td width="50%">

### 🔌 10 MCP Servers
Pre-configured tool integrations:
- **context7** - Framework docs
- **sequential-thinking** - Complex reasoning
- **playwright** - Browser automation
- **magic** - UI generation
- **tavily** - Web search
- **firecrawl** - Web scraping
- **github** - GitHub operations
- **postgres** - Database operations
- **filesystem** - File operations
- **memory** - Persistent memory

</td>
<td width="50%">

### 📁 Workspace Support
Initialize projects with `.agent/` structure:
```
your-project/
└── .agent/
    ├── rules/      # Project rules
    ├── workflows/  # Custom workflows
    └── skills/     # Custom skills
```

**Features:**
- Project-specific configurations
- Custom workflow creation
- Local skill definitions
- Team-shareable settings

</td>
</tr>
</table>

---

## 📦 Installation

### From PyPI (Recommended)

```bash
pip install supergravity
```

### From Source

```bash
git clone https://github.com/mithun50/SuperGravity.git
cd SuperGravity
pip install -e .
```

### Using pipx (Isolated Environment)

```bash
pipx install supergravity
```

---

## 🚀 Quick Start

```bash
# 1. Install SuperGravity to Antigravity IDE
supergravity install

# 2. Initialize your project workspace
cd your-project
supergravity init

# 3. Add MCP servers for enhanced capabilities
supergravity mcp setup

# 4. Check everything is working
supergravity status
```

Then restart Antigravity IDE and start using workflows:

```
/scaffold nextjs e-commerce app with auth
/implement user authentication with JWT
/security scan src/ for vulnerabilities
/test generate tests for UserService
```

---

## 🛠️ CLI Commands

### Core Commands

| Command | Description |
|---------|-------------|
| `supergravity install` | Install SuperGravity to Antigravity IDE |
| `supergravity install --force` | Force reinstall (overwrites files) |
| `supergravity uninstall` | Remove SuperGravity |
| `supergravity update` | Update workflows and rules |
| `supergravity status` | Check installation status |
| `supergravity init` | Initialize `.agent/` workspace |
| `supergravity init --path ./myproject` | Initialize specific directory |

### MCP Commands

| Command | Description |
|---------|-------------|
| `supergravity mcp list` | List all available MCP servers |
| `supergravity mcp list --installed` | List only installed servers |
| `supergravity mcp add <server>` | Install and configure an MCP server |
| `supergravity mcp add <server> -k KEY` | Install with API key |
| `supergravity mcp remove <server>` | Remove an MCP server |
| `supergravity mcp setup` | Interactive MCP setup wizard |
| `supergravity mcp update --all` | Update all installed servers |
| `supergravity mcp verify` | Verify all servers work |
| `supergravity mcp prereq` | Check prerequisites (npm, docker) |
| `supergravity mcp sync` | Sync registry with config |

---

## 🔄 Workflows

Type `/workflow-name` in Antigravity chat:

| Command | Description | Example |
|---------|-------------|---------|
| `/scaffold` | Generate project structures | `/scaffold nextjs blog with auth` |
| `/implement` | Implement features with patterns | `/implement user authentication` |
| `/security` | Security audit (OWASP Top 10) | `/security scan src/` |
| `/test` | Generate comprehensive tests | `/test for UserService` |
| `/deploy` | Deploy applications safely | `/deploy to vercel` |
| `/review` | Code review with quality checks | `/review changes in api/` |
| `/document` | Generate documentation | `/document the API` |
| `/refactor` | Safe refactoring with tests | `/refactor extract method` |
| `/debug` | Systematic debugging | `/debug login failure` |

---

## 🧠 Skills

Skills activate automatically based on your request context:

<details>
<summary><b>🏗️ Architecture & Design</b></summary>

| Skill | Trigger Examples |
|-------|------------------|
| `fullstack-architect` | "Design a scalable e-commerce system" |
| `api-designer` | "Create a REST API for users" |
| `database-expert` | "Design the schema for orders" |

</details>

<details>
<summary><b>💻 Development</b></summary>

| Skill | Trigger Examples |
|-------|------------------|
| `backend-engineer` | "Build the authentication API" |
| `frontend-specialist` | "Create a responsive dashboard" |
| `devops-engineer` | "Set up CI/CD pipeline" |

</details>

<details>
<summary><b>🔒 Quality & Security</b></summary>

| Skill | Trigger Examples |
|-------|------------------|
| `security-engineer` | "Audit for vulnerabilities" |
| `test-engineer` | "Generate unit tests" |
| `code-reviewer` | "Review this pull request" |

</details>

<details>
<summary><b>🔧 Optimization</b></summary>

| Skill | Trigger Examples |
|-------|------------------|
| `refactoring-expert` | "Refactor this module" |
| `performance-optimizer` | "Optimize database queries" |
| `documentation-writer` | "Document this API" |

</details>

---

## 🔌 MCP Servers

### No API Key Required

| Server | Purpose | Install |
|--------|---------|---------|
| `context7` | Framework documentation (React, Next.js, Vue) | `supergravity mcp add context7` |
| `sequential-thinking` | Complex multi-step reasoning | `supergravity mcp add sequential-thinking` |
| `playwright` | Browser automation and E2E testing | `supergravity mcp add playwright` |
| `filesystem` | File system operations | `supergravity mcp add filesystem` |
| `memory` | Persistent memory across sessions | `supergravity mcp add memory` |

### API Key Required

| Server | Key Required | Get Key |
|--------|--------------|---------|
| `magic` | `TWENTYFIRST_API_KEY` | [21st.dev](https://21st.dev) |
| `tavily` | `TAVILY_API_KEY` | [tavily.com](https://tavily.com) |
| `firecrawl` | `FIRECRAWL_API_KEY` | [firecrawl.dev](https://firecrawl.dev) |
| `github` | `GITHUB_PERSONAL_ACCESS_TOKEN` | [GitHub Settings](https://github.com/settings/tokens) |
| `postgres` | `POSTGRES_URL` | Your database |

### Interactive Setup

```bash
supergravity mcp setup
```

Supports multiple selection formats:
- `1 2 3` - Space-separated
- `1,2,3` - Comma-separated
- `1-3` - Ranges
- `1, 3-5, 7` - Mixed

---

## 📁 Configuration

### Global Configuration

```
~/.gemini/
├── GEMINI.md                    # Global rules
└── antigravity/
    ├── mcp_config.json          # MCP server configuration
    ├── mcp_registry.json        # MCP tracking (auto-generated)
    ├── global_workflows/        # Global workflow definitions
    └── skills/                  # AI skill definitions
```

### Workspace Configuration

```
your-project/
└── .agent/
    ├── rules/                   # Project-specific rules
    │   └── workspace.md
    ├── workflows/               # Project-specific workflows
    │   ├── dev.md
    │   ├── build.md
    │   └── pr.md
    └── skills/                  # Project-specific skills
```

---

## 💻 Platform Support

### Windows

```bash
# Option 1: Python module syntax (always works)
python -m supergravity install
python -m supergravity mcp setup

# Option 2: Add Scripts to PATH
# Add %USERPROFILE%\AppData\Local\Programs\Python\PythonXX\Scripts

# Option 3: Use pipx (recommended)
pipx install supergravity
```

### Linux / macOS

```bash
pip install supergravity
supergravity install
```

---

## 🔧 Troubleshooting

<details>
<summary><b>Installation Issues</b></summary>

```bash
# Check installation status
supergravity status

# Force reinstall
supergravity install --force
```

</details>

<details>
<summary><b>MCP Server Issues</b></summary>

```bash
# Check prerequisites
supergravity mcp prereq

# Verify servers
supergravity mcp verify

# Reinstall a server
supergravity mcp remove context7
supergravity mcp add context7
```

</details>

<details>
<summary><b>Missing Prerequisites</b></summary>

- **Node.js**: Required for MCP servers. Install from [nodejs.org](https://nodejs.org) (v18+)
- **Docker**: Required for GitHub MCP. Install from [docker.com](https://docker.com)

</details>

---

## 📚 Documentation

| Guide | Description |
|-------|-------------|
| [Skills Guide](docs/skills.md) | Creating and using AI skills |
| [Workflows Guide](docs/workflows.md) | Workflow syntax and customization |
| [MCP Servers Guide](docs/mcp-servers.md) | MCP setup and configuration |
| [Configuration Reference](docs/configuration.md) | All configuration options |
| [Customization Guide](docs/customization.md) | Custom workflows and rules |

---

## 🤝 Contributing

We welcome contributions! Here's how to get started:

```bash
# Clone the repository
git clone https://github.com/mithun50/SuperGravity.git
cd SuperGravity

# Install in development mode
pip install -e ".[dev]"

# Run tests
pytest tests/ -v

# Format code
black supergravity/
isort supergravity/
```

### CI/CD

- **Tests**: Run automatically on Windows, macOS, and Linux with Python 3.8-3.12
- **Publishing**: Automatic PyPI release on GitHub Release creation

---

## 📊 Project Stats

<div align="center">

| Metric | Value |
|--------|-------|
| **Workflows** | 9 global + unlimited custom |
| **AI Skills** | 12 built-in + custom support |
| **MCP Servers** | 10 pre-configured |
| **Python Support** | 3.8, 3.9, 3.10, 3.11, 3.12 |
| **Platforms** | Windows, macOS, Linux |

</div>

---

## 👨‍💻 Author

<div align="center">

<img src="https://github.com/mithun50.png" width="100" height="100" style="border-radius: 50%;">

### **Mithun Gowda B**

<p>
  <a href="mailto:mithungowda.b7411@gmail.com"><img src="https://img.shields.io/badge/Email-mithungowda.b7411%40gmail.com-D14836?style=for-the-badge&logo=gmail&logoColor=white" alt="Email"></a>
</p>
<p>
  <a href="https://github.com/mithun50"><img src="https://img.shields.io/badge/GitHub-mithun50-181717?style=for-the-badge&logo=github&logoColor=white" alt="GitHub"></a>
</p>

</div>

---

## 📄 License

<div align="center">

MIT License © 2025 [Mithun Gowda B](https://github.com/mithun50)

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

</div>

---

## ⚠️ Disclaimer

<div align="center">

This project is **not affiliated with or endorsed by Google**.

Google Antigravity is a product built by Google.

SuperGravity is an independent, community-driven framework.

</div>

---

<div align="center">

### ⭐ Star this repo if you find it useful!

<p>
  <a href="https://github.com/mithun50/SuperGravity/stargazers"><img src="https://img.shields.io/github/stars/mithun50/SuperGravity?style=social" alt="Stars"></a>
  <a href="https://github.com/mithun50/SuperGravity/network/members"><img src="https://img.shields.io/github/forks/mithun50/SuperGravity?style=social" alt="Forks"></a>
  <a href="https://github.com/mithun50/SuperGravity/watchers"><img src="https://img.shields.io/github/watchers/mithun50/SuperGravity?style=social" alt="Watchers"></a>
</p>

**Made with ❤️ by [Mithun Gowda B](https://github.com/mithun50)**

</div>