ai-agent-session-center 2.10.12 → 2.10.34

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kason Zhan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,166 +1,104 @@
 # AI Agent Session Center
 
-A lightweight, real-time dashboard that replaces heavy IDEs like VS Code and JetBrains for AI agent workflows. Monitor and control all your Claude Code, Gemini CLI, and Codex sessions from one place — with live SSH terminals, prompt history, tool logs, and queuing. Every session spawns an animated 3D robot in an interactive cyberdrome that visually reflects what the agent is doing. Runs on any device, anywhere.
+**Monitor, drive, queue, and resume every Claude Code, Gemini, and Codex session from one localhost dashboard — each rendered as a live 3D robot you can click into.**
+
+*Built for developers juggling multiple AI coding agents across terminals and machines.*
 
 [![npm version](https://img.shields.io/npm/v/ai-agent-session-center.svg)](https://www.npmjs.com/package/ai-agent-session-center)
-[![npm downloads](https://img.shields.io/npm/dm/ai-agent-session-center.svg)](https://www.npmjs.com/package/ai-agent-session-center)
 [![Node.js](https://img.shields.io/badge/Node.js-18+-green)](https://nodejs.org)
-[![License](https://img.shields.io/badge/License-MIT-yellow)](./LICENSE)
-
-## Demo
-
-**[Live demo → aasc.work/demo](https://aasc.work/demo)**
-
-### Desktop
-
-<table>
-  <tr>
-    <td><img src="static/screenshot-dashboard.png" alt="3D cyberdrome with active agent sessions across project rooms" width="400"></td>
-    <td><img src="static/screenshot-terminal.png" alt="SSH terminal session — control agents from the dashboard" width="400"></td>
-  </tr>
-  <tr>
-    <td><img src="static/screenshot-project-tab-detailed.png" alt="Split view with detailed session switcher cards — terminal and project file browser side by side" width="400"></td>
-    <td><img src="static/screenshot-project-tab-compact.png" alt="Split view with compact session switcher — terminal and project file browser side by side" width="400"></td>
-  </tr>
-</table>
-
-### Mobile
-
-<table>
-  <tr>
-    <td><img src="static/screenshot-mobile-home.png" alt="Mobile — 3D cyberdrome with session list" width="160"></td>
-    <td><img src="static/screenshot-mobile-terminal.png" alt="Mobile — terminal tab with live conversation" width="160"></td>
-    <td><img src="static/screenshot-mobile-project.png" alt="Mobile — project file browser" width="160"></td>
-    <td><img src="static/screenshot-mobile-history.png" alt="Mobile — session history with filters" width="160"></td>
-  </tr>
-</table>
-
-### Video
-
-https://github.com/user-attachments/assets/004ee6f9-942c-44c2-a4c5-d971fa0e824b
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow)](./LICENSE)
 
-## Why?
+### **[▶ Try it live — zero install, runs in your browser → aasc.work/demo](https://aasc.work/demo)**
 
-When you're running multiple AI coding agents across different terminals — Claude Code in one, Gemini in another, Codex in a third — it's impossible to keep track of what each one is doing. Which agent is stuck waiting for approval? Which one finished and needs your next prompt? Which one is burning tokens on a runaway loop? Agent Session Center gives you a single view across all your AI coding sessions so you can stay in control without constantly switching terminals.
+<img src="static/screenshot-dashboard.png" alt="3D cyberdrome with active agent sessions across project rooms" width="100%">
 
-## Features
+**Jump to:** [Install](#install) · [Why power users keep it open](#why-power-users-keep-it-open) · [What's inside](#whats-inside) · [Under the hood](#under-the-hood) · [Commands](#commands) · [Troubleshooting](#troubleshooting) · [FAQ](#faq)
 
-### 3D Cyberdrome Scene
+> You're running Claude Code in one terminal, Gemini in another, Codex in a third. Which one is **stuck waiting for approval**? Which one **finished** and needs your next prompt? Which one is **burning tokens on a runaway loop**? Agent Session Center watches all of them at once and surfaces the one that needs you — so you stop tab-juggling and only step in when it matters.
 
-- **One agent, one robot** — every AI coding session gets its own animated 3D character in an interactive cyberdrome
-- **8 animation states** — robots idle, walk, run, wait, dance, wave, or go offline based on real-time session status
-- **6 procedural robot models** — robot, mech, drone, spider, orb, and tank variants with auto-assigned neon colors
-- **Dynamic room system** — four-quadrant office layout with desks, coffee lounge, gym, corridor rooms, and spatial navigation AI
-- **Subagent connections** — parent-child agent teams render as connected robots with animated laser-line beams
-- **Speech bubbles & particles** — floating dialogue shows current tool/prompt, burst particles on state transitions
-- **Camera fly-to** — smooth animated camera focuses on the selected robot; OrbitControls for manual pan/zoom/rotate
-- **Flat list fallback** — 2D sidebar list auto-activates if 3D crashes or for low-resource environments
-
-### Session Detail Panel
-
-- **Resizable detail panel** — slides in from the right (320px–95vw) with 7 tabs: Terminal, Prompts, Project, Queue, Notes, Activity, Summary
-- **Session switcher** — horizontal tab strip shows all active sessions with sequence numbers, pin/unpin, compact/detailed display modes
-- **Editable metadata** — inline-edit title, label, accent color (customizes robot glow), and pin state; all persisted to SQLite + IndexedDB
-- **Session controls** — Resume, Kill, Archive, Delete, Summarize, Alert, room assignment, and label chips (ONEOFF, HEAVY, IMPORTANT)
-- **Split view** — Terminal and Project side-by-side with a draggable divider (ratio persisted per session)
-- **Approval alerts** — yellow card, visor flash, and 3-burst alarm when tools need user approval
-
-### Terminal & SSH
-
-- **Full terminal emulation** — xterm.js 5 with 256 colors, Unicode 11, WebLinks, and FitAddon
-- **Local & SSH sessions** — create terminals with working directory, command, SSH host/key/password, tmux wrap/attach
-- **Session resume** — reconnect to disconnected Claude sessions via `claude --resume` with one click
-- **Terminal bookmarks** — save scroll positions with notes, jump back to any bookmarked line
-- **Terminal toolbar** — fullscreen, clear, copy, paste, theme selector (auto, light, dark, Solarized, Dracula, custom)
-- **Bidirectional WebSocket relay** — real-time I/O, 50ms debounced resize, Escape forwards `\x1b` to SSH
-
-### Project File Browser
+```bash
+npx ai-agent-session-center
+```
 
-- **Browse & search** — navigate project directories, full-text file search with cached results
-- **Syntax highlighting** — code viewer with line numbers, word wrap toggle, and markdown outline panel
-- **Sub-tab system** — open multiple directories/files in tabs within the Project panel
-- **File bookmarks** — save line references with notes; bookmarked lines highlighted in the code viewer; cross-file navigation
-- **Sort & filter** — sort by name or date, toggle date/time display, file size shown per entry
-- **File editing** — inline editor with save support for quick edits
+The dashboard opens at **http://localhost:3333** and registers lightweight, read-only hooks automatically — no manual config, fully reversible with `--uninstall`. Robots appear the moment you use any AI CLI in any terminal.
 
-### Multi-CLI Monitoring
+Not ready to install? **[Try the live demo first — no setup → aasc.work/demo](https://aasc.work/demo)**
 
-- **Three AI CLIs** — Claude Code (up to 14 events), Gemini CLI (4 events), and Codex (1 event)
-- **3 hook density levels** — High (full monitoring), Medium (default, 12 events), Low (5 events, minimal overhead)
-- **File-based message queue** — hooks append to JSONL queue file via atomic POSIX append (~0.1ms); HTTP POST fallback
-- **3–17ms end-to-end latency** — from hook fired to browser updated
-- **5-priority session matching** — pending resume, terminal ID, working directory, path scan, PID parent check
-- **Approval detection** — tool-category timeouts with child-process check; `PermissionRequest` event for reliable signal
-- **CLI badge detection** — auto-detects CLAUDE, GEMINI, CODEX, or AIDER from launch command
+---
 
-### Prompt Queue
+## Why power users keep it open
 
-- **Global queue view** — see all pending prompts across every session in one place
-- **Per-session queue** — compose, reorder (drag-and-drop), send, and move prompts between sessions
-- **Auto-send mode** — queued prompts auto-dispatch when the target session becomes idle
+A control plane for serious multi-agent work — built to be left open all day.
 
-### Analytics & History
+| Without it | With Agent Session Center |
+|------------|---------------------------|
+| Alt-tab through a wall of terminals to find the blocked one | The robot that needs you flashes, alarms, and surfaces a colored alert card |
+| Copy-paste prompts into whichever window is free | Queue prompts per session and auto-fire them the moment it goes idle |
+| Babysit long runs so you don't miss the approval prompt | Walk away — scheduled loops and quiet-hours windows run hands-off |
+| Lose your whole layout when a session or machine restarts | Workspace snapshots rebuild sessions, tabs, rooms, and scrollback |
 
-- **History search** — full-text search across titles, projects, and labels with date range, status, and sort filters
-- **Analytics dashboard** — summary cards, 7-day activity heatmap, tool usage breakdown, active projects ranking
-- **Timeline view** — time-series visualization (hourly, daily, weekly) of sessions, prompts, and tool calls
+- **One dashboard replaces a wall of terminals.** Monitor and drive every Claude Code, Gemini, and Codex session across local and remote machines — live terminals, full conversation transcripts, tool logs, and a file browser, in one view.
+- **Drive agents from live terminals — even on a second monitor.** Real xterm.js terminals with SSH/tmux support, and you can pop any terminal or project panel out into its own native desktop window and fling it to another display.
+- **Select-to-explain, anywhere.** Highlight text in any terminal or transcript and fork a floating picture-in-picture AI session to explain, translate, or define it.
+- **Engineered for always-on use.** 3–17ms hook-to-screen latency, 700+ Vitest tests, a native Electron desktop app, and a fully mobile-responsive browser UI.
 
-### Theming & Sound
+---
 
-- **9 scene themes** — Command Center, Cyberpunk, Dracula, Nord, Monokai, Solarized, Light, Warm, Blonde
-- **16 synthesized sounds** — per-CLI profiles with per-event sound mapping (chime, ping, alarm, fanfare, etc.)
-- **6 ambient presets** — rain, lo-fi, server room, deep space, coffee shop, or off
-- **Visual effects** — glowing card borders, pulsing animations, scanline CRT overlay, status particles, fog depth by theme
+## See it
 
-### Notes & Summaries
+### Walkthrough video
 
-- **Session notes** — plain-text notes with full CRUD, stored in both SQLite and IndexedDB
-- **AI-powered summaries** — generate session summaries via configured LLM API with customizable prompt templates
+https://github.com/user-attachments/assets/004ee6f9-942c-44c2-a4c5-d971fa0e824b
 
-### Authentication & Security
+### Desktop
 
-- **Password protection** — optional login with HttpOnly cookie (1-hour TTL), rate-limited (5 attempts/15min)
-- **Security headers** — X-Frame-Options, CSP, CORS, localhost-only hook endpoint, shell metacharacter injection prevention
-- **Directory traversal protection** — `resolveProjectPath()` validates all file browser paths
+<table>
+  <tr>
+    <td><img src="static/screenshot-terminal.png" alt="Live terminal session — drive agents straight from the dashboard" width="400"></td>
+    <td><img src="static/screenshot-project-tab-detailed.png" alt="Split view, detailed session switcher — terminal and project file browser side by side" width="400"></td>
+  </tr>
+</table>
 
-### Keyboard Shortcuts
+### Mobile
 
-- **Full keyboard navigation** — `/` search, `T` new terminal, `K` kill, `A` archive, `M` mute, `S` settings, `?` shortcuts panel
-- **Rebindable shortcuts** — customize every shortcut from Settings with conflict detection
-- **Session switching** — `Alt+Cmd+1`–`9` to select Nth session by status priority
+<table>
+  <tr>
+    <td><img src="static/screenshot-mobile-home.png" alt="Mobile — 3D cyberdrome with session list" width="160"></td>
+    <td><img src="static/screenshot-mobile-terminal.png" alt="Mobile — terminal tab with live conversation" width="160"></td>
+    <td><img src="static/screenshot-mobile-project.png" alt="Mobile — project file browser" width="160"></td>
+    <td><img src="static/screenshot-mobile-history.png" alt="Mobile — session history with filters" width="160"></td>
+  </tr>
+</table>
 
-### Data Persistence
+---
 
-- **Dual storage** — SQLite on server (sessions, prompts, tools, events, notes) + IndexedDB via Dexie in browser (12 tables)
-- **Auto-snapshots** — server saves full state every 10 seconds; SSH terminals auto-respawn on restart
-- **Session ID migration** — seamless re-keying when sessions resume with new IDs
+## Install
 
-> See [docs/feature/README.md](docs/feature/README.md) for the complete features reference with architecture details and API documentation.
+```bash
+npx ai-agent-session-center
+```
 
-## Requirements
+That's the happy path. The dashboard starts at **http://localhost:3333** (configurable) and configures hooks automatically.
 
-- **Node.js 18+** with npm
-- **jq** (recommended) for hook enrichment — hooks still work without it but with less metadata
-- One or more supported AI CLIs:
-  - [Claude Code](https://docs.anthropic.com/en/docs/claude-code)
-  - [Gemini CLI](https://github.com/google-gemini/gemini-cli)
-  - [Codex CLI](https://github.com/openai/codex)
+**What it changes on your machine:** read-only hook entries added to your AI CLI settings (e.g. `~/.claude/settings.json`, via atomic write) and a queue file under `/tmp/claude-session-center/`. Nothing in the CLIs themselves is modified, and it's fully reversible with `--uninstall`.
 
-## Getting Started
+<details>
+<summary><b>Other install options</b></summary>
 
-### Using npx (Recommended)
+### Global install
 
 ```bash
-npx ai-agent-session-center
+npm install -g ai-agent-session-center
+ai-agent-session-center
 ```
 
-The dashboard starts at **http://localhost:3333** (default port, configurable during setup) and automatically configures hooks.
-
-### Global Install (if npx is not available)
+### From source
 
 ```bash
-npm install -g ai-agent-session-center
-ai-agent-session-center
+git clone https://github.com/coding-by-feng/ai-agent-session-center.git
+cd ai-agent-session-center
+npm install
+npm run dev
 ```
 
 ### Uninstall
@@ -173,24 +111,25 @@ npx ai-agent-session-center --uninstall
 npm uninstall -g ai-agent-session-center
 ```
 
-### From Source
+</details>
 
-```bash
-git clone https://github.com/coding-by-feng/ai-agent-session-center.git
-cd ai-agent-session-center
-npm install
-npm run dev
-```
+### Requirements
 
-### Usage
+- **Node.js 18+** with npm
+- **jq** (recommended) for hook enrichment — hooks still work without it, with less metadata
+- One or more supported AI CLIs:
+  - [Claude Code](https://docs.anthropic.com/en/docs/claude-code)
+  - [Gemini CLI](https://github.com/google-gemini/gemini-cli)
+  - [Codex CLI](https://github.com/openai/codex)
+
+### First run
 
-1. Start the dashboard — robots appear automatically as you use AI CLIs in any terminal
-2. Click **+ New** to create SSH terminal sessions directly from the dashboard
-3. Click a robot to view full session details (prompts, tools, activity, terminal, notes, queue)
-4. Assign sessions to rooms to organize your workspace in the 3D scene
-5. Open **Settings** to customize themes, sounds, and hook density
+1. Start the dashboard — robots appear automatically as you use AI CLIs in any terminal.
+2. Click **+ New** to spawn local or SSH terminal sessions directly from the dashboard.
+3. Click a robot to open its detail panel (Project, Terminal, Commands, Conversation, AI Popups, Notes, Queue).
+4. Queue prompts, assign sessions to rooms, and open **Settings** to tune themes, sounds, and hook density.
 
-### CLI Options
+### CLI options
 
 ```bash
 ai-agent-session-center [options]
@@ -203,98 +142,88 @@ Options:
   --uninstall        Remove all hooks from CLI configs and exit
 ```
 
-## How It Works
-
-Agent Session Center uses lightweight bash hooks that append JSON events to a file-based message queue (`/tmp/claude-session-center/queue.jsonl`). The server watches this file and broadcasts updates to connected browsers via WebSocket.
-
-No modifications to any CLI are needed. The hooks are purely observational and add negligible overhead (~2-5ms per event). **End-to-end latency: 3-17ms** from hook fired to browser updated.
-
-```
-AI CLI (Claude / Gemini / Codex)
-         |
-    Hook Script (bash)                    ~2-5ms
-    - Enriches with PID, TTY, terminal env
-         |
-  /tmp/.../queue.jsonl                    ~0.1ms
-  - Atomic POSIX append
-         |
-  Server (Express + WebSocket)            ~0.5ms
-  - Validate, process, broadcast
-         |
-  React Frontend
-  - 3D scene + detail panels update
-```
-
-### Session Matching
-
-When a hook event arrives, a 5-priority fallback system links it to the correct terminal session: pending resume match, terminal ID env var, working directory match, path scan, and PID parent check. If no match is found, a display-only card is created with the detected source (VS Code, iTerm, Warp, Ghostty, etc.).
+---
 
-### Hook Density Levels
+## What's inside
 
-| Level | Events | Use Case |
-|-------|--------|----------|
-| high | All 14 Claude events | Full monitoring, approval detection |
-| medium | 12 events | Default, good balance |
-| low | 5 events | Minimal overhead |
+A quick tour. The complete reference — 45 feature docs with architecture and APIs — lives in [`docs/feature/README.md`](docs/feature/README.md).
 
-## Tech Stack
+- **3D cyberdrome** — 6 procedural robot models, 8 animation states, user-created project rooms plus a coffee lounge with spatial navigation, subagent laser-link beams, camera fly-to, and a 2D flat-list fallback.
+- **Session detail panel** — a resizable 7-tab panel (Project, Terminal, Commands, Conversation, AI Popups, Notes, Queue), session switcher, inline-edit title/label/accent color, and split view.
+- **Terminal & SSH** — xterm.js with local/SSH/tmux sessions, dual transport (IPC in Electron / WebSocket in browser), `claude --resume`, pop-out to native desktop windows, bookmarks, select-to-explain, and hold-to-speak text-to-speech.
+- **Project browser** — lazy file tree, fuzzy find over a cached index, syntax highlighting, image/TeX viewers, inline editing, and `/`-command + `@`-file autocomplete.
+- **Multi-CLI monitoring** — automatically links every hook event to the right terminal session with no per-session setup, via an **8-priority matching cascade** (display-only fallback when nothing matches). Works with Claude Code, Gemini, and Codex, with `--model` / `--effort` launch flags.
+- **Queue, scheduler & loops** — a global and per-session queue with drag-reorder, auto-send-on-idle, scheduled loops with quiet-hours windows, and exportable queue history.
+- **Workspace snapshots** — full layout serialization, 10s server auto-snapshots, SSH auto-respawn on restart, and seamless session-ID re-keying on resume.
+- **History & search** — full-text history search across titles, projects, and labels, with date, status, and sort filters.
+- **Theming & sound** — **9 scene themes**, **15 synthesized event sounds** with per-CLI profiles, **5 ambient presets**, and CRT/scanline + particle effects.
+- **Security** — optional password login (rate-limited), a localhost-only hook endpoint, and directory-traversal + SSH-injection guards.
+- **Desktop & mobile** — a native Electron app (macOS first-class, Windows supported; system tray, multi-window) plus a fully responsive browser UI that runs anywhere Node does.
 
-- **Backend**: Node.js 18+ (ESM), Express 5, WebSocket (ws), tsx
-- **Frontend**: React 19, TypeScript, Vite
-- **3D Visualization**: Three.js, React Three Fiber, drei
-- **State Management**: Zustand, React Query
-- **Terminal**: xterm.js, node-pty
-- **Database**: SQLite (server, WAL mode) + IndexedDB via Dexie (browser)
-- **Hooks**: Bash scripts (file-based MQ primary, HTTP fallback)
-- **Testing**: Vitest (400+ tests) + Playwright (E2E)
-- **Charts**: Recharts
-- **Drag & Drop**: @dnd-kit
+---
 
-## Session States
+## Session state machine
 
 | Status | What it means | Visual |
 |--------|---------------|--------|
 | **Idle** | No activity | Green, robot seeks coffee lounge |
-| **Prompting** | You just sent a prompt | Cyan, robot walks to desk |
+| **Prompting** | You just sent a prompt | Cyan, robot walks to its desk |
 | **Working** | Agent is calling tools | Orange, charging effect |
-| **Waiting** | Agent finished, your turn | Cyan, robot goes to gym |
+| **Waiting** | Agent finished, your turn | Cyan, robot heads to the coffee lounge |
 | **Approval** | Tool blocked, needs yes/no | Yellow, visor flash, alarm |
 | **Input** | Waiting for your answer | Purple, arm raised |
 | **Ended** | Session closed | Red, offline animation |
 
-## Keyboard Shortcuts
+---
+
+## Under the hood
+
+Lightweight bash hooks append JSON events to a file-based message queue (`/tmp/claude-session-center/queue.jsonl`). The server watches the file and broadcasts updates to connected browsers over WebSocket. No CLI is modified — the hooks are purely observational and add ~2–5ms per event. **End-to-end latency is 3–17ms** from hook fired to browser updated (measured locally; the upper bound includes the React render and 3D scene update).
+
+```
+AI CLI (Claude / Gemini / Codex)
+         |
+    Hook script (bash)                    ~2-5ms
+    - enriches with PID, TTY, terminal env
+         |
+  /tmp/.../queue.jsonl                    ~0.1ms
+  - atomic POSIX append
+         |
+  Server (Express + WebSocket)            ~0.5ms
+  - validate, process, broadcast
+         |
+  React frontend                          + render
+  - 3D scene + detail panels update
+```
 
-| Key | Action |
-|-----|--------|
-| `/` | Focus search |
-| `Escape` | Close modal / deselect session |
-| `?` | Toggle shortcuts panel |
-| `S` | Toggle settings |
-| `K` | Kill selected session |
-| `A` | Archive selected session |
-| `T` | New terminal session |
-| `M` | Mute/unmute all |
+### Session matching
 
-## Known Limitations
+Each hook event is linked to the right terminal session via an **8-priority fallback cascade** — pending-resume, terminal-ID, working-directory, path-scan, and PID-parent strategies, plus fork-routing and PID-cache sub-steps. If nothing matches, a display-only card is created with the detected source (VS Code, iTerm, Warp, Ghostty, etc.).
 
-- **Session matching heuristic** — linking hook events to SSH terminals uses a multi-priority fallback system. Two sessions in the same working directory may occasionally cross-link.
-- **Approval detection timing** — auto-approved long-running commands (npm install, builds) will briefly show as "waiting for approval" for ~8 seconds until the post-tool event clears it.
-- **macOS/Linux focused** — primary development is on macOS. Linux should work identically. Windows support via PowerShell hook variant is less tested.
-- **3D scene performance** — with many concurrent sessions (20+), the Three.js scene may impact performance on lower-end hardware.
+### Hook density levels
 
-## Roadmap
+| Level | Behavior |
+|-------|----------|
+| high | All Claude hook events — fullest monitoring and approval detection |
+| medium | Default — good balance of detail and overhead |
+| low | Minimal event set for the lowest overhead |
 
-Contributions and ideas are welcome in these areas:
+### Tech stack
 
-- **More CLI integrations** — support for OpenCode, Cursor, Windsurf, or any agentic framework
-- **Remote monitoring** — dashboard accessible from other machines on the network
-- **Agent creation templates** — define agents with custom system prompts, tools, and configurations before launching
-- **Collaboration** — multi-user dashboards where teams can see each other's agent sessions
-- **Mobile companion** — responsive PWA for monitoring on the go
-- **Plugin system** — extensible hooks for custom visualizations and integrations
-- **Community themes** — user-contributed 3D scene themes and robot models
+| Layer | Technology |
+|-------|------------|
+| Backend | Node.js 18+ (ESM), Express 5, ws 8, tsx |
+| Frontend | React 19, TypeScript, Vite 7, Zustand 5, @tanstack/react-query 5 |
+| 3D | Three.js 0.182, @react-three/fiber 9, @react-three/drei 10 |
+| Terminal | @xterm/xterm 5.5 (+ fit, unicode11, web-links), node-pty 1.1 |
+| Desktop | Electron 34, electron-builder 25 |
+| Database | better-sqlite3 12 (WAL) + Dexie 4 (IndexedDB, 15 tables) |
+| Forms / validation | react-hook-form 7 + Zod 4 |
+| Markdown | react-markdown 10 + rehype-highlight |
+| Routing / misc | react-router 7 · latex.js · xlsx · auto-launch |
+| Testing | Vitest 4 (700+ tests) + Playwright 1.58 (E2E) |
 
-If any of these interest you, feel free to open an issue or submit a PR.
+---
 
 ## Commands
 
@@ -306,15 +235,19 @@ npm run setup            # Interactive setup wizard
 npm run install-hooks    # Install hooks into CLI configs
 npm run uninstall-hooks  # Remove all dashboard hooks
 npm run reset            # Reset everything (hooks, config, backup)
-npm test                 # Run tests (400+ Vitest tests)
+npm test                 # Run tests (Vitest)
 npm run test:watch       # Watch mode
 npm run test:e2e         # E2E tests (Playwright)
+npm run electron:dev     # Build + launch the Electron app
+npm run electron:build   # Build a distributable (DMG / NSIS)
 npm run debug            # Start with verbose logging
 ```
 
+---
+
 ## Troubleshooting
 
-### Hooks Not Firing
+### Hooks not firing
 
 ```bash
 # Verify hooks are registered
@@ -327,33 +260,87 @@ echo '{"session_id":"test","hook_event_name":"SessionStart"}' | ~/.claude/hooks/
 npm run install-hooks
 ```
 
-### Port 3333 in Use
+### Port 3333 in use
 
-The server auto-resolves port conflicts. To use a different port:
+The server auto-resolves port conflicts. To force another port:
 
 ```bash
 npx ai-agent-session-center --port 4444
 PORT=4444 npm start
 ```
 
-### jq Not Installed
+### jq not installed
 
 ```bash
-# macOS
-brew install jq
-
-# Ubuntu/Debian
-sudo apt-get install jq
+brew install jq            # macOS
+sudo apt-get install jq    # Ubuntu/Debian
 ```
 
+---
+
+## FAQ
+
+<details>
+<summary><b>Does it modify my AI CLI?</b></summary>
+
+No. It adds read-only, observational hook entries to your CLI's settings file (e.g. `~/.claude/settings.json`, written atomically) so it can mirror events. The CLIs themselves are untouched, and you can remove every hook with `npx ai-agent-session-center --uninstall` or `npm run reset`.
+</details>
+
+<details>
+<summary><b>Does any data leave my machine?</b></summary>
+
+No. The dashboard, hook endpoint, and message queue are all localhost-only. Nothing is sent to a remote server.
+</details>
+
+<details>
+<summary><b>How do I fully uninstall?</b></summary>
+
+Run `npx ai-agent-session-center --uninstall` to strip the hooks from all CLI configs, or `npm run reset` to also clean local config and back it up. Globally installed copies: `npm uninstall -g ai-agent-session-center`.
+</details>
+
+<details>
+<summary><b>Which CLIs are supported?</b></summary>
+
+Claude Code, Gemini CLI, and Codex CLI today. More integrations (OpenCode, Cursor, Windsurf, and other agentic frameworks) are on the roadmap.
+</details>
+
+---
+
+## Known limitations
+
+- **Session matching is heuristic** — linking hook events to terminals uses a multi-priority fallback; two sessions in the same working directory may occasionally cross-link.
+- **Approval detection timing** — auto-approved long-running commands (npm install, builds) can briefly show as "approval" for ~8s until the PostToolUse event clears it.
+- **Platform support** — developed and tested primarily on macOS. The browser dashboard works anywhere Node runs (including Linux). The Electron desktop build targets macOS and Windows; the Windows PowerShell hook variant is less battle-tested.
+- **3D scene performance** — with 20+ concurrent sessions the Three.js scene may strain lower-end hardware; the 2D flat-list fallback is available.
+
+---
+
+## Roadmap
+
+Contributions and ideas welcome:
+
+- **More CLI integrations** — OpenCode, Cursor, Windsurf, or any agentic framework
+- **Remote monitoring** — dashboard reachable from other machines on the network
+- **Agent creation templates** — define system prompts, tools, and configs before launch
+- **Collaboration** — multi-user dashboards where teams see each other's sessions
+- **Plugin system** — extensible hooks for custom visualizations
+- **Community themes** — user-contributed 3D scene themes and robot models
+
+---
+
 ## Contributing
 
-Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on how to get started.
+Contributions are welcome. To get started:
 
-## Changelog
+```bash
+git clone https://github.com/coding-by-feng/ai-agent-session-center.git
+cd ai-agent-session-center
+npm install
+npm run dev          # Vite HMR + backend
+```
 
-See [CHANGELOG.md](CHANGELOG.md) for a detailed list of changes in each release.
+Run `npm test`, `npm run lint`, and `npm run typecheck` before opening a PR, and use conventional commit messages (`feat:`, `fix:`, `docs:`, …). For the full feature reference and architecture, read [`docs/feature/README.md`](docs/feature/README.md). Release notes live in [CHANGELOG.md](CHANGELOG.md).
 
 ## License
 
-This project is licensed under the [MIT License](LICENSE).
+Released under the [MIT License](./LICENSE).