How Gemini CLI Builds Context and Learns About Your Codebase

When you use the Gemini CLI, how does it actually learn about your code? I dug into its source code to find the answer, and discovered a two-part process: a quick, initial snapshot of your project, followed by a deeper, on-demand investigation using its own tools. Here’s how it works.

The Initial Context Snapshot

When Gemini CLI starts, it gathers a high-level "snapshot" of the local working directory to provide the starting context. This initial context includes:

• Basic Environment: The current operating system, the current working directory, and today's date.
• Directory Structure: It generates a file and folder tree. This gives the model an immediate sense of the project's layout, key files, and overall structure. This doesn't include the file contents, though.

The CLI sends this entire snapshot to the model as the very first message in the chat, but as a user of the Gemini CLI, you won't see it. If you want to explore the entire unfiltered conversation history, use the /chat save command and find the JSON file it stores in .gemini/tmp/[SESSION_HASH]/checkpoint.json

On-Demand Learning with Tools

After the initial snapshot, Gemini CLI relies on its tools to investigate the codebase as needed to answer questions or perform tasks. This is the primary way it learns during a conversation. It's analogous to a developer opening files and searching for code as they work.

This searching for relevant files means it might miss important files. I like to start my chat with a few probing questions to make sure it has read the right files, before getting started with the actual task I want to complete.

Another way to influence how the Gemini CLI finds files and navigates your codebase is through the instructional context you can add to GEMINI.md. Refer to Context Files in the docs to learn more.

The key tools Gemini CLI uses to explore the code include:

• ReadFile and ReadManyFiles: To read the specific contents of one or more files. This is how it understands the actual code, comments, and logic.
• ReadFolder: To list the names of all files and subdirectories directly in a directory.
• SearchText: To search for specific strings or regular expressions within files.
• Shell: To execute shell commands, which can be used to gather information about the codebase, such as the output of git status or npm list.

You can use the command /tools to list all tools available.

Mentioning Files and Directories

A recent feature added to the Gemini CLI is the ability to reference files and directories directly in your prompt using the @ symbol. This is a powerful way to quickly provide context to the model without it having to search for files.

For example, you can ask:

What is the purpose of the @main.py file?

Or, to include a whole directory:

Can you give me a summary of the @src/ directory?

This is now the recommended way to provide file-based context to the model, and the --all-files flag has been removed.

Wrap Up

You now know how Gemini CLI learns about your codebase. On startup, it creates a high-level snapshot of your project's directory structure, but doesn't read the file contents. As you chat with it, it actively uses tools to read files, search for code, and run shell commands to learn about the codebase.

Understanding how this works helps you get better responses.

* * *

More on: Gemini CLI: Google's coding agent for the terminal →