Automatic Project-Specific System Prompts for Gemini CLI

This guide explains how to configure your shell to automatically use a project-specific system prompt for the Gemini CLI (gemini).

This "set it and forget it" approach ensures your custom project instructions are applied automatically without needing to remember special aliases.

How It Works

The solution uses a "smart" shell function that overrides the default gemini command. When you run gemini, this function searches up the directory tree for a conventional prompt file (.gemini/system.md).

• If found, it executes the gemini command with the GEMINI_SYSTEM_MD environment variable set to that file's path.
• If not found, it runs the gemini command as usual.

The performance impact is negligible, as the script uses highly optimized, built-in shell commands and adds only a few milliseconds of overhead.

Step 1: Adopt a Project Convention

In each of your projects, create a .gemini/system.md file at the project root. This file will contain your custom instructions for that specific project.

my_project/
├── .git/
├── .gemini/
│   └── system.md   # <-- Your custom instructions for this project
├── src/
└── ...

Step 2: Add the "Smart" Function to Your Shell Configuration

Add the following function to your ~/.zshrc (for Zsh) or ~/.bashrc (for Bash) file.

# A "smart" Gemini CLI function that automatically uses a project-specific
# system prompt if it finds one in the current directory or any parent directory.
gemini() {
  # The conventional path for the project-specific prompt file.
  local prompt_filename=".gemini/system.md"
  local current_dir="$PWD"
  local project_prompt_path=""

  # Traverse up from the current directory to the root to find the prompt file.
  while [ -n "$current_dir" ] && [ "$current_dir" != "/" ]; do
    if [ -f "$current_dir/$prompt_filename" ]; then
      project_prompt_path="$current_dir/$prompt_filename"
      break
    fi
    # Move to the parent directory.
    current_dir=$(dirname "$current_dir")
  done

  # If a project-specific prompt was found, use it.
  if [ -n "$project_prompt_path" ]; then
    # Inform the user that a project-specific prompt is being used.
    # This message is sent to stderr so it doesn't interfere with command output.
    echo "Info: Using project system prompt: $project_prompt_path" >&2

    # Execute the original gemini command with the GEMINI_SYSTEM_MD
    # environment variable set. 'command' prevents recursive function calls.
    GEMINI_SYSTEM_MD="$project_prompt_path" command gemini "$@"
  else
    # No project prompt found, so run the original gemini command as normal.
    command gemini "$@"
  fi
}

Step 3: Reload Your Shell

Apply the changes to your current shell session:

# For Zsh users
source ~/.zshrc

# For Bash users
source ~/.bashrc