Quick Start Guide
Relevant source files
The following files were used as context for generating this wiki page:
SuperGemini is a meta-programming framework that transforms the Gemini CLI into a structured development platform through behavioral instruction injection. It provides a suite of 18 slash commands, 13 specialized AI agents, and 6 behavioral modes designed to facilitate systematic software development workflows, agent coordination, and session persistence.
Sources: README.md:32-40, Docs/Getting-Started/quick-start.md:30-36, CLAUDE.md:7-13
Core Framework Architecture
The framework operates as a configuration distribution system rather than a traditional execution runtime. It manages the installation of behavioral instructions (in .md and .toml formats) to the user's ~/.gemini/ directory. These files modify the underlying Gemini CLI behavior by injecting specific prompts and rules.
The following diagram illustrates the high-level workflow of the SuperGemini framework:
The workflow begins with user intent analysis and moves through intelligent agent routing, tool coordination via Model Context Protocol (MCP), and session management before passing through quality validation gates.
Sources: Docs/Getting-Started/quick-start.md:43-51, CLAUDE.md:15-20
Installation and Setup
SuperGemini distinguishes between Terminal Commands (used for framework management) and Gemini CLI Commands (used during the development lifecycle). The primary executable is SuperGemini, with aliases for supergemini and sg.
Installation Methods
| Method | Command | Description |
|---|---|---|
| pipx (Recommended) | pipx install SuperGemini && SuperGemini install | Installs in an isolated environment to prevent dependency conflicts. |
| pip | pip install SuperGemini && SuperGemini install | Traditional Python package installation. |
| npm | npm install -g supergemini && SuperGemini install | Cross-platform installation via Node.js. |
| Development | pip install -e . && SuperGemini install | Editable mode for framework contributors. |
Sources: Docs/Getting-Started/quick-start.md:17-23, Docs/Getting-Started/installation.md:11-28, CLAUDE.md:22-30
Post-Installation Components
Upon running SuperGemini install, the framework populates the ~/.gemini/ directory with several critical components:
- Core: Essential behavioral files including
RULES.mdandPRINCIPLES.md. - Commands: 18 TOML-based slash commands located in
~/.gemini/commands/sg/. - Agents: 13 specialized AI personas (e.g.,
system-architect,security-engineer). - MCP: Configuration for 6 Model Context Protocol servers (Context7, Sequential, etc.).
Sources: Docs/Getting-Started/installation.md:131-150, CLAUDE.md:103-112
First-Session Workflow
The framework encourages a progressive learning path, starting with project discovery and moving toward implementation and quality validation.
This sequential flow ensures that context is preserved across development cycles, starting with understanding the codebase before attempting implementation.
Sources: Docs/Getting-Started/quick-start.md:55-70, Docs/Reference/quick-start-practices.md:112-126
Essential Command Reference
| Command | Primary Use Case | Example |
|---|---|---|
/sg:analyze | Codebase understanding or requirements discovery. | /sg:analyze src/ --focus security |
/sg:implement | Automated feature development with best practices. | /sg:implement "JWT authentication" |
/sg:workflow | Generating multi-step implementation plans. | /sg:workflow "add payment gateway" |
/sg:test | Generating test suites and checking coverage. | /sg:test --coverage |
/sg:save | Preserving current progress and context. | /sg:save "auth-module-complete" |
Sources: Docs/Reference/basic-examples.md:32-60, Docs/Reference/quick-start-practices.md:477-495
Advanced Configuration and Flags
SuperGemini supports specialized flags to modify command behavior, resource usage, and reasoning depth.
Context and Reasoning Flags
--introspect: Forces the AI to expose structured reasoning and transparent analysis markers.--focus [domain]: Directs the analysis toward specific expertise areas likesecurity,performance, orarchitecture.--uc(Ultra-Compressed): Minimizes token usage for large operations or high-pressure contexts.
MCP Server Integration
The framework coordinates various tools via MCP to enhance capabilities:
- Context7 (
--c7): Official library documentation and framework patterns. - Sequential (
--seq): Advanced multi-step reasoning and system design. - Magic (
--magic): UI/UX and frontend component generation. - Serena (
--serena): Symbol operations and large codebase memory.
Sources: Docs/Reference/quick-start-practices.md:500-515, Docs/Reference/basic-examples.md:255-285
Best Practices for Daily Development
To maximize productivity, users should adopt the "Load-Work-Save" cycle.
Daily routines should begin with /sg:load to restore context and end with /sg:save to preserve progress for the next session.
Sources: Docs/Reference/quick-start-practices.md:128-140, Docs/Reference/quick-start-practices.md:275-290
Conclusion
The SuperGemini Quick Start Guide establishes a foundation for systematic development. By combining isolated installation, specialized domain agents, and persistent session management, the framework shifts AI interactions from ad-hoc prompts to structured, production-ready workflows. Beginners are encouraged to start with basic analysis commands before exploring advanced multi-agent coordination and MCP integrations.
Sources: Docs/Getting-Started/quick-start.md:112-120, Docs/Reference/quick-start-practices.md:460-470