chore: import upstream snapshot with attribution
This commit is contained in:
wehub-resource-sync
@@ -0,0 +1,215 @@
|
||||
# Session management
|
||||
|
||||
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
|
||||
|
||||
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 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 switches to that project's session history.
|
||||
|
||||
## Resuming sessions
|
||||
|
||||
You can resume a previous session to continue the conversation with all prior
|
||||
context restored. Resuming is supported both through command-line flags and an
|
||||
interactive browser.
|
||||
|
||||
### From the command line
|
||||
|
||||
When starting Gemini CLI, use the `--resume` (or `-r`) flag to load existing
|
||||
sessions.
|
||||
|
||||
- **Resume latest:**
|
||||
|
||||
```bash
|
||||
gemini --resume
|
||||
```
|
||||
|
||||
This immediately loads the most recent session.
|
||||
|
||||
- **Resume by index:** List available sessions first (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, use the `/resume` slash command to open the **Session
|
||||
Browser**:
|
||||
|
||||
```text
|
||||
/resume
|
||||
```
|
||||
|
||||
When typing `/resume` (or `/chat`) in slash completion, commands are grouped
|
||||
under titled separators:
|
||||
|
||||
- `-- auto --` (session browser)
|
||||
- `list` is selectable and opens the session browser
|
||||
- `-- checkpoints --` (manual tagged checkpoint commands)
|
||||
|
||||
Unique prefixes such as `/resum` and `/cha` resolve to the same grouped menu.
|
||||
|
||||
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.
|
||||
- **Esc:** Press **Esc** to exit the Session Browser.
|
||||
|
||||
### Manual chat checkpoints
|
||||
|
||||
For named branch points inside a session, use chat checkpoints:
|
||||
|
||||
```text
|
||||
/resume save decision-point
|
||||
/resume list
|
||||
/resume resume decision-point
|
||||
```
|
||||
|
||||
Compatibility aliases:
|
||||
|
||||
- `/chat ...` works for the same commands.
|
||||
- `/resume checkpoints ...` also remains supported during migration.
|
||||
|
||||
## Parallel sessions with Git worktrees
|
||||
|
||||
When working on multiple tasks at once, you can use
|
||||
[Git worktrees](./git-worktrees.md) to give each Gemini session its own copy of
|
||||
the codebase. This prevents changes in one session from colliding with another.
|
||||
|
||||
## Managing 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, use the `--list-sessions` flag:
|
||||
|
||||
```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. These settings let you control retention policies and
|
||||
session lengths.
|
||||
|
||||
### Session retention
|
||||
|
||||
By default, Gemini CLI automatically cleans up old session data to prevent your
|
||||
history from growing indefinitely. When a session is deleted, Gemini CLI also
|
||||
removes all associated data, including implementation plans, task trackers, tool
|
||||
outputs, and activity logs.
|
||||
|
||||
The default policy is to **retain sessions for 30 days**.
|
||||
|
||||
#### Configuration
|
||||
|
||||
You can customize these policies using the `/settings` command or by manually
|
||||
editing your `settings.json` file:
|
||||
|
||||
```json
|
||||
{
|
||||
"general": {
|
||||
"sessionRetention": {
|
||||
"enabled": true,
|
||||
"maxAge": "30d",
|
||||
"maxCount": 50
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
- **`enabled`**: (boolean) Master switch for session cleanup. Defaults to
|
||||
`true`.
|
||||
- **`maxAge`**: (string) Duration to keep sessions (for example, "24h", "7d",
|
||||
"4w"). Sessions older than this are deleted. Defaults to `"30d"`.
|
||||
- **`maxCount`**: (number) Maximum number of sessions to retain. The oldest
|
||||
sessions exceeding this count are deleted. Defaults to undefined (unlimited).
|
||||
- **`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 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 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
|
||||
sending requests to the model. You must manually start a new session.
|
||||
- **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.
|
||||
Reference in New Issue
Block a user