docs/core/index.md

# Gemini CLI Core

Gemini CLI's core package (`packages/core`) is the backend portion of Gemini CLI, handling communication with the Gemini API, managing tools, and processing requests sent from `packages/cli`. For a general overview of Gemini CLI, see the [main documentation page](../index.md).

## Navigating this section

- **[Core tools API](./tools-api.md):** Information on how tools are defined, registered, and used by the core.
- **[Memory Import Processor](./memport.md):** Documentation for the modular GEMINI.md import feature using @file.md syntax.

## Role of the core

While the `packages/cli` portion of Gemini CLI provides the user interface, `packages/core` is responsible for:

- **Gemini API interaction:** Securely communicating with the Google Gemini API, sending user prompts, and receiving model responses.
- **Prompt engineering:** Constructing effective prompts for the Gemini model, potentially incorporating conversation history, tool definitions, and instructional context from `GEMINI.md` files.
- **Tool management & orchestration:**
  - Registering available tools (e.g., file system tools, shell command execution).
  - Interpreting tool use requests from the Gemini model.
  - Executing the requested tools with the provided arguments.
  - Returning tool execution results to the Gemini model for further processing.
- **Session and state management:** Keeping track of the conversation state, including history and any relevant context required for coherent interactions.
- **Configuration:** Managing core-specific configurations, such as API key access, model selection, and tool settings.

## Security considerations

The core plays a vital role in security:

- **API key management:** It handles the `GEMINI_API_KEY` and ensures it's used securely when communicating with the Gemini API.
- **Tool execution:** When tools interact with the local system (e.g., `run_shell_command`), the core (and its underlying tool implementations) must do so with appropriate caution, often involving sandboxing mechanisms to prevent unintended modifications.

## Chat history compression

To ensure that long conversations don't exceed the token limits of the Gemini model, the core includes a chat history compression feature.

When a conversation approaches the token limit for the configured model, the core automatically compresses the conversation history before sending it to the model. This compression is designed to be lossless in terms of the information conveyed, but it reduces the overall number of tokens used.

