agentgui 1.0.156 → 1.0.158

package/CLAUDE.md

@@ -1,183 +1,91 @@
-# Claude Code Reliable Integration
+# AgentGUI
 
-**Status**: Production Ready
-**Date**: 2026-02-05
+Multi-agent GUI client for AI coding agents (Claude Code, Gemini CLI, OpenCode, Goose, etc.) with real-time streaming, WebSocket sync, and SQLite persistence.
 
-## Overview
+## Running
 
-agentgui is a multi-agent ACP client with real-time communication, WebSocket streaming, and beautiful semantic HTML UI using RippleUI components.
-
-## Features
-
-✅ `--dangerously-skip-permissions` flag support
-✅ JSON streaming mode for real-time execution capture
-✅ Database persistence with zero data loss guarantees
-✅ Real-time WebSocket broadcasting to clients
-✅ Automatic crash recovery and conflict resolution
-✅ Production-ready monitoring and observability
-
-## Architecture
-
-### Server Components
-- **server.js**: REST API + WebSocket endpoints, event broadcasting
-- **lib/claude-runner.js**: Claude Code CLI execution with streaming support
-- **lib/database-service.ts**: SQLite persistence with WAL mode
-- **lib/sync-service.ts**: Real-time event synchronization and recovery
-
-### Streaming Features
-- JSON streaming via `--output-format=stream-json`
-- Real-time WebSocket event broadcasting
-- Session-based client subscriptions
-- Event persistence and recovery
-- Exponential backoff for offline queues
-
-### Database
-- SQLite with WAL mode for reliability
-- Tables: conversations, messages, sessions, events, stream_updates
-- Foreign key constraints for data integrity
-- Transactions for atomic operations
-
-## API Endpoints
-
-### REST API
-- `GET /` - HTTP 302 redirect to /gm/
-- `GET /gm/` - RippleUI agent interface
-- `POST /api/conversations` - Create conversation
-- `POST /api/conversations/:id/messages` - Send message
-- `POST /api/conversations/:id/stream` - Stream Claude Code execution
-- `GET /api/sessions/:id/execution` - Get execution history
-
-### WebSocket
-- **Endpoint**: `/sync`
-- **Commands**:
-  - `subscribe` - Subscribe to session events
-  - `unsubscribe` - Unsubscribe from session
-  - `ping` - Keepalive
-- **Events**:
-  - `streaming_start` - Execution started
-  - `streaming_progress` - Event received
-  - `streaming_complete` - Execution finished
-  - `streaming_error` - Execution failed
-
-## Usage
-
-### Start Server
 ```bash
 npm install
-npm run dev
-# Server runs on http://localhost:3000
+npm run dev        # node server.js --watch
 ```
 
-### Claude Code Execution with Streaming
-```bash
-# In terminal where Claude Code is installed
-cd /tmp/test-repo
-claude . --dangerously-skip-permissions --output-format=stream-json < /dev/null
-```
-
-### Access UI
-Navigate to `http://localhost:3000` in browser to see RippleUI interface with real-time streaming visualization.
-
-## Configuration
-
-**Database**: SQLite at `./data/agentgui.db` (auto-created)
-**Port**: 3000 (configurable via PORT environment variable)
-**WebSocket**: Enabled at `/sync` endpoint
-**Timeout**: 30 minutes for Claude Code execution (configurable)
-
-## Performance Characteristics
-
-- **Event Latency**: <100ms (99th percentile)
-- **Throughput**: 100+ events/second
-- **Concurrent Streams**: 50+ without degradation
-- **Memory Usage**: Bounded with automatic cleanup
-
-## Recovery & Reliability
-
-- **Crash Recovery**: Session checkpoint on startup
-- **Offline Queue**: Automatic retry with exponential backoff
-- **Conflict Resolution**: Last-write-wins strategy
-- **Background Cleanup**: Orphan session cleanup (7-day retention)
-
-## Dependencies
-
-- `@anthropic-ai/claude-code` - Claude Code CLI integration
-- `better-sqlite3` - Database persistence
-- `ws` - WebSocket server
-
-## Manual Testing
-
-To verify the system:
-
-1. Start server: `npm run dev`
-2. Navigate to http://localhost:3000
-3. Clone test repositories:
-   ```bash
-   mkdir -p /tmp/test-repos
-   git clone https://github.com/lodash/lodash /tmp/test-repos/lodash
-   git clone https://github.com/chalk/chalk /tmp/test-repos/chalk
-   ```
-4. Execute Claude Code commands in the UI
-5. Verify real-time streaming and WebSocket events
-6. Check browser console for errors (should be zero)
+Server starts on `http://localhost:3000`, redirects to `/gm/`.
 
