GEMINI.md

1# Gemini CLI DevTools
2 
3Integrated Developer Tools for Gemini CLI, providing a Chrome DevTools-like
4interface for Network and Console inspection. Launched automatically when the
5`general.devtools` setting is enabled.
6 
7## Features
8 
9- **Network Inspector**: Real-time request/response logging with streaming
10  chunks and duration tracking
11- **Console Inspector**: Real-time console log viewing
12  (log/warn/error/debug/info)
13- **Session Management**: Multiple CLI session support with live connection
14  status
15- **Import/Export**: Import JSONL log files, export current session logs
16 
17## How It Works
18 
19When `general.devtools` is enabled, the CLI's `devtoolsService` automatically:
20 
211. Probes port 25417 for an existing DevTools instance
222. If found, connects as a WebSocket client
233. If not, starts a new DevTools server and connects to it
244. If another instance races for the port, the loser connects to the winner
25 
26No environment variables needed for normal use.
27 
28## Architecture
29 
30```
31gemini.tsx / nonInteractiveCli.ts
32         │  (dynamic import)
33         ▼
34  devtoolsService.ts          ← orchestration + DevTools lifecycle
35         │  (imports)
36         ▼
37  activityLogger.ts           ← pure logging (capture, file, WebSocket transport)
38         │  (events)
39         ▼
40  DevTools server (:25417)    ← this package (HTTP + WebSocket + SSE)
41         │  (SSE /events)
42         ▼
43  DevTools UI (React)         ← client/ compiled by esbuild
44```
45 
46## Environment Variables
47 
48| Variable                         | Description                                   |
49| -------------------------------- | --------------------------------------------- |
50| `GEMINI_CLI_ACTIVITY_LOG_TARGET` | File path for JSONL mode (optional, fallback) |
51 
52## API Endpoints
53 
54| Endpoint                | Method    | Description                                                                 |
55| ----------------------- | --------- | --------------------------------------------------------------------------- |
56| `/ws`                   | WebSocket | Log ingestion from CLI sessions (register, network, console)                |
57| `/events`               | SSE       | Pushes snapshot on connect, then incremental network/console/session events |
58| `/api/trigger-debugger` | POST      | Triggers the Node.js debugger for a specific CLI session via WebSocket      |
59 
60## Development
61 
62```bash
63# Build everything (client + server)
64npm run build
65 
66# Rebuild client only after UI changes
67npm run build:client
68```
69 
70### Project Structure
71 
72```
73packages/devtools/
74├── src/
75│   └── index.ts           # DevTools server (HTTP, WebSocket, SSE)
76├── client/
77│   ├── index.html
78│   └── src/
79│       ├── main.tsx        # React entry
80│       ├── App.tsx         # DevTools UI
81│       └── hooks.ts        # Data fetching hooks
82├── esbuild.client.js       # Client build script
83└── dist/                   # Build output
84    ├── src/index.js        # Compiled server
85    └── client/             # Bundled client assets
86```
87