Configure Gemini CLI with a GEMINI.md File

How to Configure Gemini CLI with a GEMINI.md File

Once you have the Gemini CLI set up in your project, you can begin leveraging its power to interact with your codebase. Before diving into code generation, bug hunting, or feature development, it’s highly recommended to create a `GEMINI.md` file. This markdown file serves as a crucial configuration document, providing the AI model with specific instructions about your project’s conventions, architecture, preferred libraries, and coding styles. By defining these preferences, you ensure that the AI generates code that aligns with your project’s standards and your personal coding habits.

What You’ll Learn

This guide will walk you through the process of creating and configuring your `GEMINI.md` file. You will learn how to:

• Automatically generate a `GEMINI.md` file by having the Gemini CLI analyze your existing codebase.
• Understand and manage the permissions required for the CLI to make file changes.
• Manually add or edit project-specific instructions and coding preferences within the `GEMINI.md` file.
• Refresh the Gemini CLI’s memory to recognize the new or updated configuration file.
• Explore the concept of project-level, subdirectory-level, and global `GEMINI.md` files for comprehensive context.

Prerequisites

• Gemini CLI installed and set up in your project.
• An existing project with some codebase (for automatic generation).
• Basic understanding of your project’s structure and technologies.

Steps to Configure Your GEMINI.md File

Step 1: Generate the GEMINI.md File Automatically

If you have an existing project with files already written, the Gemini CLI can help you create the initial `GEMINI.md` file by analyzing your current codebase. This process helps the AI understand your project’s framework, libraries, structure, and data usage.

1. Navigate to the chat interface within your Gemini CLI session.
2. Type the command /init and press Enter. This special command instructs Gemini to scan your project and generate the `GEMINI.md` file.

Step 2: Review and Approve File Changes

Upon executing the /init command, the Gemini CLI will first create an empty `gemini.md` file in the root of your project. It will then proceed to analyze your codebase. Once the analysis is complete, instead of immediately writing to the file, Gemini will present a “diff” (a comparison of the proposed changes) in the chat window. It will ask for your permission to write the analyzed content to the `gemini.md` file.

You will typically have three options:

• Allow once: Permits the current write action but will require permission again for future file modifications.
• Always allow: Grants permission for all subsequent file write actions within the current session, meaning Gemini won’t ask for approval again.
• Refuse: Rejects the proposed changes and allows you to suggest modifications or cancel the operation entirely.

For convenience during the session, you can select ‘Always allow’. A message indicating ‘Accepting edits’ will appear above the chat input, confirming that Gemini will now make code changes automatically without further prompts.

Step 3: Understand the Auto-Edit Shortcut

Gemini CLI provides a handy shortcut to toggle the auto-accept feature for file edits on and off.

• Press Shift + Tab to disable automatic acceptance of edits. The ‘Accepting edits’ message will disappear.
• Press Shift + Tab again to re-enable automatic acceptance. The message will reappear.

This shortcut is useful for maintaining control over file modifications as needed.

Step 4: Examine and Edit the GEMINI.md File

After approving the changes, open the newly generated `gemini.md` file in your code editor. You will find sections detailing your project’s overview, prerequisites, installation steps, development server commands, testing procedures, build processes, identified frameworks (e.g., Nuxt 3), testing tools (e.g., Vitest), styling approach (e.g., single CSS file), and component/page directory structures.

Expert Note: The initial content generated by Gemini will be more comprehensive for larger, more complex projects. For smaller projects, the file might be quite brief, as observed in the example which only had two pages and minimal components.

Adding Custom Preferences:

You can enhance the `GEMINI.md` file by adding your personal coding preferences. This ensures the AI adheres to your specific style guidelines.

1. Scroll to the bottom of the `GEMINI.md` file.
2. Add your preferences in a clear, descriptive format. Examples include:
   • JavaScript/TypeScript Semicolons: “Do not use semicolons for JavaScript and TypeScript code.”
   • Tailwind CSS Usage: “Do not use Tailwind classes directly in component templates. Prefer using custom classes in the main CSS file and applying Tailwind utility classes there if needed.”
   • Dependency Management: “Keep project dependencies minimal.”
   • Import Style: “Use relative imports instead of path aliases.”
3. Save the `GEMINI.md` file after adding your customizations.

Step 5: Refresh Gemini’s Memory

For the Gemini CLI to recognize and utilize the updated or newly created `GEMINI.md` file, you need to refresh its memory.

1. In the Gemini CLI chat, type the command /memory refresh and press Enter.
2. Wait for a confirmation message indicating that the memory has been refreshed.
3. You should see a confirmation that Gemini is now using the `gemini.md` file (e.g., “It’s using one gemini.md file.”).

This step ensures that the AI has the latest context about your project’s configuration and preferences.

Step 6: Understanding Scope of GEMINI.md Files

The `GEMINI.md` file can be configured at different levels to provide context-specific instructions:

• Project-Level: The `GEMINI.md` file in the root directory applies to the entire project. This is the primary file for global project settings.
• Subdirectory-Level: You can create `GEMINI.md` files within subdirectories (e.g., in a pages/ or tests/ folder). These files provide instructions specific to the files within that particular directory and its children.
• Global-Level: For instructions that should apply across all projects, you can create a global `GEMINI.md` file. This file is located in a hidden .gemini folder within your home directory (on macOS) or user profile directory (on Windows). You may need to enable viewing hidden files to locate it. This global file is ideal for universal coding styles, personal interaction preferences with the AI, or other cross-project settings.

Important: After creating or modifying any `GEMINI.md` file (project, subdirectory, or global), always run /memory refresh to ensure the CLI re-scans and incorporates the changes.

Step 7: Maintain Your GEMINI.md File

The `GEMINI.md` file is not a one-time setup. As your project evolves, incorporates new libraries, changes its architecture, or adopts new coding styles, you should continuously update this file.

• Regularly review your `GEMINI.md` file to ensure it accurately reflects the current state of your project.
• Add or modify instructions to align with new dependencies, services, or stylistic choices.
• An outdated `GEMINI.md` file can lead to the AI using stale information, resulting in code that does not match your project’s current standards.

For new projects, you can start with a basic `GEMINI.md` file containing your core preferences and update it iteratively as you build out the application.

With your `GEMINI.md` file properly configured, the Gemini CLI is now equipped with the necessary context to assist you effectively in making code changes and generating new code that aligns with your project’s specific requirements and your personal coding style.

Source: Gemini CLI Tutorial #2 – The GEMINI.md File (YouTube)