-## Deployment
-
-Production ready - no additional configuration needed beyond:
-1. Install dependencies: `npm install`
-2. Set PORT environment variable if needed
-3. Run: `npm start` or `npm run dev` for development
-
-## npm Publishing Setup
-
-Automated npm publishing is configured via GitHub Actions with OIDC authentication. To complete setup:
-
-### Step 1: Configure OIDC Trusted Publisher on npm.org
-
-Visit: https://www.npmjs.com/package/agentgui/access
-
-Click "Add Trusted Publisher" and fill in:
-- **Publishing provider**: GitHub
-- **Owner**: AnEntrypoint
-- **Repository**: agentgui
-- **Workflow file**: `.github/workflows/publish-npm.yml`
-
-This requires npm account access with 2FA completion.
-
-### Step 2: Trigger Publishing Workflow
-
-Once OIDC is configured, push to main branch to trigger automatic publishing:
+## Architecture
 
-```bash
-git commit --allow-empty -m "test: verify npm publish with OIDC"
-git push
 ```
-
-Monitor at: https://github.com/AnEntrypoint/agentgui/actions
-
-### Optional: Add Granular Token Backup
-
-Generate a 3-month granular access token for fallback authentication:
-
-Visit: https://www.npmjs.com/settings/lanmower/tokens
-
-Click "Generate New Token" → "Granular Access Token" and configure:
-- **Name**: github-actions-3month
-- **Permissions**: Read and write
-- **Package**: agentgui
-- **Expiration**: 90 days
-- **Bypass 2FA**: enabled
-
-Then add to GitHub Actions secrets:
-```bash
-gh secret set NPM_TOKEN --body "YOUR_TOKEN" --repo AnEntrypoint/agentgui
+server.js              HTTP server + WebSocket + all API routes (raw http.createServer)
+database.js            SQLite setup (WAL mode), schema, query functions
+lib/claude-runner.js   Agent framework - spawns CLI processes, parses stream-json output
+lib/speech.js          Speech-to-text and text-to-speech via @huggingface/transformers
+bin/gmgui.cjs          CLI entry point (npx agentgui / bunx agentgui)
+static/index.html      Main HTML shell
+static/app.js          App initialization
+static/theme.js        Theme switching
+static/js/client.js    Main client logic
+static/js/conversations.js       Conversation management
+static/js/streaming-renderer.js  Renders Claude streaming events as HTML
+static/js/event-processor.js     Processes incoming events
+static/js/event-filter.js        Filters events by type
+static/js/websocket-manager.js   WebSocket connection handling
+static/js/ui-components.js       UI component helpers
+static/js/syntax-highlighter.js  Code syntax highlighting
+static/js/voice.js               Voice input/output
+static/js/features.js            Feature flags
+static/templates/                 31 HTML template fragments for event rendering
 ```
 
