MediaMetz/gemini-cli
1
0
Fork 0
mirror of https://github.com/google-gemini/gemini-cli.git synced 2026-03-10 14:10:37 -07:00
Code Issues Packages Projects Releases Wiki Activity

Docs: Refresh docs to organize and standardize reference materials. (#18403)

Browse Source
This commit is contained in:
Jenna Inouye
2026-02-13 14:09:17 -08:00
committed by GitHub
parent f76e24c00f
commit c7237f0c79
37 changed files with 2343 additions and 1676 deletions
Download Patch File Download Diff File Expand all files Collapse all files

105
docs/cli/session-management.md
View File

@@ -1,32 +1,36 @@
# Session Management
# Session management
Gemini CLI includes robust session management features that automatically save
your conversation history. This allows you to interrupt your work and resume
exactly where you left off, review past interactions, and manage your
conversation history effectively.
Session management saves your conversation history so you can resume your work
where you left off. Use these features to review past interactions, manage
history across different projects, and configure how long data is retained.
## Automatic Saving
## Automatic saving
Every time you interact with Gemini CLI, your session is automatically saved.
This happens in the background without any manual intervention.
Your session history is recorded automatically as you interact with the model.
This background process ensures your work is preserved even if you interrupt a
session.
- **What is saved:** The complete conversation history, including:
- Your prompts and the model's responses.
- All tool executions (inputs and outputs).
- Token usage statistics (input/output/cached, etc.).
- Assistant thoughts/reasoning summaries (when available).
- **Location:** Sessions are stored in `~/.gemini/tmp/<project_hash>/chats/`.
- Token usage statistics (input, output, cached, etc.).
- Assistant thoughts and reasoning summaries (when available).
- **Location:** Sessions are stored in `~/.gemini/tmp/<project_hash>/chats/`,
where `<project_hash>` is a unique identifier based on your project's root
directory.
- **Scope:** Sessions are project-specific. Switching directories to a different
project will switch to that project's session history.
project switches to that project's session history.
## Resuming Sessions
## Resuming sessions
You can resume a previous session to continue the conversation with all prior
context restored.
context restored. Resuming is supported both through command-line flags and an
interactive browser.
### From the Command Line
### From the command line
When starting the CLI, you can use the `--resume` (or `-r`) flag:
When starting Gemini CLI, use the `--resume` (or `-r`) flag to load existing
sessions.
- **Resume latest:**
@@ -36,8 +40,8 @@ When starting the CLI, you can use the `--resume` (or `-r`) flag:
This immediately loads the most recent session.
- **Resume by index:** First, list available sessions (see
[Listing Sessions](#listing-sessions)), then use the index number:
- **Resume by index:** List available sessions first (see
[Listing sessions](#listing-sessions)), then use the index number:
```bash
gemini --resume 1
@@ -48,30 +52,35 @@ When starting the CLI, you can use the `--resume` (or `-r`) flag:
gemini --resume a1b2c3d4-e5f6-7890-abcd-ef1234567890
```
### From the Interactive Interface
### From the interactive interface
While the CLI is running, you can use the `/resume` slash command to open the
**Session Browser**:
While the CLI is running, use the `/resume` slash command to open the **Session
Browser**:
```text
/resume
```
This opens an interactive interface where you can:
The Session Browser provides an interactive interface where you can perform the
following actions:
- **Browse:** Scroll through a list of your past sessions.
- **Preview:** See details like the session date, message count, and the first
user prompt.
- **Search:** Press `/` to enter search mode, then type to filter sessions by ID
or content.
- **Select:** Press `Enter` to resume the selected session.
- **Select:** Press **Enter** to resume the selected session.
- **Esc:** Press **Esc** to exit the Session Browser.
## Managing Sessions
## Managing sessions
### Listing Sessions
You can list and delete sessions to keep your history organized and manage disk
space.
### Listing sessions
To see a list of all available sessions for the current project from the command
line:
line, use the `--list-sessions` flag:
```bash
gemini --list-sessions
@@ -87,12 +96,12 @@ Available sessions for this project (3):
3. Update documentation (Just now) [abcd1234]
```
### Deleting Sessions
### Deleting sessions
You can remove old or unwanted sessions to free up space or declutter your
history.
**From the Command Line:** Use the `--delete-session` flag with an index or ID:
**From the command line:** Use the `--delete-session` flag with an index or ID:
```bash
gemini --delete-session 2
@@ -102,17 +111,18 @@ gemini --delete-session 2
1. Open the browser with `/resume`.
2. Navigate to the session you want to remove.
3. Press `x`.
3. Press **x**.
## Configuration
You can configure how Gemini CLI manages your session history in your
`settings.json` file.
`settings.json` file. These settings let you control retention policies and
session lengths.
### Session Retention
### Session retention
To prevent your history from growing indefinitely, you can enable automatic
cleanup policies.
To prevent your history from growing indefinitely, enable automatic cleanup
policies in your settings.
```json
{
@@ -126,20 +136,20 @@ cleanup policies.
}
```
- **`enabled`**: (boolean) Master switch for session cleanup. Default is
- **`enabled`**: (boolean) Master switch for session cleanup. Defaults to
`false`.
- **`maxAge`**: (string) Duration to keep sessions (e.g., "24h", "7d", "4w").
Sessions older than this will be deleted.
- **`maxAge`**: (string) Duration to keep sessions (for example, "24h", "7d",
"4w"). Sessions older than this are deleted.
- **`maxCount`**: (number) Maximum number of sessions to retain. The oldest
sessions exceeding this count will be deleted.
sessions exceeding this count are deleted.
- **`minRetention`**: (string) Minimum retention period (safety limit). Defaults
to `"1d"`; sessions newer than this period are never deleted by automatic
to `"1d"`. Sessions newer than this period are never deleted by automatic
cleanup.
### Session Limits
### Session limits
You can also limit the length of individual sessions to prevent context windows
from becoming too large and expensive.
You can limit the length of individual sessions to prevent context windows from
becoming too large and expensive.
```json
{
@@ -149,10 +159,17 @@ from becoming too large and expensive.
}
```
- **`maxSessionTurns`**: (number) The maximum number of turns (user + model
- **`maxSessionTurns`**: (number) The maximum number of turns (user and model
exchanges) allowed in a single session. Set to `-1` for unlimited (default).
**Behavior when limit is reached:**
- **Interactive Mode:** The CLI shows an informational message and stops
- **Interactive mode:** The CLI shows an informational message and stops
sending requests to the model. You must manually start a new session.
- **Non-Interactive Mode:** The CLI exits with an error.
- **Non-interactive mode:** The CLI exits with an error.
## Next steps
- Explore the [Memory tool](../tools/memory.md) to save persistent information
across sessions.
- Learn how to [Checkpoint](./checkpointing.md) your session state.
- Check out the [CLI reference](./cli-reference.md) for all command-line flags.