Settings & Configuration Management
Relevant source files
The following files were used as context for generating this wiki page:
Settings & Configuration Management in the SuperGemini Framework provides the foundational infrastructure for environment detection, path resolution, and persistent state management. The system is designed to handle cross-platform pathing (Linux, macOS, Windows) and manage the installation of behavioral configuration files to the user's home directory.
The system operates primarily as a configuration distribution layer. It manages the lifecycle of settings that dictate how the framework interacts with the Gemini CLI, ensuring that environment variables, path overrides, and component-specific configurations are correctly applied during the SuperGemini install and update workflows.
Sources: CLAUDE.md:10-18, setup/utils/paths.py:1-10
Path Management and Environment Detection
The framework utilizes a centralized path utility to ensure consistent file operations across different operating systems. It defines standard installation targets and provides mechanisms for overriding these paths via environment variables.
Path Resolution Logic
The system resolves paths by first checking for environment overrides and falling back to default user-owned directories.
The diagram shows the logic used to determine file locations, prioritizing user-defined environment variables over system defaults.
Sources: setup/utils/paths.py:45-65, CLAUDE.md:270-280
Core Path Definitions
| Path Variable | Default Value / Logic | Purpose |
|---|---|---|
HOME | Path.home() | Base user directory for all configurations. |
DEFAULT_INSTALL_DIR | ~/.gemini/ | Primary target for behavioral .md and .toml files. |
SUPERGEMINI_COMPONENTS_PATH | Environment Override | Allows custom redirection of installed components. |
VERSION_FILE | Root VERSION | Single source of truth for framework versioning. |
Sources: setup/utils/paths.py:12-25, CLAUDE.md:235-245
Component-Based Configuration
SuperGemini is organized into six distinct component types, each managed through a structured installation and configuration lifecycle.
Configuration Lifecycle
The configuration for each component (Commands, Agents, Modes, MCP) is handled by the setup/services/ layer, which orchestrates how these files are moved from the package source to the active environment.
This sequence illustrates the interaction between the installation services and the filesystem when deploying component configurations.
Sources: CLAUDE.md:120-140, setup/services/config.py:15-35
Behavioral Modes and Instruction Injection
A key feature of the configuration management system is "Behavioral Instruction Injection." Instead of modifying code, the system modifies AI behavior by injecting structured instructions stored in the configuration directory.
Mode Configuration Flags
Configuration flags allow users to manually override the automatic behavioral mode detection. These flags are processed by the settings service to adjust the prompt injection strategy.
| Flag | Mode Name | Configuration Effect |
|---|---|---|
--analyze | Creative Analysis | Injects requirement analysis instructions. |
--introspect | Introspection | Exposes reasoning markers (🤔, 🎯). |
--uc | Token Efficiency | Activates symbol-based communication protocols. |
--task-manage | Task Management | Enables Plan -> Phase -> Task structures. |
Sources: Docs/User-Guide/modes.md:10-50, CLAUDE.md:180-195
Command Namespace Configuration
The framework manages two distinct command spaces via its configuration logic:
- Terminal Commands: Python-executable logic for managing the framework (e.g.,
SuperGemini install). - Slash Commands: TOML-based configurations injected into the Gemini CLI (e.g.,
/sg:analyze).
These slash commands are NOT Python functions; they are configurations that define prompts and allowed tools.
Sources: CLAUDE.md:155-175
Version and Metadata Management
The framework maintains a strict versioning policy where a single VERSION file acts as the source of truth for all components and build scripts.
The diagram depicts the propagation of version settings from a single file across the entire framework ecosystem.
Sources: CLAUDE.md:230-245
Conclusion
Settings & Configuration Management in SuperGemini Framework ensures a secure and consistent environment for AI behavior modification. By leveraging cross-platform path resolution, environment variable overrides, and a centralized versioning system, the framework provides a robust foundation for installing and updating its meta-programming components without requiring direct code modifications to the host CLI.
Sources: CLAUDE.md:10-25, setup/utils/paths.py:1-15