You can find the token limits for each model in the [Google AI documentation](https://ai.google.dev/gemini-api/docs/models).

## Model fallback

Gemini CLI includes a model fallback mechanism to ensure that you can continue to use the CLI even if the default "pro" model is rate-limited.

If you are using the default "pro" model and the CLI detects that you are being rate-limited, it automatically switches to the "flash" model for the current session. This allows you to continue working without interruption.

## File discovery service

The file discovery service is responsible for finding files in the project that are relevant to the current context. It is used by the `@` command and other tools that need to access files.

## Memory discovery service

The memory discovery service is responsible for finding and loading the `GEMINI.md` files that provide context to the model. It searches for these files in a hierarchical manner, starting from the current working directory and moving up to the project root and the user's home directory. It also searches in subdirectories.

This allows you to have global, project-level, and component-level context files, which are all combined to provide the model with the most relevant information.

You can use the [`/memory` command](../cli/commands.md) to `show`, `add`, and `refresh` the content of loaded `GEMINI.md` files.

## Citations

When Gemini finds it is reciting text from a source it appends the citation to the output. It is enabled by default but can be disabled with the ui.showCitations setting.

- When proposing an edit the citations display before giving the user the option to accept.
- Citations are always shown at the end of the model’s turn.
- We deduplicate citations and display them in alphabetical order.
-												Rename server->core (#638)


											
										
										
											2025-05-30 18:25:47 -07:00
+								# Gemini CLI Core
-												Docs: Add initial project documentation structure and content (#368)

Co-authored-by: Taylor Mullen <ntaylormullen@google.com>
											
										
										
											2025-05-15 20:04:33 -07:00
-												Edit pass of docs/core/index.md (#1338)

Make a pass through the docs/core/index.md file to hopefully improve readability and consistency.

Of particular note, I've cut out a big chunk that felt mostly like implementation details that aren't particularly relevant for public consumption, and I cut out a discussion of cli/core interconnection that is covered better higher up in the docs hierarchy
											
										
										
											2025-06-23 14:07:03 -07:00
+								Gemini CLI's core package (`packages/core`) is the backend portion of Gemini CLI, handling communication with the Gemini API, managing tools, and processing requests sent from `packages/cli`. For a general overview of Gemini CLI, see the [main documentation page](../index.md).
-												docs: update and reorganize documentation (#806)


											
										
										
											2025-06-07 10:47:30 -07:00
-												Edit pass of docs/core/index.md (#1338)

Make a pass through the docs/core/index.md file to hopefully improve readability and consistency.

Of particular note, I've cut out a big chunk that felt mostly like implementation details that aren't particularly relevant for public consumption, and I cut out a discussion of cli/core interconnection that is covered better higher up in the docs hierarchy
											
										
										
											2025-06-23 14:07:03 -07:00
+								## Navigating this section
-												docs: update and reorganize documentation (#806)


											
										
										
											2025-06-07 10:47:30 -07:00
-												Edit pass of docs/core/index.md (#1338)

Make a pass through the docs/core/index.md file to hopefully improve readability and consistency.

Of particular note, I've cut out a big chunk that felt mostly like implementation details that aren't particularly relevant for public consumption, and I cut out a discussion of cli/core interconnection that is covered better higher up in the docs hierarchy
											
										
										
											2025-06-23 14:07:03 -07:00
+								- **[Core tools API](./tools-api.md):** Information on how tools are defined, registered, and used by the core.
-												feat: modular GEMINI.md imports with @file.md syntax (#1585) (#2230)


											
										
										
											2025-06-30 04:21:47 +05:30
+								- **[Memory Import Processor](./memport.md):** Documentation for the modular GEMINI.md import feature using @file.md syntax.
-												Docs: Add initial project documentation structure and content (#368)

Co-authored-by: Taylor Mullen <ntaylormullen@google.com>
											
										
										
											2025-05-15 20:04:33 -07:00
-												Edit pass of docs/core/index.md (#1338)

Make a pass through the docs/core/index.md file to hopefully improve readability and consistency.

Of particular note, I've cut out a big chunk that felt mostly like implementation details that aren't particularly relevant for public consumption, and I cut out a discussion of cli/core interconnection that is covered better higher up in the docs hierarchy
											
										
										
											2025-06-23 14:07:03 -07:00
+								## Role of the core
-												Docs: Add initial project documentation structure and content (#368)

Co-authored-by: Taylor Mullen <ntaylormullen@google.com>
											
										
										
											2025-05-15 20:04:33 -07:00
-												Edit pass of docs/core/index.md (#1338)

Make a pass through the docs/core/index.md file to hopefully improve readability and consistency.

Of particular note, I've cut out a big chunk that felt mostly like implementation details that aren't particularly relevant for public consumption, and I cut out a discussion of cli/core interconnection that is covered better higher up in the docs hierarchy
											
										
										
											2025-06-23 14:07:03 -07:00
+								While the `packages/cli` portion of Gemini CLI provides the user interface, `packages/core` is responsible for:
-												Docs: Add initial project documentation structure and content (#368)

Co-authored-by: Taylor Mullen <ntaylormullen@google.com>
											
										
										
											2025-05-15 20:04:33 -07:00
-												Edit pass of docs/core/index.md (#1338)

Make a pass through the docs/core/index.md file to hopefully improve readability and consistency.

Of particular note, I've cut out a big chunk that felt mostly like implementation details that aren't particularly relevant for public consumption, and I cut out a discussion of cli/core interconnection that is covered better higher up in the docs hierarchy
											
										
										
											2025-06-23 14:07:03 -07:00
+								- **Gemini API interaction:** Securely communicating with the Google Gemini API, sending user prompts, and receiving model responses.
 								- **Prompt engineering:** Constructing effective prompts for the Gemini model, potentially incorporating conversation history, tool definitions, and instructional context from `GEMINI.md` files.
 								- **Tool management & orchestration:**
-												Docs: Add initial project documentation structure and content (#368)

Co-authored-by: Taylor Mullen <ntaylormullen@google.com>
											
										
										
											2025-05-15 20:04:33 -07:00
+								  - Registering available tools (e.g., file system tools, shell command execution).
 								  - Interpreting tool use requests from the Gemini model.
 								  - Executing the requested tools with the provided arguments.
 								  - Returning tool execution results to the Gemini model for further processing.
-												Edit pass of docs/core/index.md (#1338)

Make a pass through the docs/core/index.md file to hopefully improve readability and consistency.

Of particular note, I've cut out a big chunk that felt mostly like implementation details that aren't particularly relevant for public consumption, and I cut out a discussion of cli/core interconnection that is covered better higher up in the docs hierarchy
											
										
										
											2025-06-23 14:07:03 -07:00
+								- **Session and state management:** Keeping track of the conversation state, including history and any relevant context required for coherent interactions.
-												Rename server->core (#638)


											
										
										
											2025-05-30 18:25:47 -07:00
+								- **Configuration:** Managing core-specific configurations, such as API key access, model selection, and tool settings.
-												Docs: Add initial project documentation structure and content (#368)

Co-authored-by: Taylor Mullen <ntaylormullen@google.com>
											
										
										
											2025-05-15 20:04:33 -07:00
-												Edit pass of docs/core/index.md (#1338)

Make a pass through the docs/core/index.md file to hopefully improve readability and consistency.

Of particular note, I've cut out a big chunk that felt mostly like implementation details that aren't particularly relevant for public consumption, and I cut out a discussion of cli/core interconnection that is covered better higher up in the docs hierarchy
											
										
										
											2025-06-23 14:07:03 -07:00
+								## Security considerations
-												Docs: Add initial project documentation structure and content (#368)

Co-authored-by: Taylor Mullen <ntaylormullen@google.com>
											
										
										
											2025-05-15 20:04:33 -07:00
-												Rename server->core (#638)


											
										
										
											2025-05-30 18:25:47 -07:00
+								The core plays a vital role in security:
-												Docs: Add initial project documentation structure and content (#368)

Co-authored-by: Taylor Mullen <ntaylormullen@google.com>
											
										
										
											2025-05-15 20:04:33 -07:00
-												Edit pass of docs/core/index.md (#1338)

Make a pass through the docs/core/index.md file to hopefully improve readability and consistency.

Of particular note, I've cut out a big chunk that felt mostly like implementation details that aren't particularly relevant for public consumption, and I cut out a discussion of cli/core interconnection that is covered better higher up in the docs hierarchy
											
										
										
											2025-06-23 14:07:03 -07:00
+								- **API key management:** It handles the `GEMINI_API_KEY` and ensures it's used securely when communicating with the Gemini API.
 								- **Tool execution:** When tools interact with the local system (e.g., `run_shell_command`), the core (and its underlying tool implementations) must do so with appropriate caution, often involving sandboxing mechanisms to prevent unintended modifications.
-												Docs: Add initial project documentation structure and content (#368)

Co-authored-by: Taylor Mullen <ntaylormullen@google.com>
											
										
										
											2025-05-15 20:04:33 -07:00
-												Edit pass of docs/core/index.md (#1338)

Make a pass through the docs/core/index.md file to hopefully improve readability and consistency.

Of particular note, I've cut out a big chunk that felt mostly like implementation details that aren't particularly relevant for public consumption, and I cut out a discussion of cli/core interconnection that is covered better higher up in the docs hierarchy
											
										
										
											2025-06-23 14:07:03 -07:00
+								## Chat history compression
-												Docs: Add initial project documentation structure and content (#368)

Co-authored-by: Taylor Mullen <ntaylormullen@google.com>
											
										
										
											2025-05-15 20:04:33 -07:00
-												Edit pass of docs/core/index.md (#1338)

Make a pass through the docs/core/index.md file to hopefully improve readability and consistency.

Of particular note, I've cut out a big chunk that felt mostly like implementation details that aren't particularly relevant for public consumption, and I cut out a discussion of cli/core interconnection that is covered better higher up in the docs hierarchy
											
										
										
											2025-06-23 14:07:03 -07:00
+								To ensure that long conversations don't exceed the token limits of the Gemini model, the core includes a chat history compression feature.
-												docs: update and reorganize documentation (#806)


											
										
										
											2025-06-07 10:47:30 -07:00
-												Edit pass of docs/core/index.md (#1338)

Make a pass through the docs/core/index.md file to hopefully improve readability and consistency.

Of particular note, I've cut out a big chunk that felt mostly like implementation details that aren't particularly relevant for public consumption, and I cut out a discussion of cli/core interconnection that is covered better higher up in the docs hierarchy
											
										
										
											2025-06-23 14:07:03 -07:00
+								When a conversation approaches the token limit for the configured model, the core automatically compresses the conversation history before sending it to the model. This compression is designed to be lossless in terms of the information conveyed, but it reduces the overall number of tokens used.
-												docs: update and reorganize documentation (#806)


											
										
										
											2025-06-07 10:47:30 -07:00
 								You can find the token limits for each model in the [Google AI documentation](https://ai.google.dev/gemini-api/docs/models).
-												Edit pass of docs/core/index.md (#1338)

Make a pass through the docs/core/index.md file to hopefully improve readability and consistency.

Of particular note, I've cut out a big chunk that felt mostly like implementation details that aren't particularly relevant for public consumption, and I cut out a discussion of cli/core interconnection that is covered better higher up in the docs hierarchy
											
										
										
											2025-06-23 14:07:03 -07:00
+								## Model fallback
-												docs: update and reorganize documentation (#806)


											
										
										
											2025-06-07 10:47:30 -07:00
-												Edit pass of docs/core/index.md (#1338)

Make a pass through the docs/core/index.md file to hopefully improve readability and consistency.

Of particular note, I've cut out a big chunk that felt mostly like implementation details that aren't particularly relevant for public consumption, and I cut out a discussion of cli/core interconnection that is covered better higher up in the docs hierarchy
											
										
										
											2025-06-23 14:07:03 -07:00
+								Gemini CLI includes a model fallback mechanism to ensure that you can continue to use the CLI even if the default "pro" model is rate-limited.
-												docs: update and reorganize documentation (#806)


											
										
										
											2025-06-07 10:47:30 -07:00
-												Edit pass of docs/core/index.md (#1338)

Make a pass through the docs/core/index.md file to hopefully improve readability and consistency.

Of particular note, I've cut out a big chunk that felt mostly like implementation details that aren't particularly relevant for public consumption, and I cut out a discussion of cli/core interconnection that is covered better higher up in the docs hierarchy
											
										
										
											2025-06-23 14:07:03 -07:00
+								If you are using the default "pro" model and the CLI detects that you are being rate-limited, it automatically switches to the "flash" model for the current session. This allows you to continue working without interruption.
-												docs: update and reorganize documentation (#806)


											
										
										
											2025-06-07 10:47:30 -07:00
-												Edit pass of docs/core/index.md (#1338)

Make a pass through the docs/core/index.md file to hopefully improve readability and consistency.

Of particular note, I've cut out a big chunk that felt mostly like implementation details that aren't particularly relevant for public consumption, and I cut out a discussion of cli/core interconnection that is covered better higher up in the docs hierarchy
											
										
										
											2025-06-23 14:07:03 -07:00
+								## File discovery service
-												docs: update and reorganize documentation (#806)


											
										
										
											2025-06-07 10:47:30 -07:00
 								The file discovery service is responsible for finding files in the project that are relevant to the current context. It is used by the `@` command and other tools that need to access files.
-												Edit pass of docs/core/index.md (#1338)

Make a pass through the docs/core/index.md file to hopefully improve readability and consistency.

Of particular note, I've cut out a big chunk that felt mostly like implementation details that aren't particularly relevant for public consumption, and I cut out a discussion of cli/core interconnection that is covered better higher up in the docs hierarchy
											
										
										
											2025-06-23 14:07:03 -07:00
+								## Memory discovery service
-												docs: update and reorganize documentation (#806)


											
										
										
											2025-06-07 10:47:30 -07:00
 								The memory discovery service is responsible for finding and loading the `GEMINI.md` files that provide context to the model. It searches for these files in a hierarchical manner, starting from the current working directory and moving up to the project root and the user's home directory. It also searches in subdirectories.
 								This allows you to have global, project-level, and component-level context files, which are all combined to provide the model with the most relevant information.
-												Docs: Add initial project documentation structure and content (#368)

Co-authored-by: Taylor Mullen <ntaylormullen@google.com>
											
										
										
											2025-05-15 20:04:33 -07:00
-												Edit pass of docs/core/index.md (#1338)

Make a pass through the docs/core/index.md file to hopefully improve readability and consistency.

Of particular note, I've cut out a big chunk that felt mostly like implementation details that aren't particularly relevant for public consumption, and I cut out a discussion of cli/core interconnection that is covered better higher up in the docs hierarchy
											
										
										
											2025-06-23 14:07:03 -07:00
+								You can use the [`/memory` command](../cli/commands.md) to `show`, `add`, and `refresh` the content of loaded `GEMINI.md` files.
-												citations documentation (#10742)


											
										
										
											2025-10-08 14:00:44 -07:00
 								## Citations
 								When Gemini finds it is reciting text from a source it appends the citation to the output. It is enabled by default but can be disabled with the ui.showCitations setting.
 								- When proposing an edit the citations display before giving the user the option to accept.
 								- Citations are always shown at the end of the model’s turn.
 								- We deduplicate citations and display them in alphabetical order.