Skip to content
Closed
Show file tree
Hide file tree
Changes from 4 commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .eslintignore
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
devtools-standalone/
26 changes: 26 additions & 0 deletions GEMINI.md
Original file line number Diff line number Diff line change
@@ -1,3 +1,29 @@
## Gemini DevTools

A standalone web UI for visualizing activity logs (network requests, console
output) generated by Gemini CLI.

### Quick Start

To debug the latest local session:

```bash
npx gemini-cli-devtools
```

### Features

- **Live Stream**: Real-time visualization of CLI activity via SSE.
- **Session History**: Easily switch between different CLI sessions.
- **Import/Export**: Load `.jsonl` activity logs for offline analysis or sharing
with teammates.
- **Network Inspector**: Detailed request/response headers, payloads, and
timing.
- **Console Viewer**: Collapsible, searchable, and themed console output.
- **Theme Support**: System, Light, and Dark modes.

---

# Gemini CLI Project Context

Gemini CLI is an open-source AI agent that brings the power of Gemini directly
Expand Down
113 changes: 113 additions & 0 deletions devtools-standalone/GEMINI.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,113 @@
# @google/gemini-cli-devtools

A standalone Developer Tools package for debugging Node.js applications,
offering a Chrome DevTools-like interface for Network and Console inspection.

## Features

- **Network Inspector**:
- Intercepts **HTTP/HTTPS** requests (via monkey-patching `http`/`https`).
- Intercepts **Undici/Fetch** requests (via `diagnostics_channel`).
- Supports **Server-Sent Events (SSE)** with visual chunk grouping.
- Automatically filters noise (e.g., `localhost:8097`, internal tunnels).
- Groups requests by API path prefix.
- **Console Inspector**:
- Programmable interface to feed logs (`addConsoleLog`).
- Real-time updates via SSE.
- **UI**: A modern React + Vite application served by an embedded Node.js HTTP
server.

## Installation

This package is intended for use within the Gemini CLI monorepo but can be
adapted for other tools.

## Usage

### 1. Start the DevTools Server

```typescript
import { DevTools } from '@google/gemini-cli-devtools';

// Initialize the singleton
const devTools = DevTools.getInstance();

// Enable network interception (http, https, fetch)
devTools.enableGlobalInterception();

// Start the UI server (returns the URL, e.g., http://127.0.0.1:54321)
const url = await devTools.start();
console.log(`DevTools running at ${url}`);
```

### 2. Log Console Messages

DevTools does not automatically capture `console.log`. You must feed logs into
it explicitly.

```typescript
// Example: connecting a logger or event bus to DevTools
myEventBus.on('log', (payload) => {
// payload: { type: 'info'|'error'|'warn', content: string }
DevTools.getInstance().addConsoleLog(payload);
});
```

### 3. Stop the Server

```typescript
devTools.stop();
```

## Architecture

- **Backend (`src/index.ts`)**:
- Singleton class `DevTools`.
- Manages in-memory log storage (circular buffer).
- Runs an HTTP server to serve the frontend and API endpoints (`/logs`,
`/events`).
- **Frontend (`client/`)**:
- React 18 + Vite application.
- Connects to backend via `EventSource` (SSE) for real-time updates.
- Provides "Network" and "Console" tabs.

## API Reference

### `DevTools.getInstance()`

Returns the singleton instance.

### `enableGlobalInterception()`

Patches `http.request`, `https.request` and subscribes to
`undici:request:create` channels to capture all outgoing network traffic.

### `start(): Promise<string>`

Starts the embedded HTTP server on a random available port. Returns the full
URL.

### `addConsoleLog(payload: ConsoleLogPayload)`

Adds a log entry to the Console tab.

- `payload.type`: `'log' | 'warn' | 'error' | 'debug' | 'info'`
- `payload.content`: String message.

## Development

### Build

```bash
# Build both frontend and backend
npm run build -w @google/gemini-cli-devtools
```

### Run Frontend in Dev Mode

1. Start a backend process (e.g., via the CLI in debug mode) to serve the API.
2. Run the frontend with Vite for hot-reloading:
```bash
cd packages/devtools
npm run build:client -- --watch
```
25 changes: 25 additions & 0 deletions devtools-standalone/client/index.html
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
<!doctype html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Gemini CLI DevTools</title>
<style>
html,
body,
#root {
height: 100%;
margin: 0;
padding: 0;
font-family:
-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica,
Arial, sans-serif;
overflow: hidden;
}
</style>
</head>
<body>
<div id="root"></div>
<script type="module" src="/src/main.tsx"></script>
</body>
</html>
Loading