diff --git a/docs/cli/commands.md b/docs/cli/commands.md index c5ba8a6d82..947f9ad2da 100644 --- a/docs/cli/commands.md +++ b/docs/cli/commands.md @@ -164,6 +164,21 @@ Slash commands provide meta-level control over the CLI itself. - **Note:** Only available if checkpointing is configured via [settings](../get-started/configuration.md). See [Checkpointing documentation](../cli/checkpointing.md) for more details. +- **`/resume`** + - **Description:** Browse and resume previous conversation sessions. Opens an + interactive session browser where you can search, filter, and select from + automatically saved conversations. + - **Features:** + - **Session Browser:** Interactive interface showing all saved sessions with + timestamps, message counts, and first user message for context + - **Search:** Use `/` to search through conversation content across all + sessions + - **Sorting:** Sort sessions by date or message count + - **Management:** Delete unwanted sessions directly from the browser + - **Resume:** Select any session to resume and continue the conversation + - **Note:** All conversations are automatically saved as you chat - no manual + saving required. See [Session Management](../cli/session-management.md) for + complete details. - [**`/settings`**](./settings.md) - **Description:** Open the settings editor to view and modify Gemini CLI diff --git a/docs/cli/session-management.md b/docs/cli/session-management.md new file mode 100644 index 0000000000..b7d76549ae --- /dev/null +++ b/docs/cli/session-management.md @@ -0,0 +1,158 @@ +# 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. + +## Automatic Saving + +Every time you interact with Gemini CLI, your session is automatically saved. +This happens in the background without any manual intervention. + +- **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//chats/`. +- **Scope:** Sessions are project-specific. Switching directories to a different + project will switch to that project's session history. + +## Resuming Sessions + +You can resume a previous session to continue the conversation with all prior +context restored. + +### From the Command Line + +When starting the CLI, you can use the `--resume` (or `-r`) flag: + +- **Resume latest:** + + ```bash + gemini --resume + ``` + + This immediately loads the most recent session. + +- **Resume by index:** First, list available sessions (see + [Listing Sessions](#listing-sessions)), then use the index number: + + ```bash + gemini --resume 1 + ``` + +- **Resume by ID:** You can also provide the full session UUID: + ```bash + gemini --resume a1b2c3d4-e5f6-7890-abcd-ef1234567890 + ``` + +### From the Interactive Interface + +While the CLI is running, you can use the `/resume` slash command to open the +**Session Browser**: + +```text +/resume +``` + +This opens an interactive interface where you can: + +- **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. + +## Managing Sessions + +### Listing Sessions + +To see a list of all available sessions for the current project from the command +line: + +```bash +gemini --list-sessions +``` + +Output example: + +```text +Available sessions for this project (3): + + 1. Fix bug in auth (2 days ago) [a1b2c3d4] + 2. Refactor database schema (5 hours ago) [e5f67890] + 3. Update documentation (Just now) [abcd1234] +``` + +### 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: + +```bash +gemini --delete-session 2 +``` + +**From the Session Browser:** + +1. Open the browser with `/resume`. +2. Navigate to the session you want to remove. +3. Press `x`. + +## Configuration + +You can configure how Gemini CLI manages your session history in your +`settings.json` file. + +### Session Retention + +To prevent your history from growing indefinitely, you can enable automatic +cleanup policies. + +```json +{ + "general": { + "sessionRetention": { + "enabled": true, + "maxAge": "30d", // Keep sessions for 30 days + "maxCount": 50 // Keep the 50 most recent sessions + } + } +} +``` + +- **`enabled`**: (boolean) Master switch for session cleanup. Default is + `false`. +- **`maxAge`**: (string) Duration to keep sessions (e.g., "24h", "7d", "4w"). + Sessions older than this will be deleted. +- **`maxCount`**: (number) Maximum number of sessions to retain. The oldest + sessions exceeding this count will be deleted. +- **`minRetention`**: (string) Minimum retention period (safety limit). Defaults + to `"1d"`; sessions newer than this period are never deleted by automatic + cleanup. + +### Session Limits + +You can also limit the length of individual sessions to prevent context windows +from becoming too large and expensive. + +```json +{ + "model": { + "maxSessionTurns": 100 + } +} +``` + +- **`maxSessionTurns`**: (number) The maximum number of turns (user + 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 + sending requests to the model. You must manually start a new session. + - **Non-Interactive Mode:** The CLI exits with an error. diff --git a/docs/get-started/configuration.md b/docs/get-started/configuration.md index 0335f2b889..7a1ad4475b 100644 --- a/docs/get-started/configuration.md +++ b/docs/get-started/configuration.md @@ -882,7 +882,12 @@ of v0.3.0: { "general": { "vimMode": true, - "preferredEditor": "code" + "preferredEditor": "code", + "sessionRetention": { + "enabled": true, + "maxAge": "30d", + "maxCount": 100 + } }, "ui": { "theme": "GitHub", @@ -1118,6 +1123,24 @@ for that specific session. - Example: `gemini -e my-extension -e my-other-extension` - **`--list-extensions`** (**`-l`**): - Lists all available extensions and exits. +- **`--resume [session_id]`** (**`-r [session_id]`**): + - Resume a previous chat session. Use "latest" for the most recent session, + provide a session index number, or provide a full session UUID. + - If no session_id is provided, defaults to "latest". + - Example: `gemini --resume 5` or `gemini --resume latest` or + `gemini --resume a1b2c3d4-e5f6-7890-abcd-ef1234567890` or `gemini --resume` + - See [Session Management](../cli/session-management.md) for more details. +- **`--list-sessions`**: + - List all available chat sessions for the current project and exit. + - Shows session indices, dates, message counts, and preview of first user + message. + - Example: `gemini --list-sessions` +- **`--delete-session `**: + - Delete a specific chat session by its index number or full session UUID. + - Use `--list-sessions` first to see available sessions, their indices, and + UUIDs. + - Example: `gemini --delete-session 3` or + `gemini --delete-session a1b2c3d4-e5f6-7890-abcd-ef1234567890` - **`--include-directories `**: - Includes additional directories in the workspace for multi-directory support. diff --git a/docs/sidebar.json b/docs/sidebar.json index 1a93aacf54..cccdb0cefc 100644 --- a/docs/sidebar.json +++ b/docs/sidebar.json @@ -84,6 +84,10 @@ "label": "Sandbox", "slug": "docs/cli/sandbox" }, + { + "label": "Session Management", + "slug": "docs/cli/session-management" + }, { "label": "Settings", "slug": "docs/cli/settings"