fix(cli): optimize startup with lightweight parent process

[sehoon38]

Summary

This PR resolves a significant double-boot bottleneck in the CLI startup sequence, optimizing launch time by approximately 1.1 seconds (e.g., reducing startup from ~3.3s to ~2.2s for Google Sign-In users). To achieve this without breaking existing functionality (like internal restarts and custom home directories), the memory allocation and application relaunch logic have been completely restructured.

Details

1. The Bottleneck: Eliminating the Double-Boot

Historically, the CLI would boot up, import the entire heavy dependency graph (gemini-cli-core, React, Ink, Zod schemas, etc.), calculate that it needed 50% of the system's memory for the Node.js V8 engine, and then immediately spawn a second child process with the --max-old-space-size flag, causing the user to wait through the heavy boot sequence twice.

• Refactor: Moved the memory calculation logic to the very top of packages/cli/index.ts (the entry point), before any heavy modules are evaluated. The lightweight parent acts as a lightning-fast daemon that calculates memory, spawns the heavy child process with GEMINI_CLI_NO_RELAUNCH=true, and waits.

2. Adapting App Restarts (RELAUNCH_EXIT_CODE)

• Because the parent process now acts as the daemon wrapping the application, it must handle internal restarts (like when a user types /restart or modifies core settings).
• Adaptation: The lightweight parent in index.ts now listens for the 199 (RELAUNCH_EXIT_CODE) signal from the child process. When received, it instantly respawns the child instead of exiting.

3. Preserving Admin Controls via IPC

• In the old architecture, the parent process fetched CCPA admin controls before spawning the child so they could be passed down. In the new architecture, the parent boots instantly without loading the network/auth stack.
• Adaptation: When the first child process successfully fetches admin controls, it now sends an IPC message (admin-settings-update) up to the lightweight parent. If the app ever restarts, the parent instantly passes these cached settings down to the new child, allowing it to bypass the slow CCPA network call entirely upon reboot.

4. Respecting GEMINI_CLI_HOME and Global Settings

• The new fast memory allocation bypasses the heavy loadSettings() configuration engine to preserve the 1.1s speedup, sacrificing workspace-level overrides.
• Adaptation: Implemented a lightweight JSON.parse in index.ts to read the user's global settings.json, explicitly respecting the GEMINI_CLI_HOME environment variable as a fallback before defaulting to os.homedir(). This ensures the advanced.autoConfigureMemory preference is safely respected.
• Documentation: Updated settingsSchema.ts (and regenerated the JSON/Markdown docs) to explicitly state that autoConfigureMemory is only read globally during the initial boot sequence and ignores workspace-level overrides.

Related Issues

None.

How to Validate

1. Verify Boot Speed: Run the CLI and observe a noticeably faster startup time.
2. Verify Restarts: Change a core setting in the UI (e.g., toggle an advanced setting) or use a command that restarts the CLI. Ensure the app restarts smoothly instead of quitting.
3. Verify Settings: Add autoConfigureMemory: false to your global ~/.gemini/settings.json and ensure the CLI boots without throwing any flags, or test running it under a custom GEMINI_CLI_HOME.

Pre-Merge Checklist

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

[gemini-cli]

Hi @sehoon38, thank you so much for your contribution to Gemini CLI! We really appreciate the time and effort you've put into this.

We're making some updates to our contribution process to improve how we track and review changes. Please take a moment to review our recent discussion post: Improving Our Contribution Process & Introducing New Guidelines.

Key Update: Starting January 26, 2026, the Gemini CLI project will require all pull requests to be associated with an existing issue. Any pull requests not linked to an issue by that date will be automatically closed.

Thank you for your understanding and for being a part of our community!

[github-actions]

Size Change: +4.19 kB (+0.01%)

Total Size: 34 MB

Filename	Size	Change
./bundle/chunk-BR7HWKM6.js	0 B	-14.8 MB (removed)	🏆
./bundle/chunk-G2OX3PJV.js	0 B	-3.16 MB (removed)	🏆
./bundle/core-7VWIR6XH.js	0 B	-45.5 kB (removed)	🏆
./bundle/devtoolsService-RL2REABW.js	0 B	-28.4 kB (removed)	🏆
./bundle/gemini.js	4.97 kB	-549 kB (-99.1%)	🏆
./bundle/interactiveCli-L2LDGJEF.js	0 B	-1.65 MB (removed)	🏆
./bundle/oauth2-provider-3RJIPEOL.js	0 B	-9.16 kB (removed)	🏆
./bundle/chunk-HYNWAOBZ.js	3.16 MB	+3.16 MB (new file)	🆕
./bundle/chunk-IZ7FRNOH.js	3.47 kB	+3.47 kB (new file)	🆕
./bundle/chunk-P5A6DJK6.js	14.8 MB	+14.8 MB (new file)	🆕
./bundle/core-R3G65DXA.js	45.5 kB	+45.5 kB (new file)	🆕
./bundle/devtoolsService-HCURWFW6.js	28.4 kB	+28.4 kB (new file)	🆕
./bundle/gemini-74PR4NGS.js	552 kB	+552 kB (new file)	🆕
./bundle/interactiveCli-3TS7KOP2.js	1.65 MB	+1.65 MB (new file)	🆕
./bundle/oauth2-provider-LBBJFX5T.js	9.16 kB	+9.16 kB (new file)	🆕