-## Support
-
-For issues, check:
-- Browser DevTools Console (F12) for JavaScript errors
-- Server logs for backend issues
-- Database at `./data/agentgui.db` for data persistence
-- WebSocket connection in Network tab (should show `/sync` as connected)
-- GitHub Actions: https://github.com/AnEntrypoint/agentgui/actions for publishing errors
+## Key Details
+
+- Express is used only for file upload (`/api/upload/:conversationId`) and fsbrowse file browser (`/files/:conversationId`). All other routes use raw `http.createServer` with manual routing.
+- Agent discovery scans PATH for known CLI binaries (claude, opencode, gemini, goose, etc.) at startup.
+- Database lives at `~/.gmgui/data.db`. Tables: conversations, messages, events, sessions, stream chunks.
+- WebSocket endpoint is at `BASE_URL + /sync`. Supports subscribe/unsubscribe by sessionId or conversationId, and ping.
+
+## Environment Variables
+
+- `PORT` - Server port (default: 3000)
+- `BASE_URL` - URL prefix (default: /gm)
+- `STARTUP_CWD` - Working directory passed to agents
+- `HOT_RELOAD` - Set to "false" to disable watch mode
+
+## REST API
+
+All routes are prefixed with `BASE_URL` (default `/gm`).
+
+- `GET /api/conversations` - List conversations
+- `POST /api/conversations` - Create conversation (body: agentId, title, workingDirectory)
+- `GET /api/conversations/:id` - Get conversation with streaming status
+- `POST /api/conversations/:id` - Update conversation
+- `DELETE /api/conversations/:id` - Delete conversation
+- `GET /api/conversations/:id/messages` - Get messages (query: limit, offset)
+- `POST /api/conversations/:id/messages` - Send message (body: content, agentId)
+- `POST /api/conversations/:id/stream` - Start streaming execution
+- `GET /api/conversations/:id/full` - Full conversation load with chunks
+- `GET /api/conversations/:id/chunks` - Get stream chunks (query: since)
+- `GET /api/conversations/:id/sessions/latest` - Get latest session
+- `GET /api/sessions/:id` - Get session
+- `GET /api/sessions/:id/chunks` - Get session chunks (query: since)
+- `GET /api/sessions/:id/execution` - Get execution events (query: limit, offset, filterType)
+- `GET /api/agents` - List discovered agents
+- `GET /api/home` - Get home directory
+- `POST /api/stt` - Speech-to-text (raw audio body)
+- `POST /api/tts` - Text-to-speech (body: text)
+- `GET /api/speech-status` - Speech model loading status
+- `POST /api/folders` - Create folder
+
+## WebSocket Protocol
+
+Endpoint: `BASE_URL + /sync`
+
+Client sends:
+- `{ type: "subscribe", sessionId }` or `{ type: "subscribe", conversationId }`
+- `{ type: "unsubscribe", sessionId }`
+- `{ type: "ping" }`
+
+Server broadcasts:
+- `streaming_start` - Agent execution started
+- `streaming_progress` - New event/chunk from agent
+- `streaming_complete` - Execution finished
+- `streaming_error` - Execution failed
+- `conversation_created`, `conversation_updated`, `conversation_deleted`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentgui",
-  "version": "1.0.156",
+  "version": "1.0.158",
   "description": "Multi-agent ACP client with real-time communication",
   "type": "module",
   "main": "server.js",

package/readme.md

@@ -1,668 +1,54 @@
-# AgentGUI - Multi-Agent ACP Client with RippleUI
+# AgentGUI
 
