# Gemini CLI Extensions vs Commands: Differences and Loading Mechanisms Explained

> Understand Gemini CLI extensions vs commands. Learn how commands load on-demand while extensions inject context permanently. Discover the key differences and mechanisms.

- Repository: [Ayoub Ghriss/i-have-adhd](https://github.com/ayghri/i-have-adhd)
- Tags: deep-dive
- Published: 2026-09-10

---

**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`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/GEMINI.md), which imports the canonical [`SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/gemini-extension.json) to identify the repository as an extension source
2. The runtime loads [`GEMINI.md`](https://github.com/ayghri/i-have-adhd/blob/main/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:

```bash

# 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:

```bash

# 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`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/gemini-extension.json)**: The extension manifest that maps the repository to the [`GEMINI.md`](https://github.com/ayghri/i-have-adhd/blob/main/GEMINI.md) context file, enabling permanent integration.

- **[`GEMINI.md`](https://github.com/ayghri/i-have-adhd/blob/main/GEMINI.md)**: Serves as the entry point for extensions, importing the comprehensive [`SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/SKILL.md) ruleset into the system prompt.

- **[`INSTALL.md`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/GEMINI.md) (which imports [`SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/i-have-adhd.toml)). Extension manifests ([`gemini-extension.json`](https://github.com/ayghri/i-have-adhd/blob/main/gemini-extension.json)) remain in the repository root, while the extension's context logic lives in repository files like [`GEMINI.md`](https://github.com/ayghri/i-have-adhd/blob/main/GEMINI.md) and [`SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/SKILL.md) that Gemini references after installation.