openclaw-android-assistant/PROJECT_SPEC.md

codex-web-local — Project Specification

Overview

codex-web-local is a lightweight, browser-based web UI for OpenAI Codex. It mirrors the Codex Desktop experience and runs on top of the Codex app-server, allowing remote access to a local Codex instance from any browser.

• Author: Pavel Voronin
• License: MIT
• Repository: https://github.com/pavel-voronin/codex-web-local

Architecture

┌──────────────────────────────────────────────────────────┐
│  Browser (Vue 3 SPA)                                     │
│  ┌────────────┐  ┌──────────────┐  ┌──────────────────┐ │
│  │ App.vue     │  │ Composables  │  │ API Layer        │ │
│  │ (Router)    │──│ useDesktop   │──│ codexGateway     │ │
│  │             │  │ State        │  │ codexRpcClient   │ │
│  └────────────┘  └──────────────┘  └────────┬─────────┘ │
└─────────────────────────────────────────────┼───────────┘
                                              │ HTTP/SSE
┌─────────────────────────────────────────────┼───────────┐
│  Node.js Server                             │           │
│  ┌──────────────────────────────────────────┼─────────┐ │
│  │ Express / Vite Middleware                │         │ │
│  │  ┌───────────────────┐  ┌───────────────┴───────┐ │ │
│  │  │ Auth Middleware    │  │ Codex Bridge          │ │ │
│  │  │ (password, cookie) │  │ /codex-api/*          │ │ │
│  │  └───────────────────┘  └───────────┬───────────┘ │ │
│  └─────────────────────────────────────┼─────────────┘ │
│                                        │ stdin/stdout   │
│  ┌─────────────────────────────────────┼─────────────┐ │
│  │ codex app-server (child process)    │             │ │
│  │ JSON-RPC over newline-delimited I/O │             │ │
│  └───────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────┘

Key Architectural Decisions

• No Pinia / Vuex: All state lives in a single composable (useDesktopState). Reactive refs + computed properties manage thread, message, model, and UI state.
• No WebSocket: Real-time communication uses SSE (EventSource) on /codex-api/events for server-to-client notifications, and standard HTTP POST for client-to-server RPC.
• Single child process: The Node server spawns exactly one codex app-server child process and multiplexes all RPC calls through it via stdin/stdout.
• Shared bridge state: A global singleton (AppServerProcess + MethodCatalog) survives Vite HMR reloads during development.

Tech Stack

Layer	Technology	Version
Frontend framework	Vue 3 (Composition API, <script setup>)	^3.5
Routing	Vue Router 4	^4.6
Styling	Tailwind CSS 4 (via @tailwindcss/vite)	^4.1
Build tool	Vite 6	^6.1
CLI build	tsup 8	^8.4
Type checking	TypeScript 5, vue-tsc 2	^5.7 / ^2.2
Server	Express 5	^5.1
CLI framework	Commander 13	^13.1
Runtime	Node.js >= 18	—

Project Structure

codex-web-local/
├── src/
│   ├── api/                          # Backend communication layer
│   │   ├── codexGateway.ts           # High-level API (threads, turns, models)
│   │   ├── codexRpcClient.ts         # HTTP/SSE transport for /codex-api/*
│   │   ├── codexErrors.ts            # Error normalization
│   │   ├── appServerDtos.ts          # Raw DTO types from app-server
│   │   └── normalizers/v2.ts         # DTO → UI type transformers
│   ├── components/
│   │   ├── content/                  # Main content area
│   │   │   ├── ThreadConversation.vue  # Message list with scroll management
│   │   │   ├── ThreadComposer.vue      # Input + model/reasoning selectors
│   │   │   ├── ComposerDropdown.vue    # Reusable dropdown (model, folder)
│   │   │   └── ContentHeader.vue       # Page title bar
│   │   ├── sidebar/                  # Left panel
│   │   │   ├── SidebarThreadTree.vue   # Thread list grouped by project
│   │   │   └── SidebarThreadControls.vue # New thread, auto-refresh toggle
│   │   ├── layout/
│   │   │   └── DesktopLayout.vue       # Sidebar + content split layout
│   │   └── icons/                    # Tabler icon components
│   ├── composables/
│   │   └── useDesktopState.ts        # Central state composable (~2000 LOC)
│   ├── server/                       # Node.js server (production + dev)
│   │   ├── codexAppServerBridge.ts   # Spawns/proxies codex app-server
│   │   ├── httpServer.ts             # Express app for production
│   │   ├── authMiddleware.ts         # Password-based auth
│   │   └── password.ts              # Password generation + comparison
│   ├── cli/
│   │   └── index.ts                  # CLI entry point (Commander)
│   ├── types/
│   │   └── codex.ts                  # UI-layer TypeScript types
│   ├── router/
│   │   └── index.ts                  # Vue Router config
│   ├── App.vue                       # Root component
│   ├── main.ts                       # Vue app bootstrap
│   └── style.css                     # Global Tailwind styles
├── documentation/                    # Codex app-server protocol docs
│   ├── APP_SERVER_DOCUMENTATION.md   # Full protocol reference (66 methods, 7 server requests, 34 notifications)
│   └── app-server-schemas/           # Materialized JSON + TypeScript schemas
│       ├── json/                     # JSON Schema files (v1, v2, root)
│       └── typescript/               # TypeScript type definitions (v1, v2, root)
├── index.html                        # SPA entry point
├── vite.config.ts                    # Vite config (Vue, Tailwind, bridge middleware)
├── tsup.config.ts                    # CLI build config
└── package.json                      # Scripts, deps, bin entry

Features

Implemented

Feature	Description
Thread management	List, create, archive, select threads; resume inactive threads on demand
Chat conversation	Send messages, view full conversation history with user/assistant/system roles
Real-time streaming	SSE-based live updates for agent messages, reasoning text, and turn lifecycle
Model selection	Dropdown to choose from available models (model/list RPC)
Reasoning effort	Configurable reasoning effort level (none → xhigh)
Turn interrupt	Stop in-progress agent turns
Server request handling	Approve/reject server-initiated requests (command approvals, file changes, tool calls)
Project grouping	Threads organized by working directory (project)
Project customization	Rename, reorder, remove projects (persisted to localStorage)
Unread indicators	Track read/unread state per thread
Auto-refresh	Optional 4-second polling with visual countdown
Collapsible sidebar	Resizable (260–620px), toggle with Ctrl/Cmd+B
Scroll state persistence	Remember scroll position per thread across navigation
Password auth	Optional password protection with auto-generated passwords in production
New thread creation	"Let's build" hero view with folder selector
Live overlay	Reasoning text, activity labels, and error messages during agent work
Turn duration display	"Worked for Xm Ys" summary after turn completion

Not Yet Implemented

Based on the app-server protocol (documentation/APP_SERVER_DOCUMENTATION.md), the following capabilities are available in the protocol but not yet surfaced in the UI:

Feature	Relevant RPC Methods
Thread forking	thread/fork
Thread rollback	thread/rollback
Thread naming	thread/name/set
Thread unarchiving	thread/unarchive
Context compaction	thread/compact/start
Code review	review/start
Skills management	skills/list, skills/remote/read, skills/remote/write, skills/config/write
Apps management	app/list
MCP server status	mcpServerStatus/list, config/mcpServer/reload
Account management	account/login/start, account/logout, account/read, account/rateLimits/read
Configuration UI	config/read, config/value/write, config/batchWrite, configRequirements/read
Command execution	command/exec
Git diff view	gitDiffToRemote
Fuzzy file search	fuzzyFileSearch, session-based search
Feedback upload	feedback/upload
Collaboration modes	collaborationMode/list
Experimental features	experimentalFeature/list
Turn diff view	turn/diff/updated notification
Turn plan view	turn/plan/updated notification
Token usage display	thread/tokenUsage/updated notification
Command output streaming	item/commandExecution/outputDelta notification
File change output	item/fileChange/outputDelta notification
MCP tool call progress	item/mcpToolCall/progress notification
Terminal interaction	item/commandExecution/terminalInteraction notification

Planned: Thread Forking

Forking creates a new thread from an existing thread so users can branch the conversation without mutating the original.

UX Requirements

• Add a Fork thread action in thread row controls and thread header controls.
• On success, navigate to the new forked thread immediately.
• Show lineage metadata in the forked thread header:
  • Forked from: <source thread title or id>
• Preserve lineage information in thread list tooltips/details where available.

RPC Contract

• Method: thread/fork
• Primary input: threadId of the source thread (preferred over path)
• Optional overrides: cwd, model, approvalPolicy, sandbox, baseInstructions, developerInstructions
• Expected response: ThreadForkResponse with a new thread.id

State + Routing Behavior

• Insert the new thread into sourceGroups / projectGroups immediately after fork returns.
• Set selectedThreadId to the new forked thread id.
• Route to /thread/:threadId for the new thread.
• Keep original thread unchanged and still selectable.

Acceptance Criteria

• User can fork from any existing thread.
• Forked thread has a different id from the source thread.
• Source thread history remains intact.
• UI displays the fork origin for the selected forked thread.

Communication Protocol

HTTP Endpoints (Bridge)

Method	Path	Purpose
POST	/codex-api/rpc	JSON-RPC proxy — forwards { method, params } to app-server
POST	/codex-api/server-requests/respond	Reply to server-initiated requests
GET	/codex-api/server-requests/pending	List pending server requests
GET	/codex-api/meta/methods	Discover available RPC methods
GET	/codex-api/meta/notifications	Discover available notification types
GET	/codex-api/events	SSE stream for real-time notifications

Bridge → App-Server

Communication uses newline-delimited JSON-RPC 2.0 over stdin/stdout of the codex app-server child process. The bridge:

1. Receives HTTP requests from the frontend
2. Translates them into JSON-RPC calls on stdin
3. Reads JSON-RPC responses from stdout
4. Forwards server-initiated requests to the frontend via SSE
5. Routes client responses back to the app-server

RPC Methods Used by the Frontend

Method	Purpose
initialize	Handshake with app-server (automatic)
thread/list	Fetch all non-archived threads
thread/read	Fetch thread detail with turns and items
thread/start	Create a new thread
thread/resume	Resume an inactive thread
thread/archive	Archive a thread
turn/start	Send a user message and start agent turn
turn/interrupt	Interrupt an in-progress turn
model/list	List available models
config/read	Read current model and reasoning effort

Notifications Handled by the Frontend

Notification	Action
turn/started	Mark thread in-progress, show "Thinking"
turn/completed	Mark complete, show duration summary
item/started	Update activity label (Thinking / Writing)
item/completed	Finalize agent message or reasoning
item/agentMessage/delta	Append to live agent message text
item/reasoning/summaryTextDelta	Append to live reasoning overlay
item/reasoning/summaryPartAdded	Insert reasoning section break
server/request	Show pending approval in UI
server/request/resolved	Remove resolved request from UI
error	Display error notification
thread/name/updated	(Queued for thread list refresh)

State Management

All frontend state is managed by useDesktopState() — a single Vue composable that provides:

Reactive State

• projectGroups / sourceGroups — thread list grouped by project
• selectedThreadId / selectedThread — currently active thread
• persistedMessagesByThreadId — loaded messages from server
• liveAgentMessagesByThreadId — streaming agent messages
• liveReasoningTextByThreadId — streaming reasoning text
• inProgressById — per-thread turn-in-progress flags
• availableModelIds / selectedModelId / selectedReasoningEffort
• pendingServerRequestsByThreadId — approval requests
• turnSummaryByThreadId / turnActivityByThreadId / turnErrorByThreadId
• Loading/sending/interrupting boolean flags

Persistence (localStorage)

Key	Data
codex-web-local.thread-read-state.v1	Per-thread read timestamps
codex-web-local.thread-scroll-state.v1	Per-thread scroll positions
codex-web-local.selected-thread-id.v1	Last selected thread
codex-web-local.project-order.v1	Custom project ordering
codex-web-local.project-display-name.v1	Custom project names
codex-web-local.auto-refresh-enabled.v1	Auto-refresh preference
codex-web-local.sidebar-collapsed.v1	Sidebar collapse state

Event Processing Pipeline

1. SSE events arrive via EventSource on /codex-api/events
2. Each event is passed to applyRealtimeUpdates() for immediate UI effects (activity labels, live text, in-progress flags)
3. Events are also passed to queueEventDrivenSync() which debounces (220ms) a full data refresh
4. The debounced syncFromNotifications() calls loadThreads() and loadMessages() to reconcile server state

Routing

Route	Path	Behavior
Home	/	New thread creation view with folder selector
Thread	/thread/:threadId	Thread conversation view
Redirect	/new-thread	Redirects to Home
Fallback	/:pathMatch(.*)*	Redirects to Home

Bidirectional sync between selectedThreadId state and URL is handled via Vue watchers in App.vue.

Development

Prerequisites

• Node.js >= 18
• codex CLI installed and in PATH

Scripts

Command	Description
npm run dev	Start Vite dev server (port 5173)
npm run build	Type-check + build frontend + build CLI
npm run build:frontend	vue-tsc --noEmit && vite build
npm run build:cli	tsup (builds CLI to dist-cli/)
npm run preview	Preview production build

Dev Mode

npm run dev starts a Vite dev server that includes the codex bridge as middleware. The bridge spawns codex app-server as a child process. The frontend calls /codex-api/* endpoints on the same origin.

Production Mode

npx codex-web-local [--port 3000] [--password mypass] [--no-password]

The CLI starts an Express server that serves the built frontend from dist/ and uses the same bridge middleware. Password authentication is enabled by default with an auto-generated password printed to the console.

Auth (Production)

• Default: auto-generated password printed to console on startup
• Login: POST /auth/login with { password } body
• Session: HttpOnly cookie codex_web_local_token
• Uses constant-time comparison to prevent timing attacks

Design Principles

1. Minimal dependencies: Only essential packages — no state management library, no component library, no CSS framework beyond Tailwind
2. Protocol-first: The UI is designed around the Codex app-server protocol; all features map directly to RPC methods and notifications
3. Offline-resilient: localStorage persistence ensures the UI recovers gracefully from disconnections
4. Reference equality optimization: Extensive use of identity checks and shallow merging to minimize unnecessary Vue re-renders
5. Single composable pattern: All state and logic in one place for discoverability, at the cost of file size (~2000 LOC)