CLI & Setup Internals
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 via behavioral instruction injection rather than direct code modification of the AI's core runtime. The CLI and setup internals function as a configuration distribution system that installs behavioral instructions (.md, .toml) into the user's local ~/.gemini/ directory to modify the AI's orchestration patterns.
Sources: CLAUDE.md:12-16, README.md:18-24
The system distinguishes between Terminal Commands (used for installation and management) and Slash Commands (used within the Gemini CLI environment). The Python-based setup/ module handles the logic for file copying, validation, and configuration management, ensuring that the behavioral "payload" in the SuperGemini/ source directory is correctly deployed to the target environment.
Sources: CLAUDE.md:112-124, Docs/Getting-Started/installation.md:25-30
Architecture Overview
The framework employs a "Dual Directory Structure" to separate the installer logic from the instruction payload.
Directory Roles
setup/(The Installer): Contains the Python code responsible for executing installation, updates, and uninstallation. It manages system checks, permission validation, and MCP configuration.SuperGemini/(The Payload): Contains the Markdown and TOML files that are copied to~/.gemini/. These include the 13 specialized AI agents and 18 slash commands.
Sources: CLAUDE.md:112-124, README.md:18-24
System Flow
The following diagram illustrates the flow from the user executing a terminal command to the successful injection of behavioral instructions into the Gemini CLI environment.
The diagram shows the sequential steps taken by the setup system to prepare the local environment.
Sources: CLAUDE.md:112-132, Docs/Getting-Started/installation.md:144-155
Installation Mechanism
Installation is performed via the SuperGemini install command. The framework supports multiple installation profiles and selective component deployment.
Installation Components
The system manages six distinct component types, each handled by specific installer logic:
- Core: Essential framework files (RULES.md, PRINCIPLES.md, FLAGS.md).
- Commands: 18 TOML-based slash commands deployed to
~/.gemini/commands/sg/. - Modes: Operation modes like brainstorming or introspection.
- Agents: 13 specialized AI personas using "Persona Mode."
- MCP: Configuration for external Model Context Protocol servers.
- MCP Docs: Documentation files for the integrated servers.
Sources: CLAUDE.md:95-103, Docs/Getting-Started/installation.md:162-171
Execution Logic Table
| Component | Destination Path | Primary Function |
|---|---|---|
| Core | ~/.gemini/ | Global behavior and development principles |
| Commands | ~/.gemini/commands/sg/ | Injects prompts for /sg: namespace |
| Agents | ~/.gemini/ | specialized personas like system-architect |
| MCP | ~/.gemini/.gemini.json | Configures external tool integration |
Sources: CLAUDE.md:95-103, Docs/Getting-Started/installation.md:185-195
Command Syntax and Namespaces
A critical aspect of the internals is the strict separation of command namespaces to prevent user confusion between the installer and the runtime environment.
Namespace Distinction
- Terminal Namespace (
SuperGemini): Capitalized primary entry point for the Python management tool. Handlesinstall,update,uninstall, andbackup. - Slash Command Namespace (
/sg:): Lowercase prefix used inside the Gemini CLI. These commands are mapped to TOML files in the~/.gemini/commands/sg/directory.
Sources: CLAUDE.md:137-148, claudedocs/CSI_WF.md:37-47
TOML Conversion Process
Commands are authored in Markdown (.md) with front matter and converted to TOML format during the installation process for Gemini CLI compatibility.
prompt = """SuperGemini Framework Command: /sg:analyze
[Full instructions here...]
"""
description = "Analyze codebase architecture"
Sources: CLAUDE.md:155-170
Uninstall and Maintenance
The framework enforces a two-step uninstallation process to prevent accidental data loss of user customizations.
Uninstallation Sequence
The sequence illustrates the protective separation between framework instructions and user configurations.
Sources: Docs/Getting-Started/installation.md:275-290
Security and Validation
The setup internals include validation checks to prevent path traversal and ensure safe path resolution during file operations. It uses pathlib.Path for cross-platform compatibility and validates target directories before execution.
Sources: CLAUDE.md:248-255, CLAUDE.md:273-280
Summary
The CLI & Setup Internals of SuperGemini serve as a robust bridge between the framework's behavioral instructions and the Gemini CLI runtime. By utilizing a Python-based installer to manage a configuration-driven "payload," the system provides a specialized development environment through systematic workflow automation and intelligent agent coordination.
Sources: CLAUDE.md:12-25, Docs/Getting-Started/installation.md:15-20