agentgui 1.0.851 → 1.0.853

package/.codeinsight

@@ -0,0 +1,102 @@
+## 🎯 agentgui v1.0.811 — Multi-agent ACP client with real-time communication
+
+**Runtime:** node (pnpm)
+
+## 🚀 Quick Start
+
+`node server.js --watch`
+
+# 103f 27.9kL 1343fn 31cls cx2.6
+*Legend: f=files L=lines fn=functions cls=classes cx=avg-complexity | file:line:name(NL)=location Np=params | ↑N=imports-from ↓N=imported-by (N)=occurrences (+N)=more | 🔄circular 🏝️isolated 🔥complex 📋duplicated 📁large*
+
+**Langs:** JS:99% JSON:0%
+
+## 🛠️ Tech Stack
+
+**Stack:** Express, Zod
+**Patterns:** Date.now(335), sendJSON(225), prep(185), this.escapeHtml(157), document.createElement(142), broadcastSync(140)
+**Top IDs:** type(839), data(811), error(724), conversationId(624), message(572), req(563)
+
+## ⚡ Code Patterns
+
+**Async:** async(622), await(270), Promise(15)
+**Errors:** try/catch(457), throw(120)
+**Internal calls:** Date.now(335), sendJSON(225), prep(185), this.escapeHtml(157), document.createElement(142), broadcastSync(140), document.getElementById(138), assign(106)
+
+## 🔗 I/O & Integration
+
+**Env vars:** AGENTGUI_BASE_URL, BASE_URL, BUN_BE_BUN, BUN_INSTALL, CODEX_HOME, DEBUG, GITHUB_USER, GOOGLE_OAUTH_CLIENT_ID, GOOGLE_OAUTH_CLIENT_SECRET, HOME, HOT_RELOAD, NPM_CACHE, PASSWORD, PORT, PORTABLE_DATA_DIR, PORTABLE_EXE_DIR, RATE_LIMIT_MAX, SHELL, STARTUP_CWD, _, npm_config_cache, npm_execpath
+**HTTP:** fetch(29)
+**Storage:** SQL(204), files(240), JSON(175)
+**Events:** emit(48), listen(289)
+
+## 📊 Code Organization
+
+**Large files:** js/client.js:3479L, server.js:3407L, js/streaming-renderer.js:2422L, lib/db-queries.js:1412L, lib/claude-runner.js:1266L, static/app.js:968L (+17)
+**Long funcs:** lib/db-queries.js:3:createQueries(1410L), server.js:1838:processMessageWithStreaming(539L), js/client.js:2798:loadConversationMessages(284L), lib/ws-handlers-conv.js:19:register(264L), lib/claude-runner.js:276:_runACPOnce(261L), js/client.js:439:setupUI(233L) (+71)
+**Many params:** lib/db-queries.js:3:createQueries(101p), lib/ws-handlers-run.js:4:register(31p), lib/routes-tools.js:3:register(27p), acp-queries.js:8:createACPQueries(24p), lib/ws-handlers-conv.js:19:register(21p), lib/ws-handlers-util.js:9:register(20p) (+31)
+**Classes:** lib/pm2-manager.js:0:PM2Manager, lib/plugin-loader.js:0:PluginLoader, lib/claude-runner.js:0:AgentRunner, lib/claude-runner.js:0:AgentRegistry, lib/checkpoint-manager.js:0:CheckpointManager, lib/ws-protocol.js:0:WsRouter, js/syntax-highlighter.js:0:SyntaxHighlighter, js/image-loader.js:0:ImageLoader (+16)
+
+## 🔄 Architecture
+
+**L0 [pure exports]:** tool-install-machine(7↓), execution-machine(5↓), tool-version(4↓), agent-discovery(4↓), oauth-common(4↓), speech(3↓), codec(3↓), acp-server-machine(3↓) (+15)
+**L3 [pure imports]:** server(43↑), agent-registry-configs(1↑)
+**Cross-module:** server.js→lib, server.js→database.js, database.js→lib
+**Hubs:** server(43↑0↓), tool-install-machine(0↑7↓), tool-manager(4↑1↓), routes-oauth(4↑1↓), execution-machine(0↑5↓)
+**External:** xstate, module, bun:sqlite, zod, ws, lru-cache
+
+## 🔌 API Surface
+
+**Exported fns:** claude-runner.js:1196:runClaudeWithStreaming(1p), speech.js:9:ttsCacheKey(1p), speech.js:13:ttsCacheGet(1p), speech.js:17:ttsCacheSet(1p), ws-handlers-run.js:4:register(31p)
+**Classes:** PM2Manager, PluginLoader, AgentRunner, AgentRegistry, CheckpointManager, WsRouter (+18)
+**Entry files:** ws-handlers-run, routes-threads, tool-install-machine, claude-runner, agent-descriptors (+18)
+
+## 🚨 Issues
+
+- 🔥 Complex funcs: db-queries.js:3:createQueries(1410L), server.js:1838:processMessageWithStreaming(539L), client.js:2798:loadConversationMessages(284L), ws-handlers-conv.js:19:register(264L) (+24)
+- 📁 Large files: lib/db-queries.js:1412L, lib/claude-runner.js:1266L, server.js:3407L (+7)
+- 📋 80 duplicated groups
+- 🔐 hardcoded secrets in server.js:1760
+- 🔐 SQL injection in acp-queries.js:142, acp-queries.js:143, acp-queries.js:176, acp-queries.js:177, db-queries.js:479, db-queries.js:480 (+2)
+
+## 🧹 Dead Code & Tests
+
+**Orphaned:** git-plugin.js, state-barrier.js, copy-vendor.js, dialogs.js, recording-machine.js, pm2-monitor.js (+46)
+**Tests:** 0/103 (0%)
+
+## 📦 Modules
+
+- lib: 58f, 111cx, 34↑77↓
+- static: 35f, 0cx, 0↑0↓
+- bin: 1f, 0cx, 0↑0↓
+- electron: 1f, 0cx, 0↑0↓
+- scripts: 3f, 0cx, 0↑0↓
+
+## 📄 File Index
+
+**acp-queries.js** 182L fn: createACPQueries, createThread, getThread, patchThread (+17)
+**bin/gmgui.cjs** 79L fn: gmgui
+**database.js** 650L fn: getDataDir, initSchema, migrateFromJson, migrateToACP (+2)
+**ecosystem.config.cjs** 22L exports: [script], [interpreter], [watch], [env], [apps]
+**electron/main.js** 83L fn: startServer, pollReady, attempt, createWindow
+**lib/acp-protocol.js** 91L fn: normalizeContentBlock, extractToolResultContent, handleSessionUpdate, createACPProtocolHandler
+**lib/acp-sdk-manager.js** 199L fn: log, resolveCommand, resetIdleTimer, clearIdleTimer (+14)
+**lib/acp-server-machine.js** 166L fn: calcBackoff, purgeOldRestarts, getOrCreate, get (+6)
+**lib/agent-descriptors.js** 47L fn: buildDescriptor, initializeDescriptors, getAgentDescriptor, getAllDescriptors
+**lib/agent-discovery.js** 168L fn: findCommand, queryACPServerAgents, discoverAgents, discoverExternalACPServers (+1)
+**lib/agent-registry-configs.js** 125L fn: parseClaudeOutput, registerAllAgents, buildArgs, buildArgs
+**lib/checkpoint-manager.js** 182L exports: [CheckpointManager] fn: constructor, loadCheckpoint, injectCheckpointEvents, copyCheckpointChunks (+5)
+**lib/claude-runner.js** 1266L exports: [runClaudeWithStreaming] fn: getSpawnOptions, resolveCommand, constructor, defaultBuildArgs (+23)
+**lib/codec.js** 4L fn: encode, decode
+**lib/db-queries.js** 1412L fn: createQueries, createConversation, getConversation, getAllConversations (+90)
+**lib/execution-machine.js** 182L fn: notifyListeners, getOrCreate, get, remove (+8)
+**lib/gm-agent-configs.js** 77L fn: log, runInstaller, installGMAgentConfigs, forceReinstallGMAgentConfigs
+**lib/jsonl-watcher.js** 253L fn: constructor, start, stop, removeConversation (+13)
+**lib/model-download-machine.js** 107L fn: getActor, send, snapshot, isDownloading (+4)
+**lib/oauth-codex.js** 164L exports: [CODEX_AUTH_FILE], [CODEX_HOME] fn: generatePkce, parseJwtEmail, saveCodexCredentials, getCodexOAuthStatus (+5)
+*+83 more files*
+
+Git: branch: main, 1 uncommitted
+Hot: package.json(50), server.js(18), client.js(10), index.html(6), db-queries.js(6), main.css(5)
+Tooling: GitHub Actions (build-platforms.yml, docker-publish.yml, gh-pages.yml, publish-release.yml), Docker
+Conv[JS]: 4-space, single quotes, semicolons, named exports, relative imports, kebab-case files