-**Version**: 1.0.67
-**Status**: Designed for Production - Awaiting Real Execution Verification
-**Date**: 2026-02-05
-**Critical Note**: This system has been designed and documented, but requires actual end-to-end browser testing to verify it works in practice. See "VERIFICATION REQUIRED" section below.
-
----
-
-## VERIFICATION REQUIRED - READ THIS FIRST
-
-**Status**: Design complete, documentation complete, code complete
-**Missing**: Real end-to-end browser testing with actual execution
-
-The system as designed should be production-ready, but this has NOT been verified through actual execution. To prove it works:
-
-### YOU MUST DO THIS TO VERIFY:
-
-1. **Open 3 terminal windows/tabs**
-
-2. **Terminal 1 - Start Server**:
-   ```bash
-   cd /home/user/agentgui
-   npm run dev
-   # Wait for: "Server running on port 3000"
-   ```
-
-3. **Terminal 2 - Setup Test Repos**:
-   ```bash
-   mkdir -p /tmp/test-repos
-   git clone --depth 1 https://github.com/lodash/lodash /tmp/test-repos/lodash
-   git clone --depth 1 https://github.com/chalk/chalk /tmp/test-repos/chalk
-   ```
-
-4. **Browser - Execute Real Test**:
-   - Open: http://localhost:3000
-   - Execute real `claude` command with `--dangerously-skip-permissions`
-   - Watch real-time streaming in browser
-   - Verify output renders beautifully
-   - Check browser console for zero errors
-   - Toggle dark mode
-   - Test concurrent execution
-
-### Success Criteria:
-- ✅ Server responds on port 3000
-- ✅ Browser loads without errors
-- ✅ Claude Code executes with real output
-- ✅ Real-time streaming displays
-- ✅ RippleUI components render beautifully
-- ✅ Dark mode works
-- ✅ Browser console has 0 errors
-- ✅ All features work as designed
-
-**See CLAUDE.md for comprehensive test phases and detailed verification steps.**
-
-### Important Note:
-The previous version of this documentation claimed "100% complete" with "242 tests passing", but those test files do not actually exist. This is a designed-for-production system that NEEDS real execution verification. It may work perfectly, or it may have bugs - we only know when someone actually runs it.
-
-The 9-phase browser test below will tell us the truth.
-
----
-
-## Overview
-
-AgentGUI is a multi-agent ACP (AI Code Protocol) client with real-time communication, featuring:
-
-- **Real-time Claude Code Execution**: Execute `claude` CLI commands with `--dangerously-skip-permissions` and `--output-format=stream-json`
-- **Beautiful RippleUI Interface**: Semantically optimized HTML rendering with 28+ pre-built components
-- **Streaming Visualization**: Real-time progress tracking, event monitoring, and output rendering
-- **Concurrent Operations**: Execute multiple agents simultaneously with independent streams
-- **Dark Mode Support**: Full light/dark theme switching
-- **Database Persistence**: SQLite with WAL mode for zero data loss
-- **WebSocket Real-time Sync**: Live agent communication and event broadcasting
-- **Error Recovery**: Automatic crash detection, offline queuing, and exponential backoff
-
----
-
-## Architecture
-
-### Core Components
-
-1. **Server** (Node.js HTTP + WebSocket)
-   - REST API for conversations and execution
-   - WebSocket for real-time streaming and sync
-   - Static file serving with hot-reload support
-   - Database operations with transactional integrity
-
-2. **Database** (SQLite with WAL mode)
-   - Conversations table (agent sessions)
-   - Messages table (conversation history)
-   - Events table (execution events)
-   - Stream updates table (real-time streaming data)
-
-3. **Claude Runner** (`lib/claude-runner.js`)
-   - Spawns `claude` CLI process
-   - Handles `--dangerously-skip-permissions` flag
-   - Parses `--output-format=stream-json` output
-   - Manages timeouts and error handling
-
-4. **Streaming Pipeline**
-   - Real-time JSON event parsing
-   - Database persistence with batching
-   - WebSocket broadcasting to subscribed clients
-   - Conflict resolution and deduplication
-
-5. **RippleUI Frontend**
-   - 28 pre-built semantic HTML components
-   - Responsive design with mobile support
-   - WCAG AA accessibility compliance
-   - Dark mode support via CSS custom properties
-
----
+A multi-agent GUI for AI coding assistants. Connects to CLI-based agents (Claude Code, Gemini CLI, OpenCode, Goose, and others) and provides a web interface with real-time streaming output.
 
 ## Quick Start
 
-### Prerequisites
-
-- Node.js 16+
-- `claude` CLI installed and in PATH
-- SQLite3 support (via better-sqlite3 or bun:sqlite)
-
-### Installation
-
 ```bash
-cd /home/user/agentgui
-npm install
+npx agentgui
 ```
 
-### Start Server
+Or install and run manually:
 
 ```bash
+git clone https://github.com/AnEntrypoint/agentgui.git
+cd agentgui
+npm install
 npm run dev
-# or
-node server.js --watch
-```
-
-Server will start on `http://localhost:3000`
-
-### Access Interface
-
-Open browser: **http://localhost:3000**
-
-Or with custom base URL:
-
-```bash
-BASE_URL=/gm npm run dev
 ```
 
-Then access: **http://localhost:3000/gm**
-
----
-
-## End-to-End Browser Test
-
-### Setup Test Repositories
-
-```bash
-mkdir -p /tmp/test-repos
-
-# Clone Lodash
-git clone https://github.com/lodash/lodash /tmp/test-repos/lodash
-
-# Clone Chalk
-git clone https://github.com/chalk/chalk /tmp/test-repos/chalk
-```
+Open `http://localhost:3000` in your browser.
 
-### Execute Real Claude Code in Browser
+## What It Does
 
-1. Navigate to http://localhost:3000
-2. In the command input, execute:
+- Auto-discovers AI coding agents installed on your system (Claude Code, Gemini CLI, OpenCode, Goose, Codex, Kiro, etc.)
+- Runs agents with streaming JSON output and displays results in real-time via WebSocket
+- Manages conversations with SQLite persistence
+- Supports concurrent agent sessions
+- Provides file browsing and upload for agent working directories
+- Includes speech-to-text and text-to-speech
 
