agentgui 1.0.155 → 1.0.157

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