package/CLAUDE.md

@@ -464,6 +464,25 @@ CSS custom properties for code/thinking blocks live in `static/css/main.css`:
 
 `parseAndRenderMarkdown()` in `streaming-renderer.js` handles: `##`/`###` headers, `-`/`*` ul lists, `1.` ol lists, `>` blockquotes, `---` hr, inline bold/italic/code/links via `_mdInline()`. Thinking block content is rendered through this function.
 
+## README.md Documentation
+
+**GitHub Badges and Metrics:**
+
+The README.md uses shields.io badges with a consistent pattern:
+- **Header badges** (lines 7-9): Star count, last commit, latest release — each links to corresponding GitHub page
+- **GitHub Stats table** (lines 54-62): Detailed metrics (stars, forks, watchers, issues, activity) — each badge links to its resource page
+- **All badges use:** `style=flat-square`, `color=blue`, dynamic data (no hardcoded values)
+
+**Debug API section** (lines 174-192):
+- Documents `DEBUG=1` environment variable for state inspection
+- Lists `/api/debug/*` endpoints: machines, state, ws-stats
+- Lists browser console `window.__debug` properties with purpose
+- Links to CLAUDE.md for complete architecture documentation
+
+**Approach validated:** Header badges are compact (visual prominence); stats table is detailed (discoverability). Non-redundant, no duplicate metrics, complementary visibility.
+
+**For future observability improvements:** Use shields.io with the established pattern (flat-square, color=blue, dynamic endpoints). Link badges to corresponding GitHub resource pages. Document in README alongside the badge.
+
 ## Known Gotchas
 
 - **`agent-browser --version`** prints help, not version. Use `-V` flag.

package/README.md

