feat: Add user-defined custom slash command support with argument, file

[yusei-murai]

TLDR

This pull request enhances the Gemini CLI by adding robust support for custom slash commands defined via Markdown files in the .gemini/commands/ directory. It ensures that custom commands can include argument substitution, file inclusion, and shell command execution, and that their output is correctly sent to the Gemini API and displayed in the CLI. The PR also improves the parsing and execution logic for both built-in and custom commands, and fixes several edge cases around argument handling and AI response extraction.

Dive Deeper

• Custom slash commands are now loaded at startup and appended to the available command list.
• Each custom command can use $ARGUMENTS for user input, @file for file inclusion for shell output inclusion in the prompt sent to Gemini.
• The action logic for custom commands now robustly handles prompt construction, error handling for file/shell access, and ensures the AI response is always a string.
• The command parsing logic is simplified and made more reliable, ensuring that arguments and subcommands are correctly passed to all command actions.
• The PR also includes defensive coding for unknown commands and improved error messages for users.

Reviewer Test Plan

1. Pull this branch and run the CLI locally.
2. Add a Markdown file (e.g., .gemini/commands/hello.md) with a template using $ARGUMENTS, @file, or !command.
3. Start the CLI and use your custom command, e.g., /project:hello world.
4. Confirm that:
   • The prompt is constructed as expected (arguments, file contents, shell output are substituted).
   • The AI response is displayed in the CLI.
5. Try built-in commands and confirm they still work as expected.
6. Optionally, run the test suite to ensure no regressions:

   npm run test
   

Testing Matrix

	🍏	🪟	🐧
npm run	❓	❓	❓
npx	❓	❓	❓
Docker	❓	❓	❓
Podman	❓	-	-
Seatbelt	❓	-	-

Linked issues / bugs

Issue: #2727
Issue: #2322

[gemini-code-assist]

Summary of Changes

Hello @yusei-murai, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request enhances the Gemini CLI by adding support for custom slash commands defined in Markdown files. It allows users to extend the CLI's functionality with custom prompts, argument handling, file inclusion, and shell command execution, improving flexibility and usability.

Highlights

• Custom Slash Commands: Introduces the ability to define custom slash commands via Markdown files in .gemini/commands/. These commands can include argument substitution ($ARGUMENTS), file inclusion (@file), and shell command execution (!command).
• Command Loading: Custom slash commands are loaded at startup and appended to the available command list, making them accessible like built-in commands.
• Prompt Construction: The action logic for custom commands handles prompt construction, error handling for file/shell access, and ensures the AI response is always a string.
• Argument Parsing: Simplifies command parsing logic to reliably pass arguments and subcommands to all command actions.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point in your pull request via creating an issue comment (i.e. comment on the pull request page) using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in issue comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist is currently in preview and may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments to provide feedback.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request introduces a feature for custom slash commands. There are critical issues related to security, correctness, and error handling that need to be addressed, including a potential arbitrary code execution vulnerability and a regression bug in argument parsing.

[bbiggs]

Rather than custom commands, are these named prompts? That is, should it be something like /p or /prompt that would also support custom prompts as provided by MCP servers?

https://modelcontextprotocol.io/docs/concepts/prompts

[yusei-murai]

My implementation is functionally very similar to MCP named prompts.
Commands can be executed using /project:command-name syntax, which supports variable substitution and file path inputs as well.

While it’s not using the /prompt prefix, the core idea aligns closely with the named prompt concept defined in MCP.

[psinha40898]

Hey there,

I noticed your PR and wanted to reach out about potentially collaborating. I've been working on this feature as well and noticed a few technical points about your PR that might be worth discussing:

1. The feature should detect commands that claude code detect (.md files without a description too)
2. The yaml package might be better than js-yaml
3. According to my understanding, the shell (!) and @ commands should be executed before the constructed prompt is sent to the LLM. They should be executed by the cli and the resulting prompt should be sent to the model. Currently, I'm not sure if these implementations are on the right track.
4. Ideally, the UX should not show the full constructed prompt or template in the CLI. This is likely solvable by adding a new history item type and not adding/rendering the full constructed prompt as a user history item.

I was wondering if you agree with my concerns and are open to collaboration. Ultimately, a core maintainer should decide if my analysis makes sense.

Good luck

[yusei-murai]

@psinha40898
Hi, thanks a lot for your detailed feedback!

I'm glad to hear that you've also been working on this feature — collaboration sounds great, and I’d be happy to discuss these points further:

1. yaml vs js-yaml
   I’ll try replacing js-yaml with yaml and see how it works out.

2. Command detection from .md files without description
   I’ll keep thinking about how best to handle this — thanks for pointing it out.

3. Shell (!) and @ command execution
   That makes a lot of sense. I’ll go ahead and make the necessary changes.

I’m based in Japan and it's late here, so I’ll take a look at your suggestions and work on the improvements tomorrow. Once I’ve made the changes, would you mind reviewing them again? After that, I'd love to chat more about how we could collaborate on this feature.

[psinha40898]

@yusei-murai

Sounds good and I would love to help

[abhipatel12]

Hey all thanks for the discussions and contribution. We have implemented custom commands using toml so going to close this!