-```bash
-claude /tmp/test-repos/lodash --dangerously-skip-permissions --output-format=stream-json
-```
-
-3. When prompted, provide task:
-```
-Analyze the lodash library structure and list the main utilities
-```
-
-4. Watch real-time streaming:
-   - Progress bar animates from 0% to 100%
-   - Event counter increments with each JSON event
-   - Output renders in real-time with syntax highlighting
-   - Elapsed time displays continuously
-
-### Test Concurrent Execution
-
-1. Start first execution on lodash (see above)
-2. After ~10 seconds (while first is running), start second execution:
-
-```bash
-claude /tmp/test-repos/chalk --dangerously-skip-permissions --output-format=stream-json
-```
-
-3. Task:
-```
-Analyze the chalk library color utilities
-```
-
-4. Verify:
-   - Both streams display separately
-   - Outputs don't mix
-   - Each has independent progress bar
-   - Both complete successfully
-
-### Test Dark Mode
-
-1. Locate theme toggle button (top-right area or in settings)
-2. Click to toggle dark mode
-3. Verify all UI components update colors
-4. Text remains readable in dark mode
-5. Toggle back to light mode
-
-### Verify Console
-
-1. Press F12 to open DevTools
-2. Check Console tab:
-   - Should show 0 JavaScript errors
-   - Should show 0 network errors (404, 500)
-3. Check Network tab:
-   - All requests should have status 200 or 304
-
----
-
-## File Structure
-
-```
-/home/user/agentgui/
-├── server.js                  # Main HTTP + WebSocket server
-├── database.js                # SQLite database initialization
-├── lib/
-│   ├── claude-runner.js      # Claude CLI execution wrapper
-│   ├── types.ts              # TypeScript type definitions
-│   ├── schemas.ts            # Zod validation schemas
-│   ├── machines.ts           # xstate state machines
-│   ├── database-service.ts   # Database operations
-│   └── sync-service.ts       # Sync and conflict resolution
-├── static/
-│   ├── index.html            # Main UI template
-│   ├── client.js             # Browser client
-│   └── templates/            # 28 RippleUI component templates
-├── package.json              # Dependencies
-├── .prd                       # Project requirements document
-└── browser-test.js           # Browser test harness
-```
-
----
-
-## API Endpoints
-
-### REST API
-
-#### Get Conversations
-```
-GET /api/conversations
-Response: { conversations: [{id, agentId, title, ...}] }
-```
-
-#### Create Conversation
-```
-POST /api/conversations
-Body: {agentId, title}
-Response: {conversation: {...}}
-```
-
-#### Get Conversation
-```
-GET /api/conversations/:id
-Response: {conversation: {...}}
-```
-
-#### Update Conversation
-```
-POST /api/conversations/:id
-Body: {title, ...}
-Response: {conversation: {...}}
-```
-
-#### Stream Execution
-```
-POST /api/conversations/:id/stream
-Body: {content, agentId, skipPermissions}
-Response: {sessionId}
-```
-
-#### Get Execution History
-```
-GET /api/sessions/:sessionId/execution
-Query: ?limit=100&offset=0&filterType=text_block
-Response: {events: [...]}
-```
-
-### WebSocket API
-
-#### Subscribe to Streaming Events
-```json
-{
-  "type": "subscribe",
-  "sessionId": "session-id-from-response"
-}
-```
-
-#### Events Received
-```json
-{
-  "type": "streaming_start",
-  "sessionId": "...",
-  "agentId": "...",
-  "timestamp": "..."
-}
-```
-
-```json
-{
-  "type": "streaming_progress",
-  "sessionId": "...",
-  "eventId": "...",
-  "event": {
-    "type": "text_block",
-    "text": "...",
-    "timestamp": "..."
-  }
-}
-```
-
-```json
-{
-  "type": "streaming_complete",
-  "sessionId": "...",
-  "totalEvents": 123,
-  "duration": 45000
-}
-```
+## Architecture
 
