[WIP] Add browser mode for Cletus with react client

[Copilot]

Browser Mode Implementation - Complete ✅

Successfully implemented --browser mode for Cletus with a React-based web UI!

Features Implemented

• Browser Mode Flag: Added --browser and --port CLI arguments
• HTTP Server: Node.js HTTP server serving static files with secure path handling
• WebSocket Support: Real-time bidirectional communication for chat operations
• React Client: Modern, responsive web UI built with React
• Server-Side Operations: All AI operations and file I/O run server-side via WebSocket
• Reusable Architecture: Leverages existing Cletus logic (ConfigFile, ChatFile, AI components)
• TypeScript: Strict typing throughout, no any/unknown usage
• Component Structure: Well-organized, split into small focused components
• Security: Path traversal protection, localhost-only binding by default

Architecture

Server (src/browser/server.ts):

• HTTP server for static file serving with secure path resolution
• WebSocket server for real-time chat communication
• API endpoints for config and chat data
• Lazy-loads AI components to avoid startup delays
• Binds to 127.0.0.1 (localhost only) for security

Client (src/browser/client/):

• Pages: InitPage, MainPage (chat list + settings), ChatPage
• Components: Sidebar, ChatList, ChatHeader, MessageList, MessageItem, ChatInput, OperationDisplay, Collapsible, SettingsView
• Styling: CSS with dark/light mode support

Screenshots

Initialization Page (when no config exists):

Usage

# Start browser mode (binds to localhost:3000 by default)
cletus --browser

# Specify custom port
cletus --browser --port 8080

Technical Notes

• Operations run server-side with results streamed via WebSocket
• Operation input/output displayed in collapsible sections
• Static files served from dist-browser/ directory
• No server-side rendering needed - fully client-side React app
• WebSocket handles: chat initialization, message sending, status updates, streaming responses
• Secure path resolution prevents directory traversal attacks

Build Process

• Main CLI: esbuild.config.cjs → dist/index.js
• Browser client: esbuild.browser.cjs → dist-browser/
• Both built with npm run build

Security

• ✅ CodeQL scan: No vulnerabilities found
• ✅ Path traversal protection with resolved absolute paths
• ✅ Localhost-only binding by default
• ✅ No any/unknown TypeScript usage
• ✅ Lazy loading of optional dependencies (sharp)

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Cletus: Add --browser mode</issue_title>
<issue_description>When specified - instead of a CLI it launches a HTTP server & react client with a fancier UI for initialization, settings, chats, chat interface, and looking at all message & operation input & output. The operation input & output should be in collapsible sections. The react client app should be slick and responsive with a really good UX. The development should split out components very heavily to avoid massive files. The development should be done in a browser folder - leaving the existing code as untouched as possible. The client code should have the ability to have operation specific rendering just like what's in the CLI client in the operations folder. Since this is local there's not much use for having any server side functionality - if a server is avoidable at all that's fine. Use good TypeScript practices - use the existing types. Don't use any/unknown or forceful casting.</issue_description>

Comments on the Issue (you are @copilot in this section)

Custom agent used: Cletus-Developer
An agent that understands the cletus package.

• Fixes Cletus: Add --browser mode #157

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.