Gemini CLI Extensions vs Commands: Differences and Loading Mechanisms Explained

Custom commands in Gemini CLI use standalone TOML files that load on-demand from ~/.gemini/commands/, while extensions use a JSON manifest to permanently inject context into every session's system prompt.

The ayghri/i-have-adhd repository implements both integration patterns to provide ADHD-friendly response formatting through the Gemini CLI runtime. Understanding the distinctions between Gemini CLI extensions and commands reveals how each loading mechanism affects session scope, activation triggers, and runtime behavior.

Core Architectural Differences

Custom Commands: On-Demand TOML Integration

Custom commands rely on self-contained TOML files that define isolated functionality. In the i-have-adhd repository, the command logic resides in skills/i-have-adhd/agents/gemini.toml, which users manually copy to ~/.gemini/commands/i-have-adhd.toml.

Key characteristics include:

• Session-local scope: Rules activate only for the specific session where the user types /i-have-adhd
• Explicit invocation: The command remains dormant until triggered by the slash command
• Argument substitution: Gemini processes {{args}} placeholders within the TOML prompt = """ ... """ block at runtime
• Manual updates: Users must re-run curl commands to fetch newer versions of the TOML file

Extensions: Persistent JSON Manifest Integration

Extensions provide always-on functionality through a declarative manifest approach. The repository's gemini-extension.json file instructs Gemini to treat the entire repository as a permanent runtime extension.

Key characteristics include:

• Global scope: Once installed via gemini extensions install https://github.com/ayghri/i-have-adhd, rules apply to all future sessions
• Automatic activation: No slash command required; the system prompt automatically includes the ADHD formatting rules
• Context file loading: The manifest points to GEMINI.md, which imports the canonical SKILL.md ruleset
• Managed lifecycle: Updates and uninstalls use gemini extensions update/uninstall commands

Loading Mechanisms Deep Dive

Command Loading: Directory Scanning and Lazy Execution

The Gemini CLI scans the ~/.gemini/commands/ directory at startup, indexing available .toml files. When a user invokes /i-have-adhd, the runtime:

1. Locates the matching TOML file in the commands directory
2. Parses the prompt definition and argument templates
3. Substitutes variables and executes the prompt block for that specific interaction

This lazy-loading approach means the ADHD ruleset affects only the current conversation thread, requiring re-invocation in new sessions.

Extension Loading: Manifest Parsing and System Prompt Injection

The extension mechanism operates through a different pipeline:

1. Gemini reads gemini-extension.json to identify the repository as an extension source
2. The runtime loads GEMINI.md as a context file, which contains imports to the full skill definition
3. These rules are prepended to the system prompt of every chat session automatically
4. The extension remains active across restarts until explicitly disabled or uninstalled

Installation and Usage Examples

Installing the Custom Command (Opt-In, Session-Based)

For temporary, on-demand access to the ADHD formatting rules:

# Create the commands directory and download the TOML file

mkdir -p ~/.gemini/commands
curl -fsSL https://raw.githubusercontent.com/ayghri/i-have-adhd/main/skills/i-have-adhd/agents/gemini.toml \
  -o ~/.gemini/commands/i-have-adhd.toml

# Activate for the current session only

/i-have-adhd

To remove: rm ~/.gemini/commands/i-have-adhd.toml

Installing the Extension (Always-On, Global)

For permanent behavioral modification across all Gemini sessions:

# Install via the GitHub repository URL

gemini extensions install https://github.com/ayghri/i-have-adhd

# Rules are now active automatically; no slash command needed

To update: gemini extensions update i-have-adhd

To remove: gemini extensions uninstall i-have-adhd

Key Files and Their Roles

Understanding the file structure clarifies how each loading mechanism functions:

• skills/i-have-adhd/agents/gemini.toml: Defines the custom command structure, including the prompt block that shapes ADHD-friendly responses when invoked via slash command.

• gemini-extension.json: The extension manifest that maps the repository to the GEMINI.md context file, enabling permanent integration.

• GEMINI.md: Serves as the entry point for extensions, importing the comprehensive SKILL.md ruleset into the system prompt.

• INSTALL.md: Documents both installation pathways and their respective trade-offs in the Gemini CLI section.

Summary

• Custom commands use TOML files in ~/.gemini/commands/, require manual installation via curl, and activate only when explicitly invoked with /i-have-adhd.
• Extensions use gemini-extension.json manifests, install via gemini extensions install, and automatically modify the system prompt for all sessions without user intervention.
• Loading mechanisms differ fundamentally: Commands scan directories at startup but execute lazily, while extensions parse JSON manifests to permanently inject context.
• Scope determines use case: Choose commands for temporary, opt-in functionality; choose extensions for permanent workflow modifications.
• Update paths vary: Commands require manual file replacement, while extensions use the native gemini extensions update command.

Frequently Asked Questions

What is the main difference between a Gemini CLI command and extension?

A custom command is a TOML file that remains dormant until you type a specific slash command like /i-have-adhd, affecting only the current session. An extension uses a JSON manifest to automatically load context files into every session's system prompt, modifying Gemini's behavior globally without requiring explicit activation.

How do I update or remove these integrations?

For commands, update by re-running the original curl command to overwrite the TOML file in ~/.gemini/commands/, or remove it manually with rm ~/.gemini/commands/i-have-adhd.toml. For extensions, use the native CLI commands: gemini extensions update i-have-adhd to refresh or gemini extensions uninstall i-have-adhd to completely remove the integration.

Which loading mechanism is better for permanent workflow changes?

Use the extension mechanism via gemini extensions install when you want ADHD-friendly formatting applied to every conversation automatically. The extension loads GEMINI.md (which imports SKILL.md) into the system prompt permanently, eliminating the need to remember slash commands while ensuring consistent behavior across all sessions.

Where are command files stored versus extension manifests?

Custom command TOML files reside in the user's home directory at ~/.gemini/commands/ (specifically i-have-adhd.toml). Extension manifests (gemini-extension.json) remain in the repository root, while the extension's context logic lives in repository files like GEMINI.md and SKILL.md that Gemini references after installation.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}