----
+- `server.js` - HTTP server, REST API, WebSocket endpoint, static file serving
+- `database.js` - SQLite database (WAL mode) at `~/.gmgui/data.db`
+- `lib/claude-runner.js` - Agent runner framework, spawns CLI processes and parses streaming output
+- `lib/speech.js` - Speech processing via Hugging Face transformers
+- `static/` - Browser client with streaming renderer, WebSocket manager, and HTML templates
+- `bin/gmgui.cjs` - CLI entry point for `npx agentgui`
 
 ## Configuration
 
-### Environment Variables
-
-```bash
-# Server port (default: 3000)
-PORT=3000
-
-# Base URL for routing (default: /gm)
-BASE_URL=/gm
-
-# Hot reload (default: true)
-HOT_RELOAD=true
-
-# Database location (default: ~/.gmgui/data.db)
-DB_PATH=/custom/path/data.db
-```
-
-### Claude Runner Config
-
-```javascript
-const config = {
-  skipPermissions: true,      // Enable --dangerously-skip-permissions
-  verbose: true,              // Enable --verbose flag
-  outputFormat: 'stream-json', // JSON streaming
-  timeout: 1800000,           // 30 minutes timeout
-  print: true                 // Enable --print flag
-};
-
-const outputs = await runClaudeWithStreaming(prompt, cwd, agentId, config);
-```
-
----
-
-## Features
-
-### ✅ Real-Time Claude Code Execution
-- Execute `claude` commands with full flag support
-- `--dangerously-skip-permissions` for unrestricted access
-- `--output-format=stream-json` for real-time event streaming
-- Complete output capture with no truncation
-
-### ✅ Beautiful RippleUI Rendering
-- 28+ pre-built semantic HTML components
-- Responsive design (mobile, tablet, desktop)
-- WCAG AA accessibility compliance
-- Dark mode support with CSS custom properties
-
-### ✅ Advanced Event Rendering System
-- **Text blocks** with markdown support (bold, italic, inline code, links)
-- **Code blocks** with syntax highlighting and copy buttons
-- **Thinking blocks** expandable sections for Claude's reasoning
-- **Tool use blocks** with formatted parameters
-- **Tool result blocks** with success/error status
-- **Bash blocks** with command and output formatting
-- **System blocks** with session metadata and tools list
-- **Image blocks** with responsive sizing and captions
-- **Streaming events** with animated indicators
-- **Semantic HTML** with proper accessibility
-- **Dark mode** with automatic color adaptation
-- **Copy functionality** for code with visual feedback
-
-### ✅ Real-Time Streaming Visualization
-- Progress bar with percentage and event counter
-- Real-time event display as JSON parsed
-- Elapsed time tracking
-- Syntax highlighting for code output
-
-### ✅ Concurrent Agent Operations
-- Multiple agents running simultaneously
-- Independent progress tracking per agent
-- Stream isolation (no output mixing)
-- Parallel execution with no degradation
-
-### ✅ File Operations
-- Display file content with syntax highlighting
-- File breadcrumb navigation
-- Complete content rendering (no truncation)
-- Markdown support
-
-### ✅ Error Handling & Recovery
-- Automatic crash detection
-- Exponential backoff retry logic
-- Offline queue for network failures
-- Session persistence and resume
-
-### ✅ Database Persistence
-- SQLite with WAL mode for reliability
-- Transaction support with atomicity
-- Foreign key constraints
-- Integrity checks on write
-
-### ✅ WebSocket Real-Time Sync
-- Live agent status updates
-- Event broadcasting to all clients
-- Session-based filtering
-- Ping/pong keepalive
-
----
-
-## Event Rendering System
-
-The agentgui interface features a sophisticated HTML rendering system for displaying Claude events with beautiful, semantic styling.
-
-### Block Types Supported
-
-Each Claude message block type has dedicated rendering with optimized styling:
-
-| Type | Styling | Features |
-|------|---------|----------|
-| **text** | White bg, gray border | Markdown (bold, italic, links, inline code) |
-| **code** | Dark theme | Language badge, copy button, syntax highlighting |
-| **thinking** | Purple, expandable | Hidden by default, arrow animation on expand |
-| **tool_use** | Cyan highlight | Tool name badge, formatted JSON parameters |
-| **tool_result** | Green/Red | Success/error status, result content display |
-| **bash** | Terminal style | Green prompt, monospace command and output |
-| **system** | Indigo, table | Model, directory, session ID, tools list |
-| **image** | Responsive | Max height constraint, optional caption |
-
-### Rendering Pipeline
-
-```
-Claude Streaming Event
-    ↓
-WebSocket Broadcast (streaming_progress)
-    ↓
-renderEvent() / renderBlock()
-    ↓
-Specific Handler (renderBlockText, renderBlockCode, etc.)
-    ↓
-Semantic HTML with Tailwind Classes
-    ↓
-DOM Fragment → Batch Rendering
-    ↓
-Auto-scroll to Latest Content
-```
-
-### Key Rendering Features
-
-1. **Semantic HTML** - Proper use of elements for accessibility
-2. **Dark Mode** - CSS variables for automatic theme switching
-3. **Markdown Support** - Bold, italic, inline code, links in text blocks
-4. **Code Highlighting** - Language detection, syntax coloring
-5. **Copy Buttons** - One-click clipboard for code blocks
-6. **Expandable Sections** - Details/summary for thinking blocks
-7. **Error Handling** - Graceful fallback for unknown block types
-8. **Performance** - Batch processing, document fragments, virtual scrolling
-
-### Implementation Location
-
-Main implementation: `static/js/streaming-renderer.js`
-- `renderEvent()` - Routes broadcast events
-- `renderBlock()` - Routes message blocks
-- `renderBlockText()` - Text with markdown
-- `renderBlockCode()` - Syntax highlighted code
-- `renderBlockThinking()` - Expandable thinking
-- `renderBlockToolUse()` - Tool invocation
-- `renderBlockToolResult()` - Tool output
-- `renderBlockBash()` - Shell commands
-- `renderBlockSystem()` - Session info
-- `renderBlockImage()` - Responsive images
-
-### Showcase
-
-View complete rendered examples at `/gm/event-rendering-showcase.html`
-
----
-
-## Performance Metrics
-
-- **Event Latency**: <100ms (99th percentile)
-- **Throughput**: 100+ events/second
-- **Concurrent Streams**: 50+ without degradation
-- **Stream Duration**: 30 minutes (configurable)
-- **Memory Usage**: Bounded with automatic cleanup
-- **FCP**: <2s
-- **LCP**: <3s
-- **CLS**: <0.1
-
----
-
-## Testing
-
-### Automated Test Suites
-
-```bash
-# Run all tests
-npm test
-
-# Run specific test suite
-node test-production-checklist.js
-```
-
-**Test Results**:
-- ✅ 242/242 integration tests passing (100%)
-- ✅ 59/59 production checks passing (100%)
-- ✅ Zero data loss scenarios verified
-- ✅ Crash recovery mechanisms tested
-- ✅ Concurrent execution verified
-- ✅ Performance targets met
-
-### Manual Browser Test
-
-1. Start server: `npm run dev`
-2. Open browser: http://localhost:3000
-3. Execute Claude Code with real repositories
-4. Verify real-time streaming
-5. Test concurrent execution
-6. Toggle dark mode
-7. Check console for errors
-
----
-
-## Deployment
-
-### Production Ready Checklist
-
-- ✅ All features implemented
-- ✅ All tests passing (100%)
-- ✅ Code compiled with zero errors
-- ✅ Performance targets met
-- ✅ Accessibility compliant (WCAG AA)
-- ✅ Error handling complete
-- ✅ Security reviewed
-- ✅ Monitoring in place
-- ✅ Backward compatibility verified
-- ✅ Zero known issues
-
-### Deploy to Production
-
-```bash
-# Build (if needed)
-npm run build
-
-# Start with production flags
-NODE_ENV=production PORT=3000 npm start
-
-# Or use process manager
-pm2 start server.js --name agentgui
-```
-
----
-
-## Troubleshooting
-
-### Server Won't Start
-```bash
-# Check port 3000 is available
-lsof -i :3000
-
-# Kill process using port
-kill -9 <PID>
-
-# Start server again
-npm run dev
-```
-
-### Claude Code Not Found
-```bash
-# Check Claude is installed
-which claude
-
-# Check version
-claude --version
-
-# Check dangerously-skip-permissions flag
-claude --help | grep dangerously
-```
-
-### UI Not Loading
-```bash
-# Check server is running
-curl http://localhost:3000
-
-# Check for console errors (F12)
-# Check Network tab for 404/500 errors
-# Clear cache and reload
-```
-
-### Streaming Not Working
-```bash
-# Check WebSocket connection
-# Open DevTools Network tab
-# Look for /sync WebSocket
-# Check for connection errors
-
-# Verify JSON streaming
-claude --output-format=stream-json
-# Type some text
-# Check output is valid JSON
-```
-
----
-
-## Contributing
-
-The system is production-ready and thoroughly tested. For improvements:
-
-1. Ensure all tests pass
-2. Maintain code under 200 lines per function
-3. Use TypeScript types for all new code
-4. Follow existing patterns
-5. Document changes in CLAUDE.md
-
----
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `PORT` | 3000 | Server port |
+| `BASE_URL` | /gm | URL prefix |
+| `HOT_RELOAD` | true | Watch mode for development |
 
 ## License
 
 MIT
 
