Modes Overview
Relevant source files
The following files were used as context for generating this wiki page:
SuperGemini Behavioral Modes constitute an intelligent adaptation system that modifies the Gemini CLI's behavior based on task complexity, context, and resource constraints. These modes operate as a meta-programming layer, injecting specific instructions into the AI's persona to optimize for creative analysis, task coordination, or token efficiency without requiring manual code changes.
The framework supports six distinct modes that typically activate automatically based on specific triggers, such as the number of files involved in a request or the current context usage percentage. These modes ensure that the framework scales its response sophistication from simple one-off tasks to complex, multi-directory engineering operations.
Sources: Docs/User-Guide/modes.md:16-20, CLAUDE.md:12-16, Docs/User-Guide/modes.md:522-530
Architecture and Activation Logic
The "Modes" system is implemented as a core component of the SuperGemini setup. Architecturally, these modes are stored as behavioral instruction files (Markdown or TOML) in the SuperGemini/Modes/ directory and are installed to the user's ~/.gemini/ directory during setup.
Mode Activation Flow
Modes are governed by an intelligent adaptation system that monitors user input and environment state to determine the appropriate behavioral layer.
The diagram above illustrates the decision logic used to trigger specific behavioral modes based on the nature of the request and system state.
Sources: Docs/User-Guide/modes.md:522-530, CLAUDE.md:38-44
System Triggers
Activation is handled by a set of thresholds and keywords:
- Complexity Threshold: Triggered when a task spans more than 3 files or 2 directories.
- Resource Pressure: Triggered when context usage exceeds 75% of the limit.
- Uncertainty: Triggered by vague requirements or keywords like "maybe" or "explore".
- Error Recovery: Triggered during unexpected results or explicit requests for reasoning analysis.
Sources: Docs/User-Guide/modes.md:434-442, Docs/User-Guide/modes.md:522-530
Core Behavioral Modes
The framework defines six primary modes, each with specific purposes and auto-activation triggers.
| Mode | Key Purpose | Auto-Triggers | Behavioral Markers |
|---|---|---|---|
| 🧠 Creative Analysis | Requirement discovery | "analyze", "explore", vague ideas | Socratic questions, technical briefs |
| 🔍 Introspection | Meta-cognitive analysis | "analyze reasoning", error recovery | 🤔, 🎯, 💡, 📊 symbols |
| 📋 Task Management | Complex coordination | >3 steps, >2 directories | Plans, Phases, Tasks, Todos |
| 🎯 Orchestration | Intelligent tool routing | Multi-tool operations, >75% resource usage | Parallel tool execution, optimal routing |
| ⚡ Token Efficiency | Communication compression | --uc flag, >75% context usage | Symbols, 30-50% token reduction |
| 🎨 Standard | Balanced default | Simple, well-defined tasks | Professional, clear prose |
Sources: Docs/User-Guide/modes.md:44-55, Docs/User-Guide/modes.md:522-530
🧠 Creative Analysis Mode
This mode focuses on transforming vague project ideas into structured implementation plans. It shifts the AI's behavior to ask clarifying questions rather than providing immediate code solutions.
- Key Behavior: Produces technical briefs and implementation plans.
- Manual Activation:
/sg:analyze "topic"or--analyze.
Sources: Docs/User-Guide/modes.md:70-110
🔍 Introspection Mode
Introspection exposes the AI's reasoning process. It is primarily used for debugging and learning optimization, ensuring decision-making is transparent.
- Markers: Uses specific emojis for reasoning transparency: 🎯 (Decision), 🔄 (Alternative), 💡 (Learning).
- Manual Activation:
--introspect.
Sources: Docs/User-Guide/modes.md:124-155
📋 Task Management Mode
Designed for large-scale operations, this mode organizes work into a hierarchical structure: Plan → Phase → Task → Todo. It utilizes session persistence (memory integration) to track progress across multiple interactions.
- Key Feature: Quality gates between phase transitions.
- Manual Activation:
--task-manage.
Sources: Docs/User-Guide/modes.md:167-195
⚡ Token Efficiency Mode
This mode is critical for large codebases where context limits are a concern. It achieves 30-50% token reduction by substituting verbose technical descriptions with symbol systems.
- Auto-Trigger: Activated when context usage hits 75%.
- Manual Activation:
--ucor--ultracompressed.
Sources: Docs/User-Guide/modes.md:231-255, Docs/Reference/README.md:135
Implementation Details
The implementation of modes involves the ModesComponent class, which handles the lifecycle of behavioral instructions.
The Modes Component
The setup/components/modes.py file defines how modes are managed within the framework's installation engine.
# setup/components/modes.py:15-35
class ModesComponent(Component):
"""Component for behavioral modes"""
def get_metadata(self) -> Dict[str, Any]:
return {
"id": "modes",
"name": "Behavioral Modes",
"description": "Intelligent behavioral adaptation modes",
"version": "4.0.0"
}
Sources: setup/components/modes.py:15-35
Sequence of Installation
Modes rely on the "Core" component as a dependency to ensure the base behavioral files are present before specific mode instructions are injected.
This sequence demonstrates the dependency check and file transfer process for activating modes at the system level.
Sources: setup/components/modes.py:40-60, CLAUDE.md:38-44
Usage and Overrides
While modes are designed to be transparent, users can manually control them using CLI flags. These flags take priority over the automatic detection system.
- Multi-Mode Workflows: Modes can be "stacked." For example,
/sg:analyze "legacy-system" --introspect --uccombines requirements discovery with reasoning transparency and token compression. - Priority Rules: User-intent (manual flags) always overrides automatic triggers. Safety and validation behaviors (found in Task Management) always take precedence over efficiency optimizations.
Sources: Docs/User-Guide/modes.md:310-335, Docs/User-Guide/modes.md:448-460
Summary
The Modes system in SuperGemini Framework provides a dynamic orchestration layer that adapts Gemini CLI to the specific needs of a software development project. By separating behavioral instructions into distinct modes—ranging from Creative Analysis to Token Efficiency—the framework ensures optimal performance and reasoning depth regardless of task scale or resource availability. This configuration-driven approach allows for sophisticated AI behavior modification without altering the underlying application code.