@uitoolbar/provider-codex

OpenAI Codex integration provider for UiToolbar. Uses the OpenAI Codex SDK to enable AI-powered code modifications based on selected elements.

Features

• Codex SDK - Uses @openai/codex-sdk for agent interactions
• SSE Streaming - Real-time streaming of agent responses
• Session Management - Reusable Codex threads with 30-minute TTL
• Undo Support - Per-session git state snapshots for reliable undo
• Local History - Edit history stored in .uistudio/history.ndjson
• Monorepo Support - Searches packages/ directories for file resolution

Installation

pnpm add @uitoolbar/provider-codex

Requirements

• OpenAI API key configured for Codex access

Usage

Starting the Server

# Via CLI
pnpm exec uitoolbar-codex

# Or programmatically
import { startServer } from '@uitoolbar/provider-codex/server'
startServer(7567)

API Endpoints

GET /health

Check server status and agent availability.

{
  "status": "ok",
  "provider": "codex",
  "version": "0.0.1",
  "agentInstalled": true
}

POST /agent

Send a prompt to the Codex agent. Returns SSE stream.

// Request
{
  content: string      // Element context (HTML, etc.)
  prompt: string       // User instruction
  options?: {
    model?: string     // Model override
    workspace?: string // Working directory
  }
  sessionId?: string   // Resume existing session
}

// SSE Events
event: status
data: "Thinking…"

event: status
data: "Completed successfully"

event: error
data: "Error message"

event: done
data: ""

POST /abort/:sessionId

Abort an in-progress agent session.

POST /undo/:sessionId

Undo changes from a specific session.

POST /undo

Undo the last agent change (uses last session).

GET /history?elementId=...&limit=...

Retrieve edit history for a specific element.

Client Usage

import { createCodexClient } from '@uitoolbar/provider-codex/client'

const client = createCodexClient('http://localhost:7567')

// Check connection
const isConnected = await client.checkHealth()

// Send prompt with streaming
for await (const message of client.sendPrompt({
  content: '<button>Click me</button>',
  prompt: 'Make this button red'
})) {
  console.log(message.type, message.content)
}

Configuration

| Option | Default | Description | |--------|---------|-------------| | port | 7567 | Server port | | model | (agent default) | Override AI model | | workspace | process.cwd() | Working directory |

Environment Variables

• UISTUDIO_CWD - Default workspace path

How It Works

1. Extension sends element context + prompt to server
2. Server creates a Codex thread via @openai/codex-sdk
3. Agent events are streamed back as SSE (messages, reasoning, commands, file changes)
4. Sessions persist for 30 minutes with automatic cleanup
5. Git state is snapshotted before/after for undo support

Development

# Run server in dev mode
pnpm dev

# Run tests
pnpm test

# Build
pnpm build