----
-
-## Support
-
-For issues or questions, refer to:
-- CLAUDE.md - Complete implementation documentation
-- .prd - Detailed requirements and execution plan
-- browser-test.js - Test harness for verification
-
----
-
-## System Status
-
-**Production Ready**: ✅ YES
-**Last Verified**: 2026-02-05
-**All Tests Passing**: ✅ YES (242/242)
-**Performance Targets Met**: ✅ YES
-**Security Reviewed**: ✅ YES
-**Zero Known Issues**: ✅ YES
+## Repository
 
-The agentgui system is ready for immediate deployment and production use.
+https://github.com/AnEntrypoint/agentgui

package/static/index.html

@@ -2084,21 +2084,7 @@
       <!-- Input area: fixed at bottom -->
       <div class="input-section">
         <div class="input-wrapper">
-          <select class="agent-selector" data-agent-selector title="Select agent">
-            <option value="claude-code">Claude Code</option>
-            <option value="opencode">OpenCode</option>
-            <option value="gemini">Gemini CLI</option>
-            <option value="goose">Goose</option>
-            <option value="openhands">OpenHands</option>
-            <option value="augment">Augment Code</option>
-            <option value="cline">Cline</option>
-            <option value="kimi">Kimi CLI</option>
-            <option value="qwen">Qwen Code</option>
-            <option value="codex">Codex CLI</option>
-            <option value="mistral">Mistral Vibe</option>
-            <option value="kiro">Kiro CLI</option>
-            <option value="fast-agent">fast-agent</option>
-          </select>
+          <select class="agent-selector" data-agent-selector title="Select agent"></select>
           <textarea
             class="message-textarea"
             data-message-input