ℹ️ View Unchanged

Filename	Size	Change
./bundle/bundled/third_party/index.js	8 MB	0 B
./bundle/chunk-34MYV7JD.js	2.45 kB	0 B
./bundle/chunk-5AUYMPVF.js	858 B	0 B
./bundle/chunk-5PS3AYFU.js	1.18 kB	0 B
./bundle/chunk-664ZODQF.js	124 kB	0 B
./bundle/chunk-DAHVX5MI.js	206 kB	0 B
./bundle/chunk-IUUIT4SU.js	56.5 kB	0 B
./bundle/chunk-OGWWODAT.js	1.96 MB	0 B
./bundle/chunk-RJTRUG2J.js	39.8 kB	0 B
./bundle/devtools-36NN55EP.js	696 kB	0 B
./bundle/dist-T73EYRDX.js	356 B	0 B
./bundle/events-XB7DADIJ.js	418 B	0 B
./bundle/getMachineId-bsd-TXG52NKR.js	1.55 kB	0 B
./bundle/getMachineId-darwin-7OE4DDZ6.js	1.55 kB	0 B
./bundle/getMachineId-linux-SHIFKOOX.js	1.34 kB	0 B
./bundle/getMachineId-unsupported-5U5DOEYY.js	1.06 kB	0 B
./bundle/getMachineId-win-6KLLGOI4.js	1.72 kB	0 B
./bundle/memoryDiscovery-JNNGTYL3.js	980 B	0 B
./bundle/multipart-parser-KPBZEGQU.js	11.7 kB	0 B
./bundle/node_modules/@google/gemini-cli-devtools/dist/client/main.js	222 kB	0 B
./bundle/node_modules/@google/gemini-cli-devtools/dist/src/_client-assets.js	229 kB	0 B
./bundle/node_modules/@google/gemini-cli-devtools/dist/src/index.js	13.4 kB	0 B
./bundle/node_modules/@google/gemini-cli-devtools/dist/src/types.js	132 B	0 B
./bundle/sandbox-macos-permissive-open.sb	890 B	0 B
./bundle/sandbox-macos-permissive-proxied.sb	1.31 kB	0 B
./bundle/sandbox-macos-restrictive-open.sb	3.36 kB	0 B
./bundle/sandbox-macos-restrictive-proxied.sb	3.56 kB	0 B
./bundle/sandbox-macos-strict-open.sb	4.82 kB	0 B
./bundle/sandbox-macos-strict-proxied.sb	5.02 kB	0 B
./bundle/src-QVCVGIUX.js	47 kB	0 B
./bundle/tree-sitter-7U6MW5PS.js	274 kB	0 B
./bundle/tree-sitter-bash-34ZGLXVX.js	1.84 MB	0 B
./bundle/cleanup-2E4EPG7S.js	856 B	+856 B (new file)	🆕

_{compressed-size-action}

[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 optimizes the CLI startup sequence by replacing the previous double-boot architecture with a lightweight parent process that manages memory allocation and process lifecycle. By deferring the loading of heavy dependencies until after the initial environment setup, the change significantly improves launch performance. The architecture also introduces robust IPC handling for persistent settings and a streamlined restart mechanism, ensuring a smoother user experience while maintaining functional parity.

Highlights

• Startup Optimization: Implemented a lightweight parent process to handle memory calculation and daemonization, eliminating the double-boot bottleneck and reducing startup time by approximately 1.1 seconds.
• Restart Logic: Restructured the application relaunch process to allow the parent process to listen for a specific exit code (199) and instantly respawn the child process.
• IPC for Admin Settings: Introduced IPC communication to pass cached admin settings from the child process to the parent, ensuring settings persist across restarts without redundant network calls.
• Configuration Constraints: Updated documentation and settings schema to clarify that autoConfigureMemory is now strictly a global setting, ignoring workspace-level overrides to maintain startup performance.

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 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 counter productive. 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 implements a process relaunch mechanism to dynamically configure Node.js memory limits based on global user settings. The CLI entry point is refactored into a lightweight parent process that spawns a heavy child process with the appropriate memory flags. Feedback focuses on improving the parent process's resilience by handling termination signals to ensure proper child cleanup and providing more descriptive error logging if the child process fails to start.