Add ephemeral session mode (--ephemeral)

[kiankyars]

HUMAN WRITTEN:

I made this PR because I use Gemini in headless mode to perform data annotation and labelling, and I don't want it to flood my session logs with many instances of the same agent doing a headless task.

AI WRITTEN:

Summary

Adds a --ephemeral CLI flag for runs where nothing the agent produces for the current process should land under the user's .gemini directory.

Details

The flag now covers, in a single place, every per-run writer that normally targets ~/.gemini/tmp/<project_hash>/:

• Chat history (chats/).
• Conversation checkpoints used by /restore.
• Truncated tool outputs and tool-output masking dumps (tool-outputs/).
• RAG snippet trace logs (logs/rag-trace.log).
• Shell command history (shell_history).
• Plans, tracker, and tasks scratch directories.

Mechanism:

• Storage.setEphemeralTempDir(...) redirects getProjectTempDir() and getHistoryDir() to a per-process directory under the system temp dir (os.tmpdir()/gemini-cli-ephemeral/<unique>/). Because every per-run path is derived from getProjectTempDir(), every existing writer is redirected without touching individual call sites.
• Config activates the redirect when --ephemeral is set and disables automatic checkpointing for that run.
• ChatRecordingService.initialize() returns early in ephemeral mode, so the in-memory cachedConversation is also null (defensive — the storage redirect alone is sufficient).
• parseArguments now rejects --ephemeral combined with --resume, --session-id, or --session-file with a clear error, because there is nothing to persist or resume.
• Settings, authentication credentials, and the global project registry are still read normally.

How to Validate

npm ci
npm run build --workspace @google/gemini-cli-core
npm run build --workspace @google/gemini-cli
npm run typecheck --workspace @google/gemini-cli-core
npm run typecheck --workspace @google/gemini-cli
npx vitest run \
  packages/cli/src/config/config.test.ts \
  packages/core/src/services/chatRecordingService.test.ts \
  packages/core/src/config/storage.test.ts
npx prettier --check \
  docs/cli/headless.md \
  packages/cli/src/config/config.ts \
  packages/cli/src/config/config.test.ts \
  packages/core/src/config/config.ts \
  packages/core/src/config/storage.ts \
  packages/core/src/services/chatRecordingService.ts \
  packages/core/src/services/chatRecordingService.test.ts
npx eslint \
  packages/cli/src/config/config.ts \
  packages/cli/src/config/config.test.ts \
  packages/core/src/config/config.ts \
  packages/core/src/config/storage.ts \
  packages/core/src/services/chatRecordingService.ts \
  packages/core/src/services/chatRecordingService.test.ts
node packages/cli/dist/index.js --help | rg -n 'ephemeral|resume|session'
node packages/cli/dist/index.js --ephemeral --resume latest   # should print mutual-exclusion error and exit non-zero

Manual smoke run, on macOS:

ls -d ~/.gemini/tmp/* | sort > /tmp/before
node packages/cli/dist/index.js --ephemeral --help >/dev/null
ls -d ~/.gemini/tmp/* | sort > /tmp/after
diff /tmp/before /tmp/after   # expected empty

Pre-Merge Checklist

• Updated relevant documentation and README (if needed)
• Added/updated tests (if needed)
• Noted breaking changes (if any) — none. New flag, default off.
• Validated on required platforms/methods:
  • MacOS
    • npm run
    • npx
    • Docker
    • Podman
    • Seatbelt
  • Windows
    • npm run
    • npx
    • Docker
  • Linux
    • npm run
    • npx
    • Docker

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request adds an ephemeral session mode to the Gemini CLI, allowing users to run processes without leaving persistent artifacts in their ~/.gemini directory. By redirecting temporary file operations to a process-specific location in the system's temp folder and disabling automatic checkpointing, this change ensures that sensitive or one-off session data remains isolated and transient. The implementation is designed to be robust, covering all major per-run writers while maintaining existing functionality for standard persistent sessions.

Highlights

• New --ephemeral CLI flag: Introduced an --ephemeral flag that prevents the CLI from persisting run data (such as chat history, checkpoints, and logs) to the user's home directory.
• Storage redirection: Implemented a mechanism in the Storage service to redirect all per-run writes to a unique, process-local directory within the system's temporary folder when ephemeral mode is active.
• Validation and safety: Added strict validation to prevent combining --ephemeral with persistence-related flags like --resume, --session-id, or --session-file.
• Documentation and testing: Updated documentation in headless.md and added comprehensive unit tests to verify the redirection logic and the mutual exclusivity of the new flag.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize the Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counterproductive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request introduces an --ephemeral mode to the Gemini CLI, which prevents session data such as chat history, checkpoints, and logs from being persisted to the user's home directory by redirecting writes to a temporary system directory and disabling automatic checkpointing. Review feedback identifies a resource leak and security risk regarding the creation of temporary directories, suggesting the use of fs.mkdtempSync and cleanup on process exit. Additionally, the current implementation in ChatRecordingService is noted to cause a regression by disabling in-memory conversation history required for the UI; the reviewer recommends allowing the service to function normally using the redirected temporary path.

_{Note: Security Review did not run due to the size of the PR.}

[kiankyars]

@scidomino don't mean to annoy, but I believe this is a valuable contribution!

[scidomino]

Sorry. I am not reviewing PRs that are not for help-wanted issues.

[gemini-cli]

Hi there! Thank you for your interest in contributing to Gemini CLI.

To ensure we maintain high code quality and focus on our prioritized roadmap, we only guarantee review and consideration of pull requests for issues that are explicitly labeled as 'help wanted'.

This PR will be closed in 7 days if it remains without that designation. We encourage you to find and contribute to existing 'help wanted' issues in our backlog! Thank you for your understanding.

[kiankyars]

I don't understand how I can get the help wanted label for this issue

[kiankyars]

/assign

[gemini-cli]

This pull request is being closed as it has been open for 14 days without a 'help wanted' designation. We encourage you to find and contribute to existing 'help wanted' issues in our backlog! Thank you for your understanding.