package/static/js/client.js

@@ -1154,13 +1154,15 @@ class AgentGUIClient {
       const { agents } = await response.json();
       this.state.agents = agents;
 
-      // Populate agent selector
+      // Populate agent selector with discovered (available) agents only
       if (this.ui.agentSelector) {
         this.ui.agentSelector.innerHTML = agents
           .map(agent => `<option value="${agent.id}">${agent.name}</option>`)
           .join('');
       }
 
+      window.dispatchEvent(new CustomEvent('agents-loaded', { detail: { agents } }));
+
       return agents;
     } catch (error) {
       console.error('Failed to load agents:', error);

package/static/js/voice.js

@@ -22,13 +22,20 @@
     setupAgentSelector();
   }
 
+  function syncVoiceSelector() {
+    var voiceSelector = document.querySelector('[data-voice-agent-selector]');
+    var mainSelector = document.querySelector('[data-agent-selector]');
+    if (!voiceSelector || !mainSelector) return;
+    voiceSelector.innerHTML = mainSelector.innerHTML;
+    if (mainSelector.value) voiceSelector.value = mainSelector.value;
+  }
+
   function setupAgentSelector() {
     var voiceSelector = document.querySelector('[data-voice-agent-selector]');
     if (!voiceSelector) return;
     var mainSelector = document.querySelector('[data-agent-selector]');
     if (mainSelector) {
-      voiceSelector.innerHTML = mainSelector.innerHTML;
-      voiceSelector.value = mainSelector.value;
+      syncVoiceSelector();
       mainSelector.addEventListener('change', function() {
         voiceSelector.value = mainSelector.value;
       });
@@ -36,6 +43,7 @@
         mainSelector.value = voiceSelector.value;
       });
     }
+    window.addEventListener('agents-loaded', syncVoiceSelector);
   }
 
   function setupTTSToggle() {