Skip to content
The Terminal

DevTools API

import { Aside } from ‘@astrojs/starlight/components’;

The Terminal exposes a DevTools HTTP API that allows external tools to interact with the built-in browser panel. This is the mechanism that gives Gee-Code vision into your running application.

Architecture

Section titled “Architecture”
┌─────────────────────────────┐
│  The Terminal (Main Process) │
│                             │
│  DevTools HTTP Server       │
│  (port 9876)                │
│       │                     │
│       ▼                     │
│  Browser Panel (Chromium)   │
│  └── Your running app       │
└─────────────────────────────┘
         ▲
         │ HTTP
         │
┌────────┴────────────────────┐
│  Gee-Code                    │
│  (reads ~/.the-terminal/    │
│   devtools.json)            │
└─────────────────────────────┘

Configuration File

Section titled “Configuration File”

The Terminal writes connection details to ~/.the-terminal/devtools.json:

{
  "port": 9876,
  "url": "http://localhost:9876"
}

Gee-Code reads this file on startup to discover the API endpoint.

API Endpoints

Section titled “API Endpoints”

The DevTools API exposes several capabilities:

Console

Section titled “Console”

Read console output from the browser panel.

GET /console?limit=50&clear=false

Returns console entries with level (log, warn, error), message text, and timestamp.

DOM Inspection

Section titled “DOM Inspection”

Get the DOM structure of the current page or a specific element.

GET /dom?selector=body&depth=4

Returns a nested tree of elements with tag names, attributes, and text content.

JavaScript Execution

Section titled “JavaScript Execution”

Execute JavaScript in the page context.

POST /eval
Content-Type: application/json


{"expression": "document.title"}

Returns the result of the expression. Each evaluation runs in its own scope, so variable declarations don’t conflict.

Screenshots

Section titled “Screenshots”

Capture the current page or a specific element.

GET /screenshot?selector=body&full_page=false

Returns a PNG image of the rendered page.

Interaction

Section titled “Interaction”

Click elements or fill form inputs.

POST /click
Content-Type: application/json


{"selector": "#submit-button"}
POST /fill
Content-Type: application/json


{"selector": "#email-input", "value": "user@example.com"}

Interaction methods trigger proper DOM events, compatible with React, Vue, Angular, and other frameworks.

Network

Section titled “Network”

Get recent network requests.

GET /network?limit=30&filter_pattern=api

Returns URLs, methods, status codes, and timing for recent requests.

Page Navigation

Section titled “Page Navigation”
GET /pages          # List open pages
POST /reload        # Reload current page
POST /navigate      # Navigate to a URL

Security

Section titled “Security”

The DevTools API only listens on localhost — it’s not accessible from the network. The port is randomized and written to a file only readable by the current user.

Building Custom Integrations

Section titled “Building Custom Integrations”

While Gee-Code is the primary consumer of the DevTools API, the HTTP interface is open for custom tooling. You could build:

  • A testing framework that drives the browser panel
  • A monitoring tool that watches for console errors
  • A custom AI integration that uses a different LLM

The API speaks standard HTTP with JSON payloads — no proprietary protocol.

Next Steps

Section titled “Next Steps”