Configuring Gemini CLI

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• src/specify_cli/init.py
• templates/plan-template.md
• scripts/update-agent-context.sh
• CONTRIBUTING.md
• templates/agent-file-template.md
• spec-driven.md

Gemini CLI is one of the supported AI coding agents for executing the Spec-Driven Development (SDD) workflow within the spec-kit project. Proper configuration ensures that the Gemini agent has the necessary context to understand project requirements, adhere to architectural principles, and generate code effectively.

The configuration process involves two primary stages: initial project setup using the specify init command, and the automatic generation and maintenance of a GEMINI.md context file during the development lifecycle. This file acts as a dynamic set of guidelines for the AI.

Sources: README.md:80-82, CONTRIBUTING.md:15-16

Project Initialization

The specify CLI tool handles the initial setup of a project for use with Gemini. This is done via the init command, which prepares the project structure and necessary templates.

Sources: src/specify_cli/init.py:612-763, README.md:144-162

Selecting Gemini as the AI Agent

You can select Gemini CLI as your agent either through a command-line flag or an interactive prompt during initialization.

1. Using the --ai flag:

   specify init <project_name> --ai gemini
   

2. Using the interactive prompt: If the --ai flag is omitted, the CLI presents a selection menu where you can choose Gemini.

   # src/specify_cli/__init__.py:688-698
   else:
       # Use arrow-key selection interface
       selected_ai = select_with_arrows(
           AI_CHOICES, 
           "Choose your AI assistant:", 
           "copilot"
       )
   

The specify tool defines "gemini" as a valid choice, mapping it to the display name "Gemini CLI".

Sources: src/specify_cli/init.py:53-57, src/specify_cli/init.py:681-698

Prerequisite Check

During initialization, the CLI checks if the gemini command is available in the system's PATH. This check can be bypassed using the --ignore-agent-tools flag.

# src/specify_cli/__init__.py:701-711
if not ignore_agent_tools:
    agent_tool_missing = False
    # ...
    elif selected_ai == "gemini":
        if not check_tool("gemini", "Install from: https://github.com/google-gemini/gemini-cli%22):
            console.print("[red]Error:[/red] Gemini CLI is required for Gemini projects")
            agent_tool_missing = True

The following diagram illustrates the initialization flow when selecting Gemini.

The GEMINI.md Context File

A key component for configuring Gemini is the GEMINI.md file. This file is automatically generated and updated to provide the AI with crucial, up-to-date context about the project's technical landscape.

Generation

The GEMINI.md file is created during the /plan command's execution. The implementation plan template specifies that an agent-specific file (e.g., GEMINI.md) should be generated in Phase 1 of planning.

Sources: templates/plan-template.md:25-27

Structure

The GEMINI.md file is based on a standard template and contains several key sections that are incrementally updated.

Section	Description	Source File
Active Technologies	A list of languages, frameworks, and databases currently in use, extracted from plan.md files.	templates/agent-file-template.md
Project Structure	A high-level view of the repository's directory structure.	templates/agent-file-template.md
Commands	Relevant CLI commands for building, testing, and linting the project, specific to the active technologies.	templates/agent-file-template.md
Code Style	Language-specific coding style guidelines.	templates/agent-file-template.md
Recent Changes	A summary of the last three features and the technologies they introduced.	templates/agent-file-template.md
Manual Additions	A designated section for developers to add persistent, custom instructions for the AI.	templates/agent-file-template.md

Sources: templates/agent-file-template.md:1-21

Automatic Updates

The scripts/update-agent-context.sh script is responsible for keeping GEMINI.md synchronized with the project's evolution. This script is typically called during the /plan phase.

The script performs the following actions:

1. Identifies GEMINI.md as a target file if the gemini agent type is specified or detected.
2. Parses the latest plan.md for new technologies (language, framework, database).
3. Reads the existing GEMINI.md file.
4. Incrementally adds new technologies, commands, and recent changes without overwriting existing entries.
5. Preserves any content within the <!-- MANUAL ADDITIONS START --> and <!-- MANUAL ADDITIONS END --> markers.
6. Updates the "Last updated" timestamp.

The following diagram shows the update flow for GEMINI.md.

Usage in the SDD Workflow

Once configured, the Gemini CLI is used to drive the main phases of the Spec-Driven Development workflow.

The user interacts with the gemini command, passing the spec-kit commands (/specify, /plan, /tasks) as arguments.

Summary

Configuring spec-kit for use with Gemini CLI is a streamlined process. It begins with a one-time selection during specify init, which validates the presence of the gemini tool. Subsequently, the system automatically manages a GEMINI.md context file, ensuring the AI agent remains synchronized with the project's technical decisions and structure throughout the development lifecycle. This automated context management is crucial for enabling Gemini to effectively execute the /specify, /plan, and /tasks commands.