Installation Guide
Relevant source files
The following files were used as context for generating this wiki page:
SuperGemini is a meta-programming framework that enhances the Gemini CLI through behavioral instruction injection. The installation process is designed to be interactive and modular, allowing users to deploy specific behavioral components—such as specialized AI agents, slash commands, and Model Context Protocol (MCP) server configurations—directly into their local environment. Sources: CLAUDE.md:8-12, Docs/Getting-Started/installation.md:5-8
The framework operates by installing behavioral instruction files (.md, .toml) into the ~/.gemini/ directory, which the Gemini CLI then reads to modify its core behavior. The Python package itself serves as the installation engine and management layer rather than the runtime execution environment. Sources: CLAUDE.md:14-18, Docs/Getting-Started/installation.md:144-156
Architecture and Components
SuperGemini utilizes a component-based installation system. The installer manages six primary component types that build the framework's functional layers. Sources: CLAUDE.md:73-83
Component Types
| Component | Description |
|---|---|
| Core | Essential framework files including PRINCIPLES.md, RULES.md, and FLAGS.md. |
| Commands | 18 slash commands (e.g., /sg:analyze) converted from Markdown to TOML for Gemini CLI consumption. |
| Modes | Behavioral modes such as brainstorming and introspection. |
| Agents | 13 specialized AI personas (e.g., security-engineer, system-architect). |
| MCP | Configuration for 6 external servers (Context7, Sequential, Magic, Playwright, MorphLLM, Serena). |
| MCP Docs | Documentation files for individual MCP server usage. |
Sources: CLAUDE.md:73-83, Docs/Getting-Started/installation.md:158-164
Directory Structure
The project maintains a dual directory structure to separate the installer logic from the framework payload.
SuperGemini/(Package Source): Contains the "payload" files (Commands, Agents, Core instructions) that are copied to the user's home directory.setup/(Installation Engine): Contains the Python logic that validates prerequisites and handles the file system operations during installation.
Sources: CLAUDE.md:85-101
Installation Workflow
The installation logic follows a sequence of system validation, user selection, and file deployment. The following diagram illustrates the standard interactive installation flow:
The installer ensures environment safety by creating backups before any file operations. Sources: Docs/Getting-Started/installation.md:120-134
Prerequisites
Users must meet specific technical requirements before initiating the installation.
- Required: Python 3.8+, Gemini CLI, and 50MB free disk space.
- Recommended: Node.js 16+ (required for specific MCP servers like Context7 and Magic), Git, and 1GB RAM.
Sources: Docs/Getting-Started/installation.md:43-52
Deployment Methods
SuperGemini supports multiple deployment paths depending on the user environment (Python-centric, Node-centric, or Developer). Sources: Docs/Getting-Started/installation.md:15-32
Terminal Commands vs. Slash Commands
A critical distinction must be made between Terminal Commands (used for installation/management) and Slash Commands (used inside Gemini CLI after installation). Sources: CLAUDE.md:104-122, Docs/Getting-Started/installation.md:34-40
Terminal commands like SuperGemini install run the Python installer logic, while slash commands like /sg:analyze utilize the deployed TOML prompts. Sources: CLAUDE.md:104-122
Standard Installation Commands
| Method | Command |
|---|---|
| pipx (Recommended) | pipx install SuperGemini && SuperGemini install |
| Standard pip | pip install SuperGemini && SuperGemini install |
| NPM Wrapper | npm install -g supergemini && SuperGemini install |
| Development | pip install -e ".[dev]" && SuperGemini install |
Sources: Docs/Getting-Started/quick-start.md:14-22, Docs/Getting-Started/installation.md:82-96
Advanced Configuration and Management
The framework provides specific flags for tailored deployments and lifecycle management. Sources: Docs/Getting-Started/installation.md:105-118
Installation Profiles
- Express:
SuperGemini install --yes(Auto-confirm interactive setup). - Minimal:
SuperGemini install --profile minimal --yes(Core features only). - Full:
SuperGemini install --profile full --yes(All features including MCP).
Sources: Docs/Getting-Started/installation.md:105-113
Uninstallation
SuperGemini implements a two-step uninstallation process to prevent the accidental loss of user customizations.
- Component Removal:
SuperGemini uninstallremoves framework files from~/.gemini/but preserves personal configurations and backups. - Package Removal:
pip uninstall SuperGeminiornpm uninstall -g supergeminiremoves the command-line tool.
Sources: Docs/Getting-Started/installation.md:195-212
Summary
The installation of SuperGemini transforms a standard Gemini CLI environment into a structured meta-programming framework through modular component deployment. By separating the installation engine (Python/setup) from the behavioral payload (Markdown/TOML), the system maintains a lightweight footprint that is easily manageable via terminal commands while providing deep functional enhancements through the /sg: slash command namespace. Sources: CLAUDE.md:14-18, Docs/Getting-Started/quick-start.md:32-38