feat(cli): add DevTools integration with gemini-cli-devtools

[SandyTao520]

Summary

Add a DevTools web inspector for Gemini CLI sessions. When enabled via general.devtools, the CLI streams network requests and console logs to a local DevTools web UI in real time.

Details

• devtoolsService.ts: Manages DevTools server lifecycle — probes for existing instance, starts/joins with race handling, auto-promotes on reconnect failure
• activityLogger.ts: Adds WebSocket transport mode for streaming network/console logs to DevTools server, with auto-reconnect logic
• gemini.tsx: Initializes DevTools when general.devtools is enabled, replays early console logs
• Uses gemini-cli-devtools from npm as an external dynamic import (not bundled into gemini.js)
• .gemini/settings.json enables devtools by default for developers of this repo

Related Issues

#18494

How to Validate

1. npm install && npm run build
2. node bundle/gemini.js — should print DevTools available at: http://127.0.0.1:25417
3. Open the URL in browser — Console and Network tabs should appear
4. Send a message in the CLI — network requests appear in DevTools
5. Verify copy/download JSON buttons work on request/response bodies
6. Disable with "general": { "devtools": false } in settings — CLI should start without DevTools

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

[gemini-cli]

Hi there! Thank you for your contribution to Gemini CLI.

To improve our contribution process and better track changes, we now require all pull requests to be associated with an existing issue, as announced in our recent discussion and as detailed in our CONTRIBUTING.md.

This pull request is being closed because it is not currently linked to an issue. Once you have updated the description of this PR to link an issue (e.g., by adding Fixes #123 or Related to #123), it will be automatically reopened.

How to link an issue:
Add a keyword followed by the issue number (e.g., Fixes #123) in the description of your pull request. For more details on supported keywords and how linking works, please refer to the GitHub Documentation on linking pull requests to issues.

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

[gemini-cli]

Hi @SandyTao520, 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!

[gemini-code-assist]

Summary of Changes

Hello @SandyTao520, 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 significantly enhances the debugging capabilities of the Gemini CLI by integrating a web-based DevTools inspector. This allows developers to monitor network activity and console output from CLI sessions in a familiar browser environment, streamlining the debugging process and providing deeper insights into application behavior.

Highlights

• DevTools Integration: Introduces a new DevTools web inspector for Gemini CLI sessions, allowing real-time streaming of network requests and console logs to a local web UI.
• Dynamic DevTools Server Management: Implements a robust system in devtoolsService.ts to manage the DevTools server lifecycle, including probing for existing instances, starting new ones, handling race conditions for port allocation, and auto-promoting to a server if client connection fails.
• Enhanced Activity Logging: Refactors activityLogger.ts to support WebSocket transport for streaming logs, with improved auto-reconnect logic and a mechanism to promote to a DevTools server if client connections are repeatedly unsuccessful.
• Console Interception Refinement: Updates ConsolePatcher.ts to correctly distinguish between DevTools and TUI debug console outputs, ensuring proper logging behavior.
• New Configuration Options: Adds general.devtools to enable/disable the DevTools inspector and experimental.enableEventDrivenScheduler for an event-driven scheduler, both configurable via settings.json and documented.
• External Dependency: Integrates gemini-cli-devtools as an external dynamic import, ensuring it's not bundled directly into the main gemini.js file.

Changelog

• docs/get-started/configuration.md
  • Added documentation for the new general.devtools setting.
  • Added documentation for the new experimental.enableEventDrivenScheduler setting.
• esbuild.config.js
  • Added gemini-cli-devtools to the list of external dependencies to prevent bundling.
• package-lock.json
  • Added gemini-cli-devtools as an optional dependency.
  • Removed path-scurry and lru-cache from @vscode/vsce's node_modules section, indicating a potential dependency cleanup or version update.
• package.json
  • Added gemini-cli-devtools as a dependency.
• packages/cli/src/config/settingsSchema.ts
  • Defined the schema for the new general.devtools boolean setting.
  • Defined the schema for the new experimental.enableEventDrivenScheduler boolean setting.
• packages/cli/src/nonInteractiveCli.test.ts
  • Updated the mock import for registerActivityLogger to point to devtoolsService.js instead of activityLogger.js.
• packages/cli/src/nonInteractiveCli.ts
  • Changed the import path for registerActivityLogger from activityLogger.js to devtoolsService.js.
  • Made the call to registerActivityLogger awaitable.
• packages/cli/src/ui/utils/ConsolePatcher.ts
  • Refactored the patchConsoleMethod to handle debug messages more precisely, only logging them if debugMode is enabled, and ensuring consistent message handling regardless of stderr status.
• packages/cli/src/utils/activityLogger.ts
  • Removed the parseHostPort utility function.
  • Modified setupNetworkLogging to accept an onReconnectFailed callback, introduce reconnectAttempts with a MAX_RECONNECT_ATTEMPTS limit, and reduce the reconnect timeout from 5000ms to 1000ms.
  • Refactored the activity logger initialization into initActivityLogger (for initial setup with network or file mode) and addNetworkTransport (for adding network transport later, e.g., during promotion).
  • Introduced bridgeCoreEvents to ensure console events are bridged to the activity logger only once.
• packages/cli/src/utils/devtoolsService.ts
  • New file: Implements the core logic for DevTools integration.
  • Includes probeDevTools for checking existing DevTools instances.
  • startOrJoinDevTools handles starting a new DevTools server or connecting to an existing one, resolving port contention.
  • handlePromotion manages the fallback mechanism to start a DevTools server if a client connection fails.
  • registerActivityLogger orchestrates the DevTools setup, attempting to connect to an existing instance, starting a new one, or falling back to file logging based on configuration.
• schemas/settings.schema.json
  • Added JSON schema definitions for general.devtools and experimental.enableEventDrivenScheduler.

Ignored Files

• Ignored by pattern: .gemini/** (1)
  • .gemini/settings.json

Activity

• No specific activity (comments, reviews, or progress updates) has been recorded for this pull request yet.

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.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

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. ↩

[github-actions]

Size Change: +4.29 kB (+0.02%)

Total Size: 23.9 MB

Filename	Size	Change
./bundle/gemini.js	23.9 MB	+4.29 kB (+0.02%)

ℹ️ View Unchanged

Filename	Size
./bundle/sandbox-macos-permissive-closed.sb	1.03 kB
./bundle/sandbox-macos-permissive-open.sb	890 B
./bundle/sandbox-macos-permissive-proxied.sb	1.31 kB
./bundle/sandbox-macos-restrictive-closed.sb	3.29 kB
./bundle/sandbox-macos-restrictive-open.sb	3.36 kB
./bundle/sandbox-macos-restrictive-proxied.sb	3.56 kB

_{compressed-size-action}

[gemini-code-assist]

Code Review

This pull request introduces a DevTools integration for inspecting Gemini CLI sessions, which is a great addition for debugging and development. However, the current implementation has a significant security flaw: it connects to a fixed local port (25417) without any authentication, allowing a malicious local user to intercept sensitive session logs, including network requests and console output, by squatting on the port. It is recommended to implement a secure handshake or use randomized ports to mitigate this risk. Additionally, a potential issue regarding recursion in the promotion logic could lead to an infinite loop under certain network conditions, which should be addressed to enhance resilience.