@@ -4,6 +4,9 @@
 [![npm downloads](https://img.shields.io/npm/dw/agentgui?color=brightgreen)](https://www.npmjs.com/package/agentgui)
 [![license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 [![GitHub Pages](https://img.shields.io/badge/docs-live-blue)](https://anentrypoint.github.io/agentgui/)
+[![GitHub stars](https://img.shields.io/github/stars/AnEntrypoint/agentgui?color=blue&style=flat-square)](https://github.com/AnEntrypoint/agentgui/stargazers)
+[![GitHub last-commit](https://img.shields.io/github/last-commit/AnEntrypoint/agentgui?style=flat-square)](https://github.com/AnEntrypoint/agentgui/commits)
+[![GitHub release](https://img.shields.io/github/v/release/AnEntrypoint/agentgui?style=flat-square)](https://github.com/AnEntrypoint/agentgui/releases)
 
 Multi-agent GUI client for AI coding agents with real-time streaming, WebSocket sync, and SQLite persistence.
 
@@ -48,6 +51,16 @@ Modern AI coding requires juggling multiple agents, each in their own terminal.
 - 📁 **File Browser** - Drag-and-drop uploads, direct file editing, and context-aware operations
 - 🔌 **Developer Friendly** - Hot reload, REST API, WebSocket endpoints, and extensible plugin system
 
+## GitHub Stats
+
+| Metric | Badge |
+|--------|-------|
+| **Stars** | [![GitHub stars](https://img.shields.io/github/stars/AnEntrypoint/agentgui?color=blue&style=flat-square)](https://github.com/AnEntrypoint/agentgui/stargazers) |
+| **Forks** | [![GitHub forks](https://img.shields.io/github/forks/AnEntrypoint/agentgui?color=blue&style=flat-square)](https://github.com/AnEntrypoint/agentgui/network/members) |
+| **Watchers** | [![GitHub watchers](https://img.shields.io/github/watchers/AnEntrypoint/agentgui?color=blue&style=flat-square)](https://github.com/AnEntrypoint/agentgui/watchers) |
+| **Open Issues** | [![GitHub issues](https://img.shields.io/github/issues/AnEntrypoint/agentgui?color=blue&style=flat-square)](https://github.com/AnEntrypoint/agentgui/issues) |
+| **Activity** | [![GitHub last-commit](https://img.shields.io/github/last-commit/AnEntrypoint/agentgui?style=flat-square)](https://github.com/AnEntrypoint/agentgui/commits) |
+
 ### Screenshots
 
 | Light Mode | Dark Mode |
@@ -156,6 +169,27 @@ All routes prefixed with `/gm`:
 - `BASE_URL` - URL prefix (default: /gm)
 - `STARTUP_CWD` - Working directory passed to agents
 - `HOT_RELOAD` - Enable watch mode (default: true)
+- `DEBUG` - Enable internal state inspection endpoints (set to `1`)
+
+## Debug API
+
+When `DEBUG=1` is set, internal state inspection endpoints become available:
+
+**Endpoints:**
+- `GET /api/debug/machines` - Inspect all XState v5 machine snapshots (execution, acp-server, tool-install states)
+- `GET /api/debug/state` - Full server state dump (connections, queues, active sessions)
+- `GET /api/debug/ws-stats` - WebSocket connection metrics and lag distribution
+
+**Browser Console** (`window.__debug`):
+- `window.__debug.convMachineStates` - Per-conversation UI state machines
+- `window.__debug.toolInstallMachineStates` - Tool installation state
+- `window.__debug.voiceMachineState` - TTS playback state
+- `window.__debug.convListMachineState` - Conversation list machine
+- `window.__debug.promptMachineState` - Prompt area state
+- `window.__debug.wsConnectionState` - WebSocket connection status
+- `window.__debug.getSyncState()` - Full snapshot of all machines at once
+
+See [CLAUDE.md](CLAUDE.md) for complete XState v5 machine documentation and internal architecture details.
 
 ## Troubleshooting
 

package/bash.exe.stackdump

@@ -0,0 +1,28 @@
+Stack trace:
+Frame         Function      Args
+0007FFFFAE00  00021005FEBA (000210285F48, 00021026AB6E, 000000000000, 0007FFFF9D00) msys-2.0.dll+0x1FEBA
+0007FFFFAE00  0002100467F9 (000000000000, 000000000000, 000000000000, 0007FFFFB0D8) msys-2.0.dll+0x67F9
+0007FFFFAE00  000210046832 (000210285FF9, 0007FFFFACB8, 000000000000, 000000000000) msys-2.0.dll+0x6832
+0007FFFFAE00  000210068F86 (000000000000, 000000000000, 000000000000, 000000000000) msys-2.0.dll+0x28F86
+0007FFFFAE00  0002100690B4 (0007FFFFAE10, 000000000000, 000000000000, 000000000000) msys-2.0.dll+0x290B4
+0007FFFFB0E0  00021006A49D (0007FFFFAE10, 000000000000, 000000000000, 000000000000) msys-2.0.dll+0x2A49D
+End of stack trace
+Loaded modules:
+000100400000 bash.exe
+7FFD0A9A0000 ntdll.dll
+7FFD088E0000 KERNEL32.DLL
+7FFD08270000 KERNELBASE.dll
+7FFD0A520000 USER32.dll
+000210040000 msys-2.0.dll
+7FFD08670000 win32u.dll
+7FFD09E60000 GDI32.dll
+7FFD07270000 gdi32full.dll
+7FFD07D80000 msvcp_win.dll
+7FFD07E30000 ucrtbase.dll
+7FFD09050000 advapi32.dll
+7FFD089B0000 msvcrt.dll
+7FFD0A460000 sechost.dll
+7FFD08740000 RPCRT4.dll
+7FFD06870000 CRYPTBASE.DLL
+7FFD07C10000 bcryptPrimitives.dll
+7FFD09530000 IMM32.DLL

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentgui",
-  "version": "1.0.851",
+  "version": "1.0.853",
   "description": "Multi-agent ACP client with real-time communication",
   "type": "module",
   "main": "electron/main.js",

package/.gm/prd.yml

@@ -1,784 +0,0 @@
-# AgentGUI UI Redesign - Research & Implementation Plan
-
-## Research Phase Complete
-- Analyzed current design: sidebar-based chat with basic styling
-- Researched competitors: ChatGPT, Claude.ai, GitHub Copilot, Cursor, Continue.dev
-- Identified modern patterns and best practices
-- Ready for implementation
-
-## Design Goals
-1. **Visual Polish**: Modern, professional appearance matching tier-1 AI tools
-2. **Usability**: Clearer information hierarchy, better discoverability
-3. **Performance**: Improved responsive design, smooth animations
-4. **Accessibility**: Enhanced keyboard navigation and screen reader support
-5. **Semantic Design**: Color and typography reflecting functionality
-
----
-
-## UI Redesign Items
-
-- id: header-redesign
-  subject: Redesign main header with better visual hierarchy
-  status: pending
-  description: |
-    Current header is minimal. Redesign to include:
-    - Large, bold title with app icon/logo
-    - Agent/model selector dropdown in header
-    - Connection status indicator (green dot, animated pulse when connecting)
-    - Theme toggle button (sun/moon icon)
-    - Settings/help buttons in top-right
-    - Breadcrumb navigation for conversations
-    Currently at line 100-115 of index.html
-  effort: medium
-  category: feature
-  blocking: []
-  blockedBy: []
-  acceptance:
-    - Header includes all 6 elements
-    - Status indicator animates on reconnect
-    - Mobile responsive (collapses to hamburger)
-  edge_cases:
-    - Long conversation titles truncate with ellipsis
-    - Status indicator visible in both light/dark modes
-
-- id: sidebar-redesign
-  subject: Modernize sidebar with better visual separation and interactions
-  status: pending
-  description: |
-    Current sidebar is functional but dated. Redesign to:
-    - Add conversation avatars (colored circles with initials or emoji)
-    - Show preview text of last message in each conversation
-    - Add timestamp (e.g., "2 hours ago")
-    - Better visual hover states (subtle background change)
-    - Conversation metadata badges (unread count, favorite star)
-    - Improved search with fuzzy matching and recent filtering
-    - Floating action buttons instead of text buttons
-    Currently at lines 49-85 of index.html
-  effort: large
-  category: feature
-  blocking: []
-  blockedBy: []
-  acceptance:
-    - Each conversation shows avatar, title, preview, timestamp
-    - Hover states provide clear feedback
-    - Search filters by title and preview text
-    - Mobile sidebar can be swiped away
-  edge_cases:
-    - New conversations show placeholder states
-    - Search results update in real-time
-    - Avatar generation consistent for same agent
-
-- id: message-bubbles-upgrade
-  subject: Redesign message rendering with distinct visual styling
-  status: pending
-  description: |
-    Current messages are plain text. Redesign to:
-    - User messages: Right-aligned, blue bubble, rounded corners
-    - Agent messages: Left-aligned, gray bubble, rounded corners
-    - Add small agent avatar before agent messages
-    - Add timestamp and sender name above messages
-    - Better code block styling with language badges
-    - Streaming animation (blinking cursor, progressive reveal)
-    - Message actions (copy, regenerate, delete) on hover
-    - Thinking blocks styled with purple accent color
-    Currently in js/streaming-renderer.js and css/main.css
-  effort: large
-  category: feature
-  blocking: []
-  blockedBy: []
-  acceptance:
-    - User/agent messages visually distinct
-    - Avatars render with agent color
-    - Code blocks include language badge and copy button
-    - Thinking blocks clearly marked with purple
-    - Streaming text shows cursor animation
-  edge_cases:
-    - Very long messages have proper text wrapping
-    - Code blocks with large content have scrollable container
-    - Multiple images in message render as grid
-
-- id: chat-input-redesign
-  subject: Upgrade chat input area with better controls
-  status: pending
-  description: |
-    Current input is basic textarea. Redesign to:
-    - Larger input area that grows with text (auto-resize)
-    - Placeholder text with tips (e.g., "Shift+Enter for new line")
-    - Send button with visual feedback (hover, active states)
-    - Formatting buttons (bold, italic, code, link)
-    - Emoji picker button
-    - Attachment/file upload button with drag-drop preview
-    - Quick actions (regenerate, steer, edit) buttons
-    - Character count indicator when approaching limit
-    - Voice input button with animated recording indicator
-  effort: large
-  category: feature
-  blocking: []
-  blockedBy: []
-  acceptance:
-    - Input auto-resizes up to max-height
-    - All buttons visible and responsive
-    - Drag-drop file preview shown before upload
-    - Voice recording shows animated waves
-    - Keyboard shortcuts work (Cmd+Enter to send)
-  edge_cases:
-    - Very long pastes handled smoothly
-    - Voice input fails gracefully with error message
-    - File uploads show progress indicator
-
-- id: streaming-visual-feedback
-  subject: Add visual feedback during agent streaming
-  status: pending
-  description: |
-    Current streaming has minimal visual indicators. Add:
-    - Animated loading skeleton (shimmer effect) for new messages
-    - Pulsing dot indicator showing active streaming
-    - Token count / generation progress
-    - ETA estimation when available
-    - "Thinking..." indicator during planning phases
-    - Subtle background animation during streaming
-    - Stop generation button (prominent and red)
-    - Completion notification with sound option
-  effort: medium
-  category: feature
-  blocking: []
-  blockedBy: []
-  acceptance:
-    - Skeleton loading appears for new agent response
-    - Pulsing indicator shows streaming is active
-    - Token count updates in real-time
-    - Stop button cancels current generation
-    - Thinking phase clearly labeled
-  edge_cases:
-    - Long responses show multiple skeleton blocks
-    - Network errors interrupt gracefully
-    - Rapid re-streaming shows smooth transition
-
-- id: code-block-enhancements
-  subject: Enhance code block rendering and interactions
-  status: pending
-  description: |
-    Current code blocks are functional but basic. Enhance with:
-    - Full language detection and syntax highlighting
-    - Copy button that changes to checkmark on success
-    - "Run in terminal" button for executable code
-    - Line numbers toggle
-    - Dark/light theme-aware colors
-    - Code diff visualization (red/green lines for changes)
-    - Filename/path display above code block
-    - Download code as file button
-    - Expand/collapse for long blocks
-    Currently in js/streaming-renderer.js
-  effort: medium
-  category: feature
-  blocking: []
-  blockedBy: []
-  acceptance:
-    - All code blocks have language badge
-    - Copy button shows success state
-    - Diffs show red/green highlighting
-    - Long blocks (>30 lines) expandable
-    - Dark mode colors contrast properly
-  edge_cases:
-    - Unknown language defaults to plaintext
-    - Very large files truncate with expand link
-    - Copy works in all browsers
-
-- id: color-palette-modernization
-  subject: Update color palette to modern, professional design system
-  status: pending
-  description: |
-    Current palette is basic blue + gray. Modernize to:
-    - Primary: Modern blue (#0066cc or #0080ff)
-    - Secondary: Vibrant accent (purple, green, or orange)
-    - Success: Emerald green (#10b981 → #059669)
-    - Error: Modern red (#ef4444 → #dc2626)
-    - Warning: Amber (#f59e0b → #d97706)
-    - Neutral: Better grayscale (5-7 shades for depth)
-    - Background: Subtle gradient or texture option
-    - Code blocks: Dark theme by default, matching VS Code
-    Dark mode: Ensure sufficient contrast (WCAG AA minimum)
-    Currently in static/css/main.css lines 3-36
-  effort: small
-  category: refactor
-  blocking: []
-  blockedBy: []
-  acceptance:
-    - All 8 colors defined in CSS vars
-    - Dark mode has separate palette
-    - Contrast ratios meet WCAG AA standard
-    - Code block colors match VS Code Dark+
-  edge_cases:
-    - Ensure colorblind-friendly palette (no red/green only)
-    - Animations don't cause motion sickness
-    - Print stylesheet still readable
-
-- id: typography-hierarchy
-  subject: Improve typography system with better hierarchy
-  status: pending
-  description: |
-    Current typography is basic system fonts. Improve with:
-    - Consider font pairing (e.g., Inter + JetBrains Mono)
-    - Define explicit size scale (8px, 10px, 12px, 14px, 16px, 18px, 20px, 24px, 32px)
-    - Improve line-height for readability (1.5-1.6 for body, 1.2 for headers)
-    - Better letter-spacing for headers (0.5px to 1px)
-    - Font weight scale (400 regular, 500 medium, 600 semibold, 700 bold)
-    - Message headers (sender name + timestamp): 12px gray
-    - Message body: 14px primary, line-height 1.6
-    - Code: JetBrains Mono 12px, line-height 1.5
-    - Improved link styling with underlines on hover
-    Currently in static/css/main.css and index.html
-  effort: small
-  category: refactor
-  blocking: []
-  blockedBy: []
-  acceptance:
-    - 9-point size scale applied
-    - Headers use font-weight 600-700
-    - Body text uses line-height 1.6
-    - Code uses monospace, 12px
-    - All text readable at 16px zoom
-  edge_cases:
-    - Very long words don't break layout
-    - Ligatures work in code
-    - CJK text renders properly
-
-- id: responsive-mobile-design
-  subject: Optimize responsive design for mobile and tablet
-  status: pending
-  description: |
-    Current responsive is basic. Enhance with:
-    - Mobile-first breakpoints (320px, 640px, 1024px, 1280px)
-    - Hamburger menu for sidebar on mobile
-    - Full-width chat input on mobile
-    - Bottom navigation bar for quick actions on mobile
-    - Gesture support (swipe for sidebar, pinch for zoom)
-    - Keyboard support for virtual keyboard display
-    - Better touch targets (min 44x44px for buttons)
-    - Optimize layouts for portrait/landscape orientation
-    Test on: iPhone, iPad, Android devices, iPad Pro
-  effort: medium
-  category: feature
-  blocking: []
-  blockedBy: []
-  acceptance:
-    - Mobile view has hamburger menu
-    - Chat input full-width on mobile
-    - All buttons at least 44x44px
-    - Bottom nav visible on mobile
-    - Swipe left opens/closes sidebar
-    - Tested on 3+ device sizes
-  edge_cases:
-    - Notch and safe area handling (iPhone)
-    - Landscape mode optimized
-    - Virtual keyboard doesn't break layout
-
-- id: animations-transitions
-  subject: Add smooth animations and transitions throughout UI
-  status: pending
-  description: |
-    Current design has minimal animations. Add:
-    - Page transitions: Subtle fade or slide
-    - Button interactions: Scale on click, color fade on hover
-    - Message entry: Slide-in from bottom with fade
-    - Sidebar toggle: Smooth width transition
-    - Skeleton loading: Shimmer animation
-    - Streaming cursor: Blinking animation
-    - Modal dialogs: Fade-in with slide
-    - Hover states: All interactive elements have smooth color/scale transitions
-    - Use 200-300ms for most transitions, 500ms for longer animations
-    - GPU-accelerated (use transform, opacity, not width/height)
-  effort: small
-  category: feature
-  blocking: []
-  blockedBy: []
-  acceptance:
-    - All major interactions have smooth transitions
-    - Animations use GPU acceleration (transform/opacity)
-    - No janky scrolling or animation stutter
-    - Animations complete in 200-500ms
-    - Reduced-motion respects user preference
-  edge_cases:
-    - Low-end devices don't stutter
-    - Animations don't interfere with scrolling
-    - Prefers-reduced-motion disables animations
-
-- id: accessibility-improvements
-  subject: Enhance accessibility for keyboard and screen reader users
-  status: pending
-  description: |
-    Current accessibility is basic. Enhance with:
-    - Keyboard navigation for all interactive elements
-    - Tab order is logical and visible (focus ring clearly visible)
-    - Skip link to jump to main content
-    - ARIA labels for all buttons and form inputs
-    - Role attributes for custom components
-    - Alt text for all images and avatars
-    - Announce streaming/loading state to screen readers
-    - Focus management for modals (trap focus, restore on close)
-    - Test with NVDA/JAWS screen readers
-    - Color contrast minimum WCAG AA (4.5:1 for text, 3:1 for UI)
-    - Readable font sizes (minimum 14px for body, 16px on mobile)
-  effort: medium
-  category: feature
-  blocking: []
-  blockedBy: []
-  acceptance:
-    - All buttons keyboard-accessible with visible focus
-    - Screen reader announces message sources
-    - Tab order is logical and documented
-    - Color contrast meets WCAG AA standard
-    - Focus ring clearly visible on all elements
-    - Tested with screen reader (NVDA/JAWS)
-  edge_cases:
-    - Dynamic content announced to screen readers
-    - Focus restored after modal closes
-    - Skip links don't cause layout issues
-
-- id: dark-mode-refinement
-  subject: Improve dark mode design and theme switching
-  status: pending
-  description: |
-    Current dark mode is basic CSS var swap. Refine to:
-    - Add system dark mode detection (prefers-color-scheme)
-    - Add manual theme toggle button
-    - Persist theme preference in localStorage
-    - Add intermediate "system" option
-    - Refine dark color palette for better contrast
-    - Code blocks in dark mode use better theme (VS Code Dark+)
-    - Add optional "high contrast" mode for accessibility
-    - Add subtle background texture/noise in dark mode
-    - Test for eye strain and readability
-  effort: small
-  category: feature
-  blocking: []
-  blockedBy: []
-  acceptance:
-    - Theme toggle button in header
-    - Preference saved and restored
-    - Dark mode has good contrast
-    - Code blocks use proper dark syntax highlighting
-    - System preference detected on first load
-    - No flickering on page reload
-  edge_cases:
-    - Very bright code on dark background readable
-    - Images rendered with appropriate borders/backgrounds
-    - Links still visible in dark mode
-
-- id: settings-panel
-  subject: Create comprehensive settings panel
-  status: pending
-  description: |
-    No current settings UI. Create panel with:
-    - Theme selection (light/dark/system)
-    - Font size adjustment (10px-20px range)
-    - Message density (compact/normal/spacious)
-    - Code block language auto-detection on/off
-    - Sound effects on/off
-    - Notification preferences
-    - Export conversation as JSON/markdown
-    - Dangerous actions: clear cache, reset all, export data
-    - Keyboard shortcuts reference
-    - About/version information
-    - Link to GitHub/documentation
-  effort: medium
-  category: feature
-  blocking: []
-  blockedBy: []
-  acceptance:
-    - Settings accessible from header menu
-    - All preferences persisted in localStorage
-    - Theme changes apply immediately
-    - Font size changes apply to all text
-    - Message density adjusts spacing
-  edge_cases:
-    - Settings panel works on mobile (full-screen modal)
-    - Reset confirmation prevents accidental deletion
-    - Export includes full conversation with metadata
-
-- id: search-enhancement
-  subject: Improve conversation search with advanced filters
-  status: pending
-  description: |
-    Current search is basic text match. Enhance with:
-    - Fuzzy matching for typo tolerance
-    - Filter by agent/model used
-    - Filter by date range
-    - Filter by conversation status (completed/ongoing)
-    - Search in message content (not just titles)
-    - Show search result preview with highlighting
-    - Remember recent searches
-    - Search result count display
-    - Keyboard shortcut (Cmd+K or Cmd+F) for search
-    - Clear search button with visual feedback
-  effort: medium
-  category: feature
-  blocking: []
-  blockedBy: []
-  acceptance:
-    - Search works across all conversation data
-    - Fuzzy matching tolerates typos
-    - Filters work in combination
-    - Keyboard shortcut opens search
-    - Results show within 100ms
-  edge_cases:
-    - Search with special characters works
-    - Very large conversation lists search quickly
-    - Search in different languages supported
-
-- id: visual-error-handling
-  subject: Improve error states and visual feedback
-  status: pending
-  description: |
-    Current error handling is basic. Improve with:
-    - Prominent error banners (red background, white text)
-    - Error icons/symbols (⚠️, ❌)
-    - Suggested actions (retry, contact support, etc.)
-    - Toast notifications for temporary issues
-    - Detailed error messages (not just "error")
-    - Connection error specific feedback
-    - Network retry with exponential backoff UI
-    - Rate limit warnings with countdown timer
-    - Clear error recovery path
-    - Error logging for debugging (show in devtools)
-  effort: small
-  category: feature
-  blocking: []
-  blockedBy: []
-  acceptance:
-    - Errors display in prominent red banner
-    - Error messages are specific and helpful
-    - Retry buttons work and show progress
-    - Toast notifications disappear after 5 seconds
-    - Connection status shown in header
-  edge_cases:
-    - Multiple errors queue properly
-    - Rate limit shows time remaining
-    - Network errors resolve automatically when online
-
-- id: conversation-threading
-  subject: Add visual conversation threading and organization
-  status: pending
-  description: |
-    Current conversations are linear. Add threading features:
-    - Show message count in conversation header
-    - Add breadcrumb showing conversation context
-    - Option to view conversation tree/structure
-    - Expand/collapse sub-conversations
-    - Thread tagging system (research, bug-fix, feature, etc.)
-    - Pin important messages or threads
-    - Add message reactions (thumbs up/down)
-    - Quote/reply to specific messages
-    - Edit sent messages
-    - Message deletion with confirmation
-  effort: large
-  category: feature
-  blocking: []
-  blockedBy: []
-  acceptance:
-    - Message count displays in header
-    - Quote replies show as indented with border
-    - Pinned messages visible at top of conversation
-    - Edit timestamp shows "(edited)" label
-    - Delete requires confirmation
-  edge_cases:
-    - Quoted message deleted shows "message removed"
-    - Thread expansion loads historical data
-    - Very long threads lazy-load older messages
-
-- id: visual-performance-metrics
-  subject: Display performance metrics and model information
-  status: pending
-  description: |
-    Add real-time metrics display:
-    - Token count (input + output)
-    - Generation time for last message
-    - Cost estimation (if available)
-    - Model name and version
-    - Temperature and top-p settings used
-    - Stop reason (max_tokens, end_turn, etc.)
-    - Can be toggled on/off in settings
-    - Small, unobtrusive display (top-right corner or expandable)
-    - Helpful tooltips explaining each metric
-  effort: small
-  category: feature
-  blocking: []
-  blockedBy: []
-  acceptance:
-    - Token count displayed for each message
-    - Generation time shown (e.g., "3.2s")
-    - Model name visible in header
-    - Metrics can be hidden via toggle
-    - Tooltips explain each metric
-  edge_cases:
-    - Streaming responses show running token count
-    - Partial tokens displayed as estimate
-    - Cost display only if configured
-
-- id: quick-actions-toolbar
-  subject: Add toolbar with common actions
-  status: pending
-  description: |
-    Add floating toolbar below chat input with quick actions:
-    - Copy entire conversation
-    - Export as markdown/JSON
-    - Share conversation (create shareable link)
-    - Start new conversation based on this thread
-    - Archive conversation
-    - Change model/agent for same conversation
-    - View conversation metadata (created date, duration, etc.)
-    - Collapse/expand toolbar with chevron icon
-  effort: medium
-  category: feature
-  blocking: []
-  blockedBy: []
-  acceptance:
-    - Toolbar visible below input area
-    - All actions have icons and tooltips
-    - Toolbar collapses to single chevron icon
-    - Keyboard shortcuts work for common actions
-    - Copy shows success toast
-  edge_cases:
-    - Toolbar doesn't cover input on mobile
-    - Share generates unique URL correctly
-    - Export includes all messages with formatting
-
-- id: visual-loading-states
-  subject: Add skeleton loading and progressive disclosure
-  status: pending
-  description: |
-    Improve loading state visuals:
-    - Skeleton loading screens for initial page load
-    - Skeleton message blocks while streaming
-    - Progressive image loading (blur-up effect)
-    - Loading spinner animations (custom SVG, not just "Loading...")
-    - Loading state for conversation list
-    - Empty state illustrations (rather than just text)
-    - Placeholder content that feels intentional
-    - Shimmer animation on skeleton screens
-    - Loading bar/progress for large operations
-  effort: small
-  category: feature
-  blocking: []
-  blockedBy: []
-  acceptance:
-    - Skeleton screens appear while loading
-    - Shimmer animation runs smoothly
-    - Empty states show helpful illustrations
-    - Loading spinner visible and animated
-    - Progressive image loading blur-up works
-  edge_cases:
-    - Skeleton screens match final layout exactly
-    - Loading states never feel stuck
-    - Animations work on low-end devices
-
-- id: agent-model-selector
-  subject: Create prominent agent and model selector UI
-  status: pending
-  description: |
-    Current model selection is buried. Create prominent selector:
-    - Dropdown in header or sidebar
-    - Shows current agent/model with icon
-    - Lists available agents (Claude, OpenCode, Gemini, Kilo, etc.)
-    - For each agent, shows available models
-    - Quick preview of model capabilities/stats
-    - Change model mid-conversation
-    - Show model context window size
-    - Show estimated cost per query (if available)
-    - Favorite/star frequently used models
-    - Search models by name
-  effort: medium
-  category: feature
-  blocking: []
-  blockedBy: []
-  acceptance:
-    - Selector visible in header
-    - Agent/model change is instant
-    - Lists all available models
-    - Shows model context window
-    - Change mid-conversation works
-  edge_cases:
-    - Model list updates on startup
-    - Unsupported models show as disabled
-    - Model change shows confirmation toast
-
-- id: conversation-metadata-display
-  subject: Show conversation metadata and history info
-  status: pending
-  description: |
-    Add visible metadata display:
-    - Created date/time
-    - Last updated timestamp
-    - Total messages count
-    - Total tokens used
-    - Duration of conversation
-    - List of agents/models used
-    - Summary/description of conversation
-    - Can be viewed in modal or sidebar info panel
-    - Shows editing capability
-  effort: small
-  category: feature
-  blocking: []
-  blockedBy: []
-  acceptance:
-    - Metadata viewable in modal or sidebar
-    - All fields display correctly
-    - Editable description field
-    - Timestamps human-readable
-  edge_cases:
-    - Very old conversations show proper date format
-    - Very long conversations show total duration
-    - Multiple agents show all used
-
-- id: visual-focus-states
-  subject: Improve keyboard focus indicators and tab order
-  status: pending
-  description: |
-    Current focus states are subtle. Improve with:
-    - High-contrast focus ring (2px, matches primary color)
-    - Focus ring on all interactive elements
-    - Visible tab order (1-2-3 indicators optional)
-    - Logical tab order documented
-    - Focus state also affects hover state for consistency
-    - Focus shadow (subtle box-shadow alongside ring)
-    - Focus visible only on keyboard, not mouse
-    - Clear visual feedback for radio/checkbox focus
-  effort: small
-  category: refactor
-  blocking: []
-  blockedBy: []
-  acceptance:
-    - Focus ring visible on all buttons
-    - Focus ring 2px width
-    - Tab order is logical
-    - Focus works with keyboard only
-    - Contrast meets WCAG AAA (7:1) if possible
-  edge_cases:
-    - Focus visible in dark mode
-    - Focus ring doesn't cover content
-    - Custom focus styles don't break accessibility
-
-- id: create-design-tokens
-  subject: Create design tokens system (spacing, sizing, shadows)
-  status: pending
-  description: |
-    Formalize design system with tokens:
-    - Spacing scale: 4px, 8px, 12px, 16px, 24px, 32px, 48px, 64px
-    - Border radius: 2px, 4px, 8px, 12px, 16px
-    - Shadow scale: small (subtle), medium (cards), large (modals)
-    - Z-index scale: base(0), dropdown(1000), modal(2000), tooltip(3000)
-    - Breakpoints: mobile(320px), tablet(640px), desktop(1024px), wide(1280px)
-    - Transition durations: fast(100ms), normal(200ms), slow(500ms)
-    - Define in root CSS vars for consistency
-    - Document in style guide
-    - Use consistently throughout UI
-  effort: small
-  category: refactor
-  blocking: []
-  blockedBy: []
-  acceptance:
-    - All spacing uses token scale
-    - All shadows use shadow scale
-    - All transitions use duration scale
-    - Z-index documented and consistent
-    - Tokens applied to all components
-  edge_cases:
-    - No magic numbers in CSS
-    - Tokens work in light and dark modes
-
----
-
-## Non-UI Items (Infrastructure)
-
-- id: performance-audit
-  subject: Conduct performance audit and optimize rendering
-  status: pending
-  description: |
-    Audit and improve performance:
-    - Measure First Contentful Paint (FCP), Largest Contentful Paint (LCP)
-    - Check Core Web Vitals (CLS, FID, TTFB)
-    - Profile JS execution on slow device (throttle to 4x slowdown)
-    - Optimize image sizes and formats (WebP)
-    - Lazy-load below-fold content
-    - Code-split large chunks
-    - Use Web Workers for heavy computations
-    - Optimize CSS (remove unused, minify)
-    - Monitor memory usage (check for leaks)
-  effort: large
-  category: infra
-  blocking: []
-  blockedBy: []
-  acceptance:
-    - FCP < 1.5s, LCP < 2.5s
-    - No CLS (Cumulative Layout Shift)
-    - Lighthouse score > 90 for performance
-    - Memory stable under 100MB
-  edge_cases:
-    - Slow network (3G) still responsive
-    - Large conversations don't cause memory leaks
-    - Mobile performance optimized
-
-- id: test-coverage-expansion
-  subject: Expand test coverage for UI components
-  status: pending
-  description: |
-    Expand tests to cover new features:
-    - Component render tests
-    - User interaction tests
-    - Message streaming tests
-    - Search functionality tests
-    - Theme switching tests
-    - Mobile responsiveness tests
-    - Error handling tests
-    - Performance regression tests
-  effort: large
-  category: infra
-  blocking: []
-  blockedBy: []
-  acceptance:
-    - >90% code coverage
-    - All major user flows tested
-    - Mobile responsive tests pass
-    - Performance benchmarks pass
-  edge_cases:
-    - Streaming responses tested
-    - Error scenarios covered
-    - WebSocket reconnection tested
-
----
-
-## Summary
-
-**Total Items**: 28 items (24 features, 4 infrastructure)
-**Large Effort**: 7 items (20 hours estimated)
-**Medium Effort**: 11 items (15 hours estimated)  
-**Small Effort**: 10 items (10 hours estimated)
-**Total Estimated**: ~45 hours
-
-## Implementation Priority
-
-Phase 1 (Critical Path - Week 1):
-1. Color palette modernization
-2. Header redesign
-3. Message bubble redesign
-4. Chat input redesign
-5. Sidebar redesign
-6. Typography improvements
-
-Phase 2 (High Value - Week 2):
-7. Animations and transitions
-8. Code block enhancements
-9. Streaming visual feedback
-10. Dark mode refinement
-11. Responsive mobile design
-
-Phase 3 (Polish & Features - Week 3):
-12. Settings panel
-13. Agent/model selector
-14. Accessibility improvements
-15. Error handling
-16. Quick actions toolbar
-17. Visual loading states
-
-Phase 4 (Nice-to-Have - Week 4):
-18-28. Remaining features and infrastructure items