[Tracking Issue] The Future of Slash Commands: Towards an Extensible Automation Platform

[abhipatel12]

Hey everyone!

With the recent merge of the slash command architectural refactor (see PR #3175), we've successfully laid a new foundation for what's possible with commands in the Gemini CLI.

This refactor was the necessary first step towards a much broader vision. Now that the groundwork is in place, we want to open up a community-wide discussion about where we go next.

The Vision: From Commands to a Platform

Our long-term vision is to evolve slash commands from a simple convenience feature into a powerful, user-driven automation platform. We want to empower you to teach Gemini CLI your unique workflows by creating a library of powerful, composable commands tailored to your projects.

The New Foundation: How We'll Get There

The recent refactor introduced the CommandService, which is the key to this entire vision. It acts as a central hub that can discover commands from multiple sources and build a unified command tree.

+-------------------+      +---------------------+      +--------------------+
|   Built-in cmds   |      | Local Command Files |      | MCP Server Prompts |
| (TS Objects with  |      |  (.gemini.toml with |      | (via an API client)|
|  subCommands)     |      |   subCommands)      |      +--------------------+
+-------------------+      +---------------------+               |
         |                        | (Discovers & Parses)         | (Discovers via API)
         | (Loads)                |                              |
         +------------------------+------------------------------+
                                  |
                      +---------------------------+
                      |      CommandService       |
                      | (Builds unified command   |
                      |           TREE)           |
                      +---------------------------+
                                  |
                                  | (Provides Tree)
                                  v
                    +-----------------------------+
                    |  CLI UI / useSlashProcessor |
                    | (Traverses tree to execute) |
                    +-----------------------------+

This architecture means we can now "plug in" new command sources without changing the core UI. This is where we need your ideas!

The Next Steps: A Call for Discussion

We want to focus our efforts on the following two steps. Our goal is to design these features in a way that makes them robust on their own, while setting the stage for them to be chainable and composable in the future.

Phase 1: Custom User-Defined Commands (The Immediate Next Step)

(Discussion for this phase will lead to a dedicated sub-issue for the final design)

• The Idea: Allow users to define their own slash commands in a local configuration file. We believe TOML (.toml) is an excellent format for this, as its explicit syntax helps prevent common configuration errors. Commands could live at a project level (<project>/.gemini/commands/) and a user level (~/.gemini/commands/).

• Example .gemini/commands/git.gemini.toml:

      # This command would be invoked via "/git commit --type feat"
      name = "git"
      description = "Commands for interacting with the git repository."
      
      # Defines an item in the 'subCommands' array using TOML's "array of tables" syntax
      [[subCommands]]
      name = "commit"
      description = "Creates a conventional commit message for staged changes."
      prompt = """
      Generate a conventional commit message of type '{{type}}' for the currently staged changes.
      """
  
        # Defines an argument for the 'commit' subcommand
        # Note the nested "array of tables" syntax
        [[subCommands.args]]
        name = "type"
        description = "Commit type (e.g., feat, fix, chore)."
        required = true

• Discussion Points:

  • We are proposing TOML as the default for its clear and unambiguous syntax. However, we know YAML and Markdown is also very common in the ecosystem. We are very open to feedback here—what are the pros and cons of this choice for your workflow?
  • What's the ideal way to define arguments within the chosen format?
  • Future-Proofing: How can we structure the format so commands can eventually be "chained" in a workflow?

Phase 2: An Integrated Ecosystem with MCP

• The Idea: Implement the CommandService to discover commands from remote sources that implement the Model Context Protocol (MCP). This turns the CLI into a client for a larger ecosystem of tools. You can read more about the protocol here. These remote commands should feel completely native, so they too can be part of any future composition or chaining features.
• Example Scenario: A team connects their internal Jira server, which exposes an MCP endpoint. The server has a prompt named create-ticket.
  1. On startup, Gemini CLI queries the server and discovers this prompt.
  2. It automatically creates a new command: /jira:create-ticket.
  3. A developer can now run /jira:create-ticket --summary "Fix login button" --type Bug directly in their terminal. The CLI handles calling the remote service and returning the result.
• Discussion Points: What kind of remote services would be most useful to integrate? What would the configuration for connecting to a new MCP-enabled service look like?

How to Get Involved & Our Contribution Process

This issue will serve as the main "Town Hall" for the vision. To ensure we build this feature collaboratively and efficiently, we will use the following process:

1. Discuss Ideas Here First: Use the comments below to discuss the overall vision and the high-level ideas for each phase.
2. Formalize a Design in a Sub-Issue: Once a high-level idea gains consensus, we will create a new, dedicated sub-issue to define the specific "blueprint" for it. This is where we will finalize details like TOML syntax or API contracts.
3. Implement After Approval: Please do not start work on a Pull Request until the design in the corresponding sub-issue has been discussed and approved by the maintainers. This ensures your hard work aligns with the project's direction and has a clear path to being merged.

Consolidating Our Efforts

Current Issues

• Issue Support user-defined custom slash commands #2727
• Issue please add custom slash commands similar to those allowed by claude code. #2322
• Issue FR write down my own "@" or "/" commands as defined in the GEMINI.md file #805

Current PRs

• PR (WIP) feat: custom slash commands à la claude code #3441
• PR Feat(cli): Define prompt files and reuse them #3115 #3366
• PR feat: Add user-defined custom slash command support with argument, file #2726
• PR Feat(cli): Define prompt files and reuse them #3115 #3366

Let's build this together! 🚀

[allenhutchison]

This is a fantastic initiative, and thank you for opening up this discussion. The vision to evolve slash commands into a user-driven automation platform is incredibly exciting. The CommandService architecture is a solid foundation for this.

After reviewing the core proposal, the related issues (#805, #2322, #2727), and the excellent community PRs (#2726, #3366, #3441), I have some feedback that I hope can help shape the final design. My thoughts center on three main areas: ensuring powerful templating, expanding the scope to include local executables, and clarifying the non-interactive user experience.

1. Strong Support for Named Arguments and Templating

I strongly support the proposed TOML structure that includes first-class support for multiple, named arguments. For commands to be truly powerful, reusable, and clear, a simple catch-all variable like $ARGUMENTS is too limiting. The ability to define specific arguments ([[subCommands.args]]) and then substitute them into a prompt template ("{{arg_name}}") is crucial for complex workflows. This structured approach is a key advantage and should be a core part of the design.

2. Broaden the Vision: From "Prompts" to "Actions"

While generating prompts for the LLM is a primary use case, we can make this platform vastly more powerful by thinking of commands as executing "actions" rather than just building "prompts". As a CLI application, Gemini should be able to integrate with the local command-line environment.

I propose we design the command schema to support different types of actions. Specifically, alongside the prompt key, we could introduce an execute key for running local shell commands.

Here’s how it might look in the TOML definition:

# A command that generates a prompt (current proposal)
[[subCommands]]
name = "commit"
description = "Creates a conventional commit message for staged changes."
prompt = """
Generate a conventional commit message of type '{{type}}' for the currently staged changes.
"""
  [[subCommands.args]]
  name = "type"
  required = true

# A command that executes a local binary
[[subCommands]]
name = "stage"
description = "Stages a file using git."
execute = "git add {{path}}"
  [[subCommands.args]]
  name = "path"
  required = true

This would allow users to wrap their existing scripts and command-line tools, making them available within the Gemini ecosystem. It also sets a clear path for future "chaining," where an execute command could pipe its output to a prompt command.

3. A Clear Path for Non-Interactive Execution

As we build this powerful system, we must consider the non-interactive (headless) experience from the start. To maintain a clean separation of concerns between the interactive and non-interactive modes, I strongly recommend introducing a new, dedicated flag for executing commands.

Instead of overloading gemini --prompt "/my_command", we could have:

gemini --execute "/my_command --arg value"

The benefits are significant:

• Architectural Clarity: It creates an explicit entry point for the command system, keeping it separate from the simpler logic that just passes a prompt to the LLM.
• Performance: The CLI would only need to initialize the full CommandService (discovering all custom commands) when --execute is used, avoiding startup latency for simple gemini "a prompt" calls.
• User Experience: It makes the user's intent unambiguous. --prompt is for the LLM; --execute is for the command automation platform.

---

Thank you again for leading this effort. I believe that incorporating these ideas will result in a flexible and powerful platform that truly empowers users to automate their workflows. I'm looking forward to the continued discussion!

[taeold]

This looks great. Thank you so much for leading the charge here!

I love the how configurable TOML-based syntax is, but I think there is something to be said about how clever Claude Code's custom slash command support is (https://docs.anthropic.com/en/docs/claude-code/slash-commands).

They are simply prompts which makes it really easy for anyone to get started. You can literally do something like

echo "Say hello" > .claude/commands/hello.md`

to start your own collection of custom commands.

Given how generally useful Gemini CLI is becoming (my cousin, an accountant, uses Gemini CLI!), I think there is quite a bit of value in considering barrier to entry for writing their own custom commands. TOMLs, imo, are not that friendly towards non-programmers.

To extend the idea of "it's just prompt" further, there is something beautiful about this idea. It means that AI agent can (and will) ask the user for more information if it doesn't have sufficient information to carry out the command.

For example, instead of this:

> /git add
=> ERROR: missing required argument "--path"

You can end up with an interaction like this:

> /git add
Gemini: Which files would you like to add?
> main.js
Gemini: Running shell command `git add main.js`

I'm not saying that latter is necessarily better. Probabilistic nature of these models mean that it might actually fail to execute the desired command. But the latter does seem more "agentic" to me and something that's only possible in a "agentic" experience like Gemini CLI. Mayb we should leverage this?

Again, I'm not casting a vote against current proposal. Just wanted to share my thoughts on why starting with simple markdown can lower the barrier to using the feature and also lead us into interesting, and potentially more powerful experience.

[abhipatel12]

Wow, a huge thank you to both @allenhutchison and @taeold for this awesome feedback. This is exactly the kind of discussion I was hoping for.

• Allen, you're fighting for the power user, laying out a vision for a structured, rock-solid system that can handle complex workflows.
• Daniel, you're championing a frictionless UX, making sure anyone can jump in and immediately benefit from the custom commands.

Here, it seems like we're choosing between Power and Simplicity. I want to propose the idea that we can do both!

A Possible Proposal: A "Progressive Enhancement" Model

We can build a system that lets you start simple and then "level up" to more powerful features whenever you need them. No friction to start, no ceiling to hold you back. A user can start quickly and then progressively adopt more powerful features as they need them.

Here's how it would work:

1. Start with Simplicity: Native .md Command Support

We can fully embrace Daniel's suggestion for a low-friction entry point. The CommandService will natively support discovering simple Markdown files.

• How it works: A user creates .gemini/commands/summarize.md (we can make the directory configurable). The CLI automatically creates a /summarize command. This will support simple argument substitution (e.g., $ARGS) and namespacing via subdirectories, making it easy for users to bring over existing prompt libraries.
• Benefit: This provides a zero-config way for anyone to save and reuse prompts, matching the ease of use of other tools in the ecosystem and immediately supporting users with existing prompt libraries.

2. Upgrade to Power: Structured .toml Workflows

While simple prompts are great, there are limitations of that approach when building truly reusable automations. Relying on "magic strings" (like !) or unstructured arguments can become brittle. This is why we need a more robust format, and where we can fully incorporate Allen's excellent suggestions.

• The Upgrade Path: When a user's needs outgrow Markdown, they can "upgrade" to our proposed .toml format to gain access to a much richer feature set. We can even build a utility (/command upgrade) to help with this.

• Adopting Allen's Suggestions for .toml:

  • From "Prompts" to "Actions": The schema will support both a prompt key (for the LLM) and an execute key for running local shell commands.
  • Headless Execution: The gemini --execute "/my_command" flag is the right long-term architectural decision, and we should build towards it.

This two-format approach gives us the best of both worlds: the accessibility of Markdown and the structured power of TOML.

"Agentic" Conversation Runtime Behavior

@taeold, your idea of the agent asking follow-up questions is fantastic. This is a powerful UX concept for the command runner itself, separate from the file format. To give this the focus it deserves, how do you feel about spinning it off into a new, separate issue for future exploration?

Feedback?

1. Proposal: We move forward with a unified plan to support both .md (for simple prompt shortcuts) and .toml (for structured, actionable workflows) from the start.
2. Immediate Goal: We create a new sub-issue to formalize the TOML specification, incorporating the execute key like Allen proposed. This will be the blueprint for the initial impl work.
3. Discussion: Does this "progressive enhancement" model feel like the right path forward? @taeold, do you feel this addresses the concerns for a high friction setup? @allenhutchison, any concerns about this approach to offer two formats?

Thank you both again for helping shape a much stronger vision for this feature!

[youngfly93]

My thoughts are:

The custom slash commands system allows users to extend Gemini CLI with their own reusable workflows and automation commands. This feature enables both project-specific and personal command creation using multiple formats.

Quick Example

Let's create a custom command using Markdown format to quickly check system status:

1. Create the Markdown command file

# Create the personal commands directory if it doesn't exist
mkdir -p ~/.gemini/commands

# Create a system status command using Markdown format
cat > ~/.gemini/commands/sysinfo.md << 'EOF'
# System Information

Display comprehensive system information including OS details, disk usage, and memory status.

## Usage
- `/sysinfo` - Display full system information
- `/sys` - Short alias for system info

```bash
echo "=== System Information ==="
uname -a
echo ""
echo "=== Disk Usage ==="
df -h | head -5
echo ""
echo "=== Memory Usage ==="
free -h 2>/dev/null || vm_stat | head -10
echo ""
echo "=== Current Time ==="
date

Category: utilities
Tags: system, info, diagnostics
AltName: sys
EOF

### 2. Use the command in Gemini CLI
```bash
# Start Gemini CLI
gemini

# Use your custom Markdown command
> /sysinfo          # Full name
> /sys              # Short name (from AltName)

# Check all available commands
> /help             # Your custom command will appear here
> /help --category utilities  # Filter by category

3. Expected output

=== System Information ===
Darwin MacBook-Pro.local 23.1.0 Darwin Kernel Version 23.1.0

=== Disk Usage ===
Filesystem      Size  Used Avail Use% Mounted on
/dev/disk1s1   500G  250G  248G  51% /

=== Memory Usage ===
               total        used        free
Mem:            16Gi       8.2Gi       7.8Gi

=== Current Time ===
Fri Jul 12 15:30:45 CST 2025

Overview

The custom slash commands system allows users to extend Gemini CLI with their own reusable workflows and automation commands. This feature enables both project-specific and personal command creation using multiple formats.

Architecture

Core Components

1. CustomCommandLoader (packages/cli/src/services/CustomCommandLoader.ts)

   • Handles discovery and loading of custom commands
   • Supports multiple file formats (TypeScript, JSON, Markdown)
   • Implements file watching for hot-reload functionality
   • Manages command validation and error handling

2. CommandService (packages/cli/src/services/CommandService.ts)

   • Integrates custom commands with built-in commands
   • Manages command registry and deduplication
   • Handles command override logic
   • Provides command categorization and filtering

3. SlashCommand Type (packages/cli/src/ui/commands/types.ts)

   • Extended to support additional metadata
   • Includes scope, category, tags, and versioning
   • Supports multiple execution modes

Implementation Details

Command Discovery Process

// Command directories structure
const commandDirs = [
  '.gemini/commands/',      // Project-level commands
  '~/.gemini/commands/'     // Personal commands
];

Loading Mechanism

1. File System Scanning: Recursively scans command directories
2. Format Detection: Identifies command format by file extension
3. Dynamic Loading: Uses dynamic imports for TypeScript modules
4. Validation: Validates command structure before registration
5. Deduplication: Ensures unique commands (custom can override built-in)

Hot-Reload Implementation

// File watching for development
FSWatcher monitors command directories
↓
File change detected
↓
Reload affected command
↓
Update command registry
↓
Notify UI of changes

Usage Guide

1. Creating Commands

JSON Format

// .gemini/commands/build.json
{
  "name": "build",
  "description": "Build the project",
  "category": "development",
  "command": "npm run build"
}

TypeScript Format

// .gemini/commands/deploy.ts
import { SlashCommand } from '@google/gemini-cli';

export default {
  name: 'deploy',
  altName: 'd',
  description: 'Deploy to environment',
  category: 'deployment',
  
  async execute(args: string[], context: any) {
    const env = args[0] || 'staging';
    console.log(`Deploying to ${env}...`);
    
    return {
      type: 'shell',
      command: `npm run deploy:${env}`
    };
  }
} as SlashCommand;

Markdown Format

# Database Reset

Reset the development database and run migrations.

## Usage
- `/db-reset` - Reset with sample data
- `/db-reset --clean` - Reset without sample data

```bash
npm run db:reset
npm run db:migrate
npm run db:seed

Category: database
Tags: db, reset, development

### 2. Command Structure

```typescript
interface SlashCommand {
  name: string;                    // Command name (required)
  altName?: string;                // Alternative/short name
  description?: string;            // Command description
  category?: string;               // Command category
  action?: (args: string[]) => Promise<void>;
  completion?: (args: string[]) => string[];
  metadata?: {
    scope?: 'builtin' | 'project' | 'personal';
    sourceFormat?: 'typescript' | 'json' | 'markdown';
    sourcePath?: string;
    category?: string;
    tags?: string[];
    author?: string;
    version?: string;
    canExecuteShell?: boolean;
  };
}

3. Using Commands

# Start Gemini CLI
gemini

# Use custom commands
> /build              # Run build command
> /deploy prod        # Deploy with arguments
> /d                  # Use alternative name

# List commands
> /help               # Show all commands
> /help --scope project    # Show project commands only
> /help --category deploy  # Show deployment commands

4. Command Execution Flow

User types: /deploy prod
↓
SlashCommandProcessor intercepts
↓
CommandService lookup
↓
Command found & validated
↓
Execute command action
↓
Return result to UI

Advanced Features

Command Override

Custom commands can override built-in commands by using the same name:

// Override built-in help command
export default {
  name: 'help',
  description: 'Custom help command',
  async execute() {
    return {
      type: 'message',
      content: 'Custom help message...'
    };
  }
} as SlashCommand;

Hot-Reload Development

# Enable debug mode for hot-reload feedback
DEBUG=1 gemini

# Edit command files - changes apply immediately

Command Scopes

• Project Commands (.gemini/commands/): Shared with team via version control
• Personal Commands (~/.gemini/commands/): Private to user, available across all projects

Execution Modes

1. Shell Command: Execute shell commands

return { type: 'shell', command: 'npm test' };

2. Message Output: Display messages

return { type: 'message', content: 'Hello!' };

3. Custom Logic: Run TypeScript code

async execute(args) {
  // Custom implementation
  const result = await apiCall();
  return { type: 'message', content: result };
}

Security Considerations

1. Command Validation: All commands are validated before execution
2. Shell Execution: Commands must explicitly declare shell execution capability
3. Sandboxing: Respects Gemini CLI's existing sandbox settings
4. No Implicit Evaluation: Command strings are not evaluated as code

Best Practices

1. Naming Conventions

   • Use lowercase with hyphens: deploy-staging
   • Keep names descriptive but concise
   • Use categories for organization

2. Error Handling

   • Always validate arguments in TypeScript commands
   • Provide helpful error messages
   • Handle async operations properly

3. Documentation

   • Include clear descriptions
   • Document expected arguments
   • Add usage examples in comments

4. Performance

   • Use JSON for simple commands (faster loading)
   • Use TypeScript only when custom logic is needed
   • Use Markdown for documentation-driven commands
   • Avoid heavy imports in command files

Troubleshooting

Commands Not Loading

• Check file permissions
• Verify JSON syntax
• Ensure TypeScript files export default
• Check DEBUG=1 output for errors

Hot-Reload Issues

• Verify file system watch permissions
• Check that command directories exist
• Ensure no syntax errors in files

Command Conflicts

• Custom commands override built-in ones
• Check for duplicate names across scopes
• Use unique names or namespacing%

[taeold]

@abhipatel12 - "why not both" is an excellent resolution haha. I also like how supporting both means it would also make it easy for existing claude code users to migrate over their custom commands to Gemini CLI with just a cp ./claude/commands/* ./gemini/commands which sounds useful!

[rksh1997]

I also support adding support for both Markdown prompts and TOML prompts. However, I have some ideas that I want to share:

1. Markdown files should support named variables, like: Say hello to {{name}}. These variables could be filled in either via flags (--name) or interactively similar to how it's implemented in Feat(cli): Define prompt files and reuse them #3115 #3366
2. For advanced prompts. I propose defining a JSON-based prompt specification. Then we can build adapters for TOML, YAML, Markdown or any other format that map to this core JSON structure.

An argument:

I am still not understanding the need for "Custom commands" rather than "Custom prompts". In my view I understand that a command does a specific deterministic task which you know the result of. While prompts rely on the output of the model and is inherently probabilistic or generative.

So mixing both in the same place doesn't make sense to me. I wouldn't like seeing /exit and then /customer_support_mail_draft underneath it.

[Manamama]

Re: @taeold's excellent point on 'barriers to entry' and the 'accountant cousin' in this discussion:

I've found a nifty way to tackle this: I consistently use Gemini CLI itself to 'self-code' its own operational configurations and snippets, including .json system files. I even have it read its own architectural documentation, which resulted in this as idea (half-tested, q.v.): https://github.com/Manamama/Puzzles_for_AIs/tree/main/docs/pmbok_instructions and https://github.com/Manamama/Puzzles_for_AIs/blob/main/docs/pmbok_instructions/workflows/git_and_GitHub_workflow.md, often using ln -s for allowing it quick access via read_file itself (another trick of mine).

This approach means I frequently operate in my ~/.gemini folder, where Gemini and I collaborate to tackle complex tasks. For instance, we recently fixed an MCP issue here: modelcontextprotocol/servers#2332, and previously, we resolved another problem (I'm not a coder, but it took us less than an hour): #3965 (comment).

My core idea is this: if Gemini can help users like me (who aren't IT pros) generate and manage these configurations, it significantly lowers the technical barrier. I propose we make this 'AI-assisted configuration' capability more visible, perhaps by adding a note in the main README. Then the question if the files be yaml, Markdown or toml shall self-solve itself, vicariously (via Gemini Core AI itself operating in its CLI).
It could be a game-changer for wider adoption.

ver. 1.2 style fixes, ln -s trick explained