High-Level Architecture
Relevant source files
The following files were used as context for generating this wiki page:
SuperGemini is a meta-programming framework designed to enhance the Gemini CLI by transforming it into a structured development platform through behavioral instruction injection. Unlike traditional applications that modify executable code, SuperGemini operates as an orchestration layer, injecting sophisticated behavioral instructions into the AI's environment to enable systematic workflows, expert agent coordination, and tool integration.
The architecture is built upon a "configuration distribution" model where Python-based installation tools manage the delivery of Markdown and TOML-based instructions to the local environment. This enables dynamic system customization, session persistence, and multi-agent collaboration without altering the underlying Gemini CLI binary.
Sources: Docs/Developer-Guide/README.md:38-40, CLAUDE.md:12-20, Docs/Getting-Started/quick-start.md:31-35
System Design Philosophy: Meta-Framework Pattern
SuperGemini follows a meta-framework architecture, acting as an enhancement layer for Gemini Code. The core mechanism is instruction injection, where the framework modifies AI behavior via configuration files (.md, .toml) rather than traditional code modifications.
The diagram above illustrates the separation between the Python-based installer and the instructional payload that actually drives the AI behavior.
Sources: Docs/Developer-Guide/README.md:38-40, CLAUDE.md:12-18
Core Architectural Components
The framework is bifurcated into two primary directories with distinct responsibilities: the "Installer" and the "Payload."
| Component | Directory | Responsibility |
|---|---|---|
| Installation Engine | setup/ | Executable Python code responsible for environment validation, file distribution, and configuration management. |
| Instructional Payload | SuperGemini/ | Source Markdown and TOML files that contain the logic for agents, commands, and behavioral modes. These are copied to the user's home directory. |
Component Types
The system manages six specific component types distributed to the ~/.gemini/ directory:
- Core: Foundational principles and rules (e.g.,
PRINCIPLES.md,RULES.md). - Commands: Slash commands implemented as TOML files in
~/.gemini/commands/sg/. - Modes: Behavioral states like brainstorming or introspection.
- Agents: Domain-specific personas (13 specialists).
- MCP: Model Context Protocol configurations for external tools.
- MCP Docs: Documentation for integrated tools.
Sources: CLAUDE.md:83-108, Docs/Developer-Guide/README.md:46-52
Multi-Agent Orchestration
The architecture features an "Agent Persona Mode" rather than a sub-process model. Instead of spawning separate AI instances, the Gemini CLI embodies specialized roles based on context-aware activation.
The sequence shows how user commands trigger an internal orchestration flow that selects the appropriate agent and tool context.
Specialized Agent Personas
The framework includes 13 specialized agents that are activated based on keyword triggers, file types, or explicit mentions:
- Architects: System, Backend, Frontend, and DevOps.
- Engineers: Security, Performance, and Quality.
- Analysts: Requirements and Root Cause.
- Specialists: Python Expert, Refactoring Expert, and Technical Writer.
Sources: CLAUDE.md:152-175, Docs/Getting-Started/quick-start.md:46-52
Command and Data Flow
The system operates across two distinct namespaces: Terminal Commands (for management) and Slash Commands (for runtime behavior).
1. Installation Flow (Python)
The setup/ engine handles the transformation of Markdown source files into TOML configurations compatible with the Gemini CLI.
- Source: Markdown files with front matter (e.g.,
SuperGemini/Commands/analyze.md). - Conversion:
_convert_md_to_toml()process. - Deployment: Files are copied to
~/.gemini/commands/sg/.
2. Runtime Flow (Instruction Injection)
When a user executes an /sg: command, the Gemini CLI reads the corresponding TOML file from the local configuration directory. This TOML contains a prompt field that injects specific instructions into the LLM's context.
Sources: CLAUDE.md:120-149, CLAUDE.md:177-195
External Integration: Model Context Protocol (MCP)
SuperGemini integrates with 6 core MCP servers to provide enhanced capabilities beyond standard LLM functions. These servers are managed via protocol abstraction and health monitoring.
| Server | Purpose |
|---|---|
| Context7 | Official library and framework documentation patterns. |
| Sequential | Multi-step reasoning and complex problem decomposition. |
| Magic | UI component generation (integrated with 21st.dev). |
| Playwright | Browser automation, E2E testing, and visual validation. |
| MorphLLM | Pattern-based code transformation. |
| Serena | Semantic code understanding and session memory. |
Sources: Docs/Developer-Guide/README.md:46-48, CLAUDE.md:273-281
Conclusion
The SuperGemini architecture represents a shift from imperative code modification to declarative instruction orchestration. By separating the installation engine from the behavioral payload, the framework provides a highly extensible and secure environment that empowers the Gemini CLI with professional software engineering specialized agents and systematic workflows.
Sources: Docs/Developer-Guide/README.md:131-133, CLAUDE.md:12-20