gh-lucklyric-cc-dev-tools-plugins-gemini/skills/gemini/references/session-workflows.md

Gemini CLI Session Workflows

Purpose: Guide for session management and multi-turn conversations Version: v0.16.0+ Last Updated: 2025-11-18

Note: Session management features documented here are available in Gemini CLI v0.16.0+ but may not be directly accessible through Claude Code's headless integration. See limitations section below.

Overview

Gemini CLI supports session persistence for multi-turn conversations, allowing you to resume previous interactions and build on context across multiple invocations.

Session Basics

What is a Session?

A session is a conversation thread with Gemini that:

• Maintains conversation history
• Preserves context across turns
• Can be resumed later
• Is stored locally in ~/.gemini/

Session Lifecycle

Create → Use → Pause → Resume → Complete → Archive/Delete

Session Management Commands

List Available Sessions

gemini --list-sessions

Example Output:

Available sessions:
 0: "test non-interactive mode" (5 minutes ago)
 1: "architecture design discussion" (1 hour ago)
 2: "code review session" (yesterday)

Resume a Session

# Resume most recent session
gemini -r latest

# Resume specific session by index
gemini -r 0
gemini -r 1
gemini -r 2

# Resume and add new prompt
gemini -r latest "Continue our discussion about microservices"

Delete a Session

# Delete session by index
gemini --delete-session 0

# Delete after listing
gemini --list-sessions
gemini --delete-session 2

Session Workflows

Workflow 1: Iterative Development

Scenario: Building a feature across multiple sessions

# Session 1: Initial design
gemini -m gemini-3-pro-preview "Design a user authentication system"
# ... conversation happens ...

# Later: Resume to implement
gemini -r latest "Now help me implement the login component"

# Even later: Review and refine
gemini -r latest "Review the implementation for security issues"

Workflow 2: Research Continuation

Scenario: Deep research across multiple timeframes

# Day 1: Start research
gemini -m gemini-3-pro-preview -e web_search "Research GraphQL best practices"

# Day 2: Continue research
gemini -r latest "Now compare GraphQL with REST for our use case"

# Day 3: Make decision
gemini -r latest "Based on our research, recommend the best approach"

Workflow 3: Code Review Marathon

Scenario: Reviewing multiple files in sequence

# Start with first file
gemini -m gemini-2.5-pro "Review this authentication module"

# Resume for next file (context preserved)
gemini -r latest "Now review the authorization module"

# Continue pattern
gemini -r latest "Review the session management module"

Workflow 4: Collaborative Debugging

Scenario: Debugging complex issues over time

# Initial investigation
gemini -m gemini-2.5-pro "Help debug this memory leak"

# After implementing first fix
gemini -r latest "The leak still occurs. Here's the new log output..."

# Final resolution
gemini -r latest "Confirmed fixed! Summarize what we found"

Best Practices

When to Use Sessions

✅ Good Use Cases:

• Complex multi-step tasks
• Iterative design and implementation
• Long-running research projects
• Code review across multiple files
• Debugging sessions spanning multiple attempts

❌ Poor Use Cases:

• Quick one-off queries
• Unrelated tasks
• Simple factual questions
• When context doesn't matter

Session Management Tips

1. Name Sessions Meaningfully: Use descriptive names for easy identification
2. Clean Up Regularly: Delete completed sessions to reduce clutter
3. Use Latest Wisely: gemini -r latest is convenient but verify you're resuming the right session
4. Context Limits: Very long sessions may hit context window limits
5. Explicit Resume: When in doubt, use numeric index rather than latest

Session Organization

# Pattern: One session per feature/task
# Session 0: "auth-implementation"
# Session 1: "payment-integration"
# Session 2: "performance-optimization"

# Check which session you need
gemini --list-sessions

# Resume the right one
gemini -r 1  # payment-integration

Session Storage

Location

Sessions are stored in:

~/.gemini/
├── sessions/
│   ├── session-0.json
│   ├── session-1.json
│   └── session-2.json
└── settings.json

Privacy & Security

• Sessions stored locally only
• No automatic cloud sync
• Contains conversation history
• May include sensitive code/data
• Should be included in .gitignore

Interactive vs Non-Interactive Sessions

Interactive Mode

# Start interactive session
gemini

# Session automatically created
# Type /chat save mytag to save with tag
# Type /chat resume mytag to resume later

Non-Interactive Mode (Headless)

# Sessions work with -r flag
gemini -r latest "New prompt here"

# But creating NEW sessions requires prompt-interactive
gemini -i "Start session with this prompt"

Limitations in Claude Code Integration

⚠️ Important: Claude Code's bash environment is non-interactive/headless, which means:

1. No Interactive Session Commands: Commands like /chat save and /chat resume don't work in headless mode
2. Resume Flag May Work: The -r flag SHOULD work for resuming, but hasn't been tested in headless context
3. Session Creation: New sessions created automatically on first invocation
4. Session Persistence: Sessions persist across Claude Code skill invocations if using same working directory

Workaround for Claude Code

Since full session management may not be available in headless mode, consider:

• Using one-shot queries for each invocation
• Maintaining conversation context at the plugin level (if needed)
• Documenting session management as manual user workflow outside Claude Code

Advanced Patterns

Session Branching

# Main session
gemini -r 0 "Implement approach A"

# Try alternative without affecting main session
gemini "Try approach B instead"  # New session

# Return to main session
gemini -r 0 "Continue with approach A"

Session Cleanup Script

#!/bin/bash
# cleanup-old-sessions.sh

# List sessions
gemini --list-sessions

# Delete sessions older than 7 days (manual inspection required)
# No automated deletion to prevent data loss

Troubleshooting

Session Not Found

$ gemini -r 5
Error: Session 5 not found

# Solution: List sessions first
$ gemini --list-sessions
# Use valid index

Lost Session Context

# If session seems to have lost context:
# 1. Verify you're resuming correct session
gemini --list-sessions

# 2. Resume with summary prompt
gemini -r 2 "Summarize what we discussed so far"

# 3. If context truly lost, start fresh
gemini "Let's restart our discussion about..."

Session Conflicts

# If multiple sessions seem to interfere:
# 1. Check current sessions
gemini --list-sessions

# 2. Delete unused sessions
gemini --delete-session 1
gemini --delete-session 3

# 3. Start fresh with clear naming
gemini "New session: payment gateway integration"

See Also

• gemini-help.md - Full CLI reference
• command-patterns.md - Common command templates
• model-selection.md - Model selection guidance