refactor(providers): remove debug logging from Claude authentication status checks

Remove legacy backend routes that no longer have frontend or internal
callers, including the old Claude/Codex MCP APIs, unused Cursor and Codex
helper endpoints, stale TaskMaster detection/next/initialize routes,
and unused command/project helpers.

This reduces duplicated MCP behavior now handled by the provider-based
MCP API, shrinks the exposed backend surface, and removes probe/service
code that only existed for deleted endpoints.

Add an MCP settings API audit document to capture the route-usage
analysis and explain why the legacy MCP endpoints were considered safe
to remove.

.env.example

@@ -17,7 +17,7 @@
 
 # Backend server port (Express API + WebSocket server)
 #API server
-PORT=3001
+SERVER_PORT=3001
 #Frontend port
 VITE_PORT=5173
 

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,41 @@
+---
+name: Bug report
+about: Create a report to help us improve
+title: ''
+labels: ''
+assignees: ''
+type: Bug
+
+---
+
+**Describe the bug**
+A clear and concise description of what the bug is.
+
+**To Reproduce**
+Steps to reproduce the behavior:
+1. Go to '...'
+2. Click on '....'
+3. Scroll down to '....'
+4. See error
+
+**Expected behavior**
+A clear and concise description of what you expected to happen.
+
+**Screenshots**
+If applicable, add screenshots to help explain your problem.
+
+**Error message**
+If applicable, add the error message you see to help explain your problem.
+
+**Desktop (please complete the following information):**
+ - OS: [e.g. iOS]
+ - Browser [e.g. chrome, safari]
+ - Version [e.g. 22]
+
+**Smartphone (please complete the following information):**
+ - Device: [e.g. iPhone6]
+ - OS: [e.g. iOS8.1]
+ - Browser [e.g. stock browser, safari]
+
+**Additional context**
+Add any other context about the problem here.

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,19 @@
+---
+name: Feature request
+about: Suggest an idea for this project
+title: "[Feature]"
+labels: ''
+assignees: ''
+type: Feature
+
+---
+
+**Is your feature request related to a problem? Please describe.**
+A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+
+**Describe the solution you'd like**
+A clear and concise description of what you want to happen.
+
+
+**Additional context**
+Add any other context or screenshots about the feature request here.

.github/workflows/release.yml

@@ -0,0 +1,50 @@
+name: Release
+
+on:
+  workflow_dispatch:
+    inputs:
+      increment:
+        description: 'Version bump: patch, minor, major, or explicit (e.g. 1.27.0)'
+        required: true
+        default: 'patch'
+        type: string
+      release_name:
+        description: 'Custom release name (optional, defaults to "CloudCLI UI vX.Y.Z")'
+        required: false
+        type: string
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      id-token: write
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.RELEASE_PAT }}
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 22
+          registry-url: https://registry.npmjs.org
+
+      - name: git config
+        run: |
+          git config user.name "${GITHUB_ACTOR}"
+          git config user.email "${GITHUB_ACTOR}@users.noreply.github.com"
+
+      - run: npm ci
+
+      - name: Release
+        run: |
+          ARGS="--ci --increment=${{ inputs.increment }}"
+          if [ -n "${{ inputs.release_name }}" ]; then
+            ARGS="$ARGS --github.releaseName=\"${{ inputs.release_name }}\""
+          fi
+          npx release-it $ARGS
+        env:
+          GITHUB_TOKEN: ${{ secrets.RELEASE_PAT }}
+          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

.gitignore

@@ -8,6 +8,7 @@ lerna-debug.log*
 
 # Build outputs
 dist/
+dist-server/
 dist-ssr/
 build/
 out/
@@ -135,6 +136,7 @@ tasks/
 !src/i18n/locales/en/tasks.json
 !src/i18n/locales/ja/tasks.json
 !src/i18n/locales/ru/tasks.json
+!src/i18n/locales/de/tasks.json
 
 # Git worktrees
-.worktrees/
+.worktrees/

.release-it.json

@@ -6,7 +6,8 @@
     "requireCleanWorkingDir": true
   },
   "npm": {
-    "publish": true
+    "publish": true,
+    "publishArgs": ["--access public"]
   },
   "github": {
     "release": true,

CHANGELOG.md

@@ -3,6 +3,103 @@
 All notable changes to CloudCLI UI will be documented in this file.
 
 
+## [1.29.2](https://github.com/siteboon/claudecodeui/compare/v1.29.1...v1.29.2) (2026-04-14)
+
+### Bug Fixes
+
+* **sandbox:** use backgrounded sbx run to keep sandbox  alive ([9b11c03](https://github.com/siteboon/claudecodeui/commit/9b11c034d9a19710a23b56c62dcf07c21a17bd97))
+
+## [1.29.1](https://github.com/siteboon/claudecodeui/compare/v1.29.0...v1.29.1) (2026-04-14)
+
+### Bug Fixes
+
+* add latest tag to docker npx command and change the detach mode to work without spawn ([4a56972](https://github.com/siteboon/claudecodeui/commit/4a569725dae320a505753359d8edfd8ca79f0fd7))
+
+## [1.29.0](https://github.com/siteboon/claudecodeui/compare/v1.28.1...v1.29.0) (2026-04-14)
+
+### New Features
+
+* adding docker sandbox environments ([13e97e2](https://github.com/siteboon/claudecodeui/commit/13e97e2c71254de7a60afb5495b21064c4bc4241))
+
+### Bug Fixes
+
+* **thinking-mode:** fix dropdown positioning ([#646](https://github.com/siteboon/claudecodeui/issues/646)) ([c7a5baf](https://github.com/siteboon/claudecodeui/commit/c7a5baf1479404bd40e23aa58bd9f677df9a04c6))
+
+### Maintenance
+
+* update release flow node version ([e2459cb](https://github.com/siteboon/claudecodeui/commit/e2459cb0f8b35f54827778a7b444e6c3ca326506))
+
+## [1.28.1](https://github.com/siteboon/claudecodeui/compare/v1.28.0...v1.28.1) (2026-04-10)
+
+### New Features
+
+* add branding, community links, GitHub star badge, and About settings tab ([2207d05](https://github.com/siteboon/claudecodeui/commit/2207d05c1ca229214aa9c2e2c9f4d0827d421574))
+
+### Bug Fixes
+
+* corrupted binary downloads ([#634](https://github.com/siteboon/claudecodeui/issues/634)) ([e61f8a5](https://github.com/siteboon/claudecodeui/commit/e61f8a543d63fe7c24a04b3d2186085a06dcbcdb))
+* **ui:** remove mobile bottom nav, unify processing indicator, and improve tooltip behavior on mobile ([#632](https://github.com/siteboon/claudecodeui/issues/632)) ([a8dab0e](https://github.com/siteboon/claudecodeui/commit/a8dab0edcf949ae610820bae9500c433781f7c73))
+
+### Refactoring
+
+* remove unused whispher transcribe logic ([#637](https://github.com/siteboon/claudecodeui/issues/637)) ([590dd42](https://github.com/siteboon/claudecodeui/commit/590dd42649424ab990353fcf59ce0965036d3d25))
+
+## [1.28.0](https://github.com/siteboon/claudecodeui/compare/v1.27.1...v1.28.0) (2026-04-03)
+
+### New Features
+
+* adding session resume in the api ([8f1042c](https://github.com/siteboon/claudecodeui/commit/8f1042cf256be282f009adcceeb55ab2dddf3fba))
+* moving new session button higher ([1628868](https://github.com/siteboon/claudecodeui/commit/16288684702dec894cf054291ca3d545ddb8214b))
+
+### Maintenance
+
+* changing package name to @cloudcli-ai/cloudcli ([ef51de2](https://github.com/siteboon/claudecodeui/commit/ef51de259ea2b963bc15f058b084e11220bc216a))
+
+## [1.27.1](https://github.com/siteboon/claudecodeui/compare/v1.26.3...v1.27.1) (2026-03-29)
+
+### Bug Fixes
+
+* prevent split on undefined（[#491](https://github.com/siteboon/claudecodeui/issues/491)） ([#563](https://github.com/siteboon/claudecodeui/issues/563)) ([b54cdf8](https://github.com/siteboon/claudecodeui/commit/b54cdf8168fc224e9907796e4229ae8ed34e6885))
+
+### Maintenance
+
+* add release-it github action ([42a1313](https://github.com/siteboon/claudecodeui/commit/42a131389a6954df0d2c3bedd2cb6d3406c5ebc1))
+* add terminal plugin in the plugins list ([004135e](https://github.com/siteboon/claudecodeui/commit/004135ef0187023e1da29c4a7137a28a42ebf9af))
+* release tokens ([f1063fd](https://github.com/siteboon/claudecodeui/commit/f1063fd33964ccb517f5ebcdd14526ed162e1138))
+* relicense to AGPL-3.0-or-later ([27cd124](https://github.com/siteboon/claudecodeui/commit/27cd12432b7d3237981f86acd9cc99532d843d4a))
+
+## [1.26.3](https://github.com/siteboon/claudecodeui/compare/v1.26.2...v1.26.3) (2026-03-22)
+
+## [1.26.2](https://github.com/siteboon/claudecodeui/compare/v1.26.0...v1.26.2) (2026-03-21)
+
+### Bug Fixes
+
+* change SW cache mechanism ([17d6ec5](https://github.com/siteboon/claudecodeui/commit/17d6ec54af18d333c8b04d2ffc64793e688d996e))
+* claude auth changes and adding copy on mobile ([a41d2c7](https://github.com/siteboon/claudecodeui/commit/a41d2c713e87d56f23d5884585b4bb43c43a250a))
+
+## [1.26.0](https://github.com/siteboon/claudecodeui/compare/v1.25.2...v1.26.0) (2026-03-20)
+
+### New Features
+
+* add German (Deutsch) language support ([#525](https://github.com/siteboon/claudecodeui/issues/525)) ([a7299c6](https://github.com/siteboon/claudecodeui/commit/a7299c68237908c752d504c2e8eea91570a30203))
+* add WebSocket proxy for plugin backends ([#553](https://github.com/siteboon/claudecodeui/issues/553)) ([88c60b7](https://github.com/siteboon/claudecodeui/commit/88c60b70b031798d51ce26c8f080a0f64d824b05))
+* Browser autofill support for login form ([#521](https://github.com/siteboon/claudecodeui/issues/521)) ([72ff134](https://github.com/siteboon/claudecodeui/commit/72ff134b315b7a1d602f3cc7dd60d47c1c1c34af))
+* git panel redesign ([#535](https://github.com/siteboon/claudecodeui/issues/535)) ([adb3a06](https://github.com/siteboon/claudecodeui/commit/adb3a06d7e66a6d2dbcdfb501615e617178314af))
+* introduce notification system and claude notifications ([#450](https://github.com/siteboon/claudecodeui/issues/450)) ([45e71a0](https://github.com/siteboon/claudecodeui/commit/45e71a0e73b368309544165e4dcf8b7fd014e8dd))
+* **refactor:** move plugins to typescript ([#557](https://github.com/siteboon/claudecodeui/issues/557)) ([612390d](https://github.com/siteboon/claudecodeui/commit/612390db536417e2f68c501329bfccf5c6795e45))
+* unified message architecture with provider adapters and session store ([#558](https://github.com/siteboon/claudecodeui/issues/558)) ([a4632dc](https://github.com/siteboon/claudecodeui/commit/a4632dc4cec228a8febb7c5bae4807c358963678))
+
+### Bug Fixes
+
+* detect Claude auth from settings env ([#527](https://github.com/siteboon/claudecodeui/issues/527)) ([95bcee0](https://github.com/siteboon/claudecodeui/commit/95bcee0ec459f186d52aeffe100ac1a024e92909))
+* remove /exit command from claude login flow during onboarding ([#552](https://github.com/siteboon/claudecodeui/issues/552)) ([4de8b78](https://github.com/siteboon/claudecodeui/commit/4de8b78c6db5d8c2c402afce0f0b4cc16d5b6496))
+
+### Documentation
+
+* add German language link to all README files ([#534](https://github.com/siteboon/claudecodeui/issues/534)) ([1d31c3e](https://github.com/siteboon/claudecodeui/commit/1d31c3ec8309b433a041f3099955addc8c136c35))
+* **readme:** hotfix and improve for README.jp.md ([#550](https://github.com/siteboon/claudecodeui/issues/550)) ([7413c2c](https://github.com/siteboon/claudecodeui/commit/7413c2c78422c308ac949e6a83c3e9216b24b649))
+* **README:** update translations with CloudCLI branding and feature restructuring ([#544](https://github.com/siteboon/claudecodeui/issues/544)) ([14aef73](https://github.com/siteboon/claudecodeui/commit/14aef73cc6085fbb519fe64aea7cac80b7d51285))
+
 ## [1.25.2](https://github.com/siteboon/claudecodeui/compare/v1.25.0...v1.25.2) (2026-03-11)
 
 ### New Features

CONTRIBUTING.md

@@ -153,4 +153,4 @@ This automatically:
 
 ## License
 
-By contributing, you agree that your contributions will be licensed under the [GPL-3.0 License](LICENSE).
+By contributing, you agree that your contributions will be licensed under the [AGPL-3.0-or-later License](LICENSE), including the additional terms specified in Section 7 of the LICENSE file.

NOTICE

@@ -0,0 +1,13 @@
+CloudCLI UI
+Copyright 2025-2026 Siteboon AI B.V. and contributors
+
+This software is licensed under the GNU Affero General Public License v3.0
+or later (AGPL-3.0-or-later). See the LICENSE file for the full license text,
+including additional terms under Section 7.
+
+Originally developed by Siteboon AI B.V. (https://github.com/siteboon/claudecodeui).
+
+Contributions by Siteboon AI B.V. prior to commit 004135ef were originally
+published under GPL-3.0 and are hereby relicensed to AGPL-3.0-or-later.
+Contributions by other authors prior to that commit remain under GPL-3.0
+and are incorporated into this work as permitted by GPL-3.0 Section 13.

README.de.md

@@ -0,0 +1,250 @@
+<div align="center">
+  <img src="public/logo.svg" alt="CloudCLI UI" width="64" height="64">
+  <h1>Cloud CLI (auch bekannt als Claude Code UI)</h1>
+  <p>Eine Desktop- und Mobile-Oberfläche für <a href="https://docs.anthropic.com/en/docs/claude-code">Claude Code</a>, <a href="https://docs.cursor.com/en/cli/overview">Cursor CLI</a>, <a href="https://developers.openai.com/codex">Codex</a> und <a href="https://geminicli.com/">Gemini-CLI</a>.<br>Lokal oder remote nutzbar – verwalte deine aktiven Projekte und Sitzungen von überall.</p>
+</div>
+
+<p align="center">
+  <a href="https://cloudcli.ai">CloudCLI Cloud</a> · <a href="https://cloudcli.ai/docs">Dokumentation</a> · <a href="https://discord.gg/buxwujPNRE">Discord</a> · <a href="https://github.com/siteboon/claudecodeui/issues">Fehler melden</a> · <a href="CONTRIBUTING.md">Mitwirken</a>
+</p>
+
+<p align="center">
+  <a href="https://cloudcli.ai"><img src="https://img.shields.io/badge/☁️_CloudCLI_Cloud-Try_Now-0066FF?style=for-the-badge" alt="CloudCLI Cloud"></a>
+  <a href="https://discord.gg/buxwujPNRE"><img src="https://img.shields.io/badge/Discord-Join_Community-5865F2?style=for-the-badge&logo=discord&logoColor=white" alt="Join Community"></a>
+  <br><br>
+  <a href="https://trendshift.io/repositories/15586" target="_blank"><img src="https://trendshift.io/api/badge/repositories/15586" alt="siteboon%2Fclaudecodeui | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/></a>
+</p>
+
+<div align="right"><i><a href="./README.md">English</a> · <a href="./README.ru.md">Русский</a> · <b>Deutsch</b> · <a href="./README.ko.md">한국어</a> · <a href="./README.zh-CN.md">中文</a> · <a href="./README.ja.md">日本語</a></i></div>
+
+---
+
+## Screenshots
+
+<div align="center">
+
+<table>
+<tr>
+<td align="center">
+<h3>Desktop-Ansicht</h3>
+<img src="public/screenshots/desktop-main.png" alt="Desktop-Oberfläche" width="400">
+<br>
+<em>Hauptoberfläche mit Projektübersicht und Chat</em>
+</td>
+<td align="center">
+<h3>Mobile-Erfahrung</h3>
+<img src="public/screenshots/mobile-chat.png" alt="Mobile-Oberfläche" width="250">
+<br>
+<em>Responsives mobiles Design mit Touch-Navigation</em>
+</td>
+</tr>
+<tr>
+<td align="center" colspan="2">
+<h3>CLI-Auswahl</h3>
+<img src="public/screenshots/cli-selection.png" alt="CLI-Auswahl" width="400">
+<br>
+<em>Wähle zwischen Claude Code, Gemini, Cursor CLI und Codex</em>
+</td>
+</tr>
+</table>
+
+
+
+</div>
+
+## Funktionen
+
+- **Responsives Design** – Funktioniert nahtlos auf Desktop, Tablet und Mobilgerät, sodass du Agents auch vom Smartphone aus nutzen kannst
+- **Interaktives Chat-Interface** – Eingebaute Chat-Oberfläche für die reibungslose Kommunikation mit den Agents
+- **Integriertes Shell-Terminal** – Direkter Zugriff auf die Agents CLI über die eingebaute Shell-Funktionalität
+- **Datei-Explorer** – Interaktiver Dateibaum mit Syntaxhervorhebung und Live-Bearbeitung
+- **Git-Explorer** – Änderungen anzeigen, stagen und committen. Branches wechseln ebenfalls möglich
+- **Sitzungsverwaltung** – Gespräche fortsetzen, mehrere Sitzungen verwalten und Verlauf nachverfolgen
+- **Plugin-System** – CloudCLI mit eigenen Plugins erweitern – neue Tabs, Backend-Dienste und Integrationen hinzufügen. [Eigenes Plugin erstellen →](https://github.com/cloudcli-ai/cloudcli-plugin-starter)
+- **TaskMaster AI Integration** *(Optional)* – Erweitertes Projektmanagement mit KI-gestützter Aufgabenplanung, PRD-Parsing und Workflow-Automatisierung
+- **Modell-Kompatibilität** – Funktioniert mit Claude, GPT und Gemini (vollständige Liste unterstützter Modelle in [`shared/modelConstants.js`](shared/modelConstants.js))
+
+
+## Schnellstart
+
+### CloudCLI Cloud (Empfohlen)
+
+Der schnellste Einstieg – keine lokale Einrichtung erforderlich. Erhalte eine vollständig verwaltete, containerisierte Entwicklungsumgebung, die über Web, Mobile App, API oder deine bevorzugte IDE erreichbar ist.
+
+**[Mit CloudCLI Cloud starten](https://cloudcli.ai)**
+
+
+### Self-Hosted (Open Source)
+
+#### npm
+
+CloudCLI UI sofort mit **npx** ausprobieren (erfordert **Node.js** v22+):
+
+```bash
+npx @cloudcli-ai/cloudcli
+```
+
+Oder **global** installieren für regelmäßige Nutzung:
+
+```bash
+npm install -g @cloudcli-ai/cloudcli
+cloudcli
+```
+
+Öffne `http://localhost:3001` – alle vorhandenen Sitzungen werden automatisch erkannt.
+
+Die **[Dokumentation →](https://cloudcli.ai/docs)** enthält weitere Konfigurationsoptionen, PM2, Remote-Server-Einrichtung und mehr.
+
+#### Docker Sandboxes (Experimentell)
+
+Agents in isolierten Sandboxes mit Hypervisor-Isolation ausführen. Standardmäßig wird Claude Code gestartet. Erfordert die [`sbx` CLI](https://docs.docker.com/ai/sandboxes/get-started/).
+
+```
+npx @cloudcli-ai/cloudcli@latest sandbox ~/my-project
+```
+
+Unterstützt Claude Code, Codex und Gemini CLI. Weitere Details in der [Sandbox-Dokumentation](docker/).
+
+---
+
+## Welche Option passt zu dir?
+
+CloudCLI UI ist die Open-Source-UI-Schicht, die CloudCLI Cloud antreibt. Du kannst es auf deinem eigenen Rechner selbst hosten oder CloudCLI Cloud nutzen, das darauf aufbaut und eine vollständig verwaltete Cloud-Umgebung, Team-Funktionen und tiefere Integrationen bietet.
+
+| | CloudCLI UI (Self-hosted) | CloudCLI Cloud |
+|---|---|---|
+| **Am besten für** | Entwickler:innen, die eine vollständige UI für lokale Agent-Sitzungen auf ihrem eigenen Rechner möchten | Teams und Entwickler:innen, die Agents in der Cloud betreiben möchten, überall erreichbar |
+| **Zugriff** | Browser via `[deineIP]:port` | Browser, jede IDE, REST API, n8n |
+| **Einrichtung** | `npx @cloudcli-ai/cloudcli` | Keine Einrichtung erforderlich |
+| **Rechner muss laufen** | Ja | Nein |
+| **Mobiler Zugriff** | Jeder Browser im Netzwerk | Jedes Gerät, native App in Entwicklung |
+| **Verfügbare Sitzungen** | Alle Sitzungen automatisch aus `~/.claude` erkannt | Alle Sitzungen in deiner Cloud-Umgebung |
+| **Unterstützte Agents** | Claude Code, Cursor CLI, Codex, Gemini CLI | Claude Code, Cursor CLI, Codex, Gemini CLI |
+| **Datei-Explorer und Git** | Ja, direkt in der UI | Ja, direkt in der UI |
+| **MCP-Konfiguration** | Über UI verwaltet, synchronisiert mit lokalem `~/.claude` | Über UI verwaltet |
+| **IDE-Zugriff** | Deine lokale IDE | Jede IDE, die mit deiner Cloud-Umgebung verbunden ist |
+| **REST API** | Ja | Ja |
+| **n8n-Node** | Nein | Ja |
+| **Team-Sharing** | Nein | Ja |
+| **Plattformkosten** | Kostenlos, Open Source | Ab $7/Monat |
+
+> Beide Optionen verwenden deine eigenen KI-Abonnements (Claude, Cursor usw.) – CloudCLI stellt die Umgebung bereit, nicht die KI.
+
+---
+
+## Sicherheit & Tool-Konfiguration
+
+**🔒 Wichtiger Hinweis**: Alle Claude Code Tools sind **standardmäßig deaktiviert**. Dies verhindert, dass potenziell schädliche Operationen automatisch ausgeführt werden.
+
+### Tools aktivieren
+
+Um den vollen Funktionsumfang von Claude Code zu nutzen, müssen Tools manuell aktiviert werden:
+
+1. **Tool-Einstellungen öffnen** – Klicke auf das Zahnrad-Symbol in der Seitenleiste
+2. **Selektiv aktivieren** – Nur die benötigten Tools einschalten
+3. **Einstellungen übernehmen** – Deine Einstellungen werden lokal gespeichert
+
+<div align="center">
+
+![Tool-Einstellungen Modal](public/screenshots/tools-modal.png)
+*Tool-Einstellungen – nur aktivieren, was benötigt wird*
+
+</div>
+
+**Empfohlene Vorgehensweise**: Mit grundlegenden Tools starten und bei Bedarf weitere hinzufügen. Die Einstellungen können jederzeit angepasst werden.
+
+---
+
+## Plugins
+
+CloudCLI verfügt über ein Plugin-System, mit dem benutzerdefinierte Tabs mit eigener Frontend-UI und optionalem Node.js-Backend hinzugefügt werden können. Plugins können direkt in **Einstellungen > Plugins** aus Git-Repos installiert oder selbst entwickelt werden.
+
+### Verfügbare Plugins
+
+| Plugin | Beschreibung |
+|---|---|
+| **[Project Stats](https://github.com/cloudcli-ai/cloudcli-plugin-starter)** | Zeigt Dateianzahl, Codezeilen, Dateityp-Aufschlüsselung, größte Dateien und zuletzt geänderte Dateien des aktuellen Projekts |
+
+### Eigenes Plugin erstellen
+
+**[Plugin-Starter-Vorlage →](https://github.com/cloudcli-ai/cloudcli-plugin-starter)** – Forke dieses Repository, um ein eigenes Plugin zu erstellen. Es enthält ein funktionierendes Beispiel mit Frontend-Rendering, Live-Kontext-Updates und RPC-Kommunikation zu einem Backend-Server.
+
+**[Plugin-Dokumentation →](https://cloudcli.ai/docs/plugin-overview)** – Vollständige Anleitung zur Plugin-API, zum Manifest-Format, zum Sicherheitsmodell und mehr.
+
+---
+## FAQ
+
+<details>
+<summary>Wie unterscheidet sich das von Claude Code Remote Control?</summary>
+
+Claude Code Remote Control ermöglicht es, Nachrichten an eine bereits im lokalen Terminal laufende Sitzung zu senden. Der Rechner muss eingeschaltet bleiben, das Terminal muss offen bleiben, und Sitzungen laufen nach etwa 10 Minuten ohne Netzwerkverbindung ab.
+
+CloudCLI UI und CloudCLI Cloud erweitern Claude Code, anstatt neben ihm zu laufen – MCP-Server, Berechtigungen, Einstellungen und Sitzungen sind exakt dieselben, die Claude Code nativ verwendet. Nichts wird dupliziert oder separat verwaltet.
+
+Das bedeutet in der Praxis:
+
+- **Alle Sitzungen, nicht nur eine** – CloudCLI UI erkennt automatisch jede Sitzung aus dem `~/.claude`-Ordner. Remote Control stellt nur die einzelne aktive Sitzung bereit, um sie in der Claude Mobile App verfügbar zu machen.
+- **Deine Einstellungen sind deine Einstellungen** – MCP-Server, Tool-Berechtigungen und Projektkonfiguration, die in CloudCLI UI geändert werden, werden direkt in die Claude Code-Konfiguration geschrieben und treten sofort in Kraft – und umgekehrt.
+- **Funktioniert mit mehr Agents** – Claude Code, Cursor CLI, Codex und Gemini CLI, nicht nur Claude Code.
+- **Vollständige UI, nicht nur ein Chat-Fenster** – Datei-Explorer, Git-Integration, MCP-Verwaltung und ein Shell-Terminal sind alle eingebaut.
+- **CloudCLI Cloud läuft in der Cloud** – Laptop zuklappen, der Agent läuft weiter. Kein Terminal zu überwachen, kein Rechner, der laufen muss.
+
+</details>
+
+<details>
+<summary>Muss ich ein KI-Abonnement separat bezahlen?</summary>
+
+Ja. CloudCLI stellt die Umgebung bereit, nicht die KI. Du bringst dein eigenes Claude-, Cursor-, Codex- oder Gemini-Abonnement mit. CloudCLI Cloud beginnt bei $7/Monat für die gehostete Umgebung zusätzlich dazu.
+
+</details>
+
+<details>
+<summary>Kann ich CloudCLI UI auf meinem Smartphone nutzen?</summary>
+
+Ja. Bei Self-Hosted: Server auf dem eigenen Rechner starten und `[deineIP]:port` in einem beliebigen Browser im Netzwerk öffnen. Bei CloudCLI Cloud: Von jedem Gerät aus öffnen – kein VPN, keine Portweiterleitung, keine Einrichtung. Eine native App ist ebenfalls in Entwicklung.
+
+</details>
+
+<details>
+<summary>Wirken sich Änderungen in der UI auf mein lokales Claude Code-Setup aus?</summary>
+
+Ja, bei Self-Hosted. CloudCLI UI liest aus und schreibt in dieselbe `~/.claude`-Konfiguration, die Claude Code nativ verwendet. MCP-Server, die über die UI hinzugefügt werden, erscheinen sofort in Claude Code und umgekehrt.
+
+</details>
+
+---
+
+## Community & Support
+
+- **[Dokumentation](https://cloudcli.ai/docs)** — Installation, Konfiguration, Funktionen und Fehlerbehebung
+- **[Discord](https://discord.gg/buxwujPNRE)** — Hilfe erhalten und mit anderen Nutzer:innen in Kontakt treten
+- **[GitHub Issues](https://github.com/siteboon/claudecodeui/issues)** — Fehlerberichte und Feature-Anfragen
+- **[Beitragsrichtlinien](CONTRIBUTING.md)** — So kannst du zum Projekt beitragen
+
+## Lizenz
+
+GNU General Public License v3.0 – siehe [LICENSE](LICENSE)-Datei für Details.
+
+Dieses Projekt ist Open Source und kann unter der GPL v3-Lizenz kostenlos genutzt, modifiziert und verteilt werden.
+
+## Danksagungen
+
+### Erstellt mit
+- **[Claude Code](https://docs.anthropic.com/en/docs/claude-code)** - Anthropics offizielle CLI
+- **[Cursor CLI](https://docs.cursor.com/en/cli/overview)** - Cursors offizielle CLI
+- **[Codex](https://developers.openai.com/codex)** - OpenAI Codex
+- **[Gemini-CLI](https://geminicli.com/)** - Google Gemini CLI
+- **[React](https://react.dev/)** - UI-Bibliothek
+- **[Vite](https://vitejs.dev/)** - Schnelles Build-Tool und Dev-Server
+- **[Tailwind CSS](https://tailwindcss.com/)** - Utility-first CSS-Framework
+- **[CodeMirror](https://codemirror.net/)** - Erweiterter Code-Editor
+- **[TaskMaster AI](https://github.com/eyaltoledano/claude-task-master)** *(Optional)* - KI-gestütztes Projektmanagement und Aufgabenplanung
+
+
+### Sponsoren
+- [Siteboon - KI-gestützter Website-Builder](https://siteboon.ai)
+---
+
+<div align="center">
+  <strong>Mit Sorgfalt für die Claude Code-, Cursor- und Codex-Community erstellt.</strong>
+</div>

README.ja.md

@@ -1,12 +1,23 @@
 <div align="center">
-  <img src="public/logo.svg" alt="Claude Code UI" width="64" height="64">
-  <h1>Cloud CLI (別名 Claude Code UI)</h1>
+  <img src="public/logo.svg" alt="CloudCLI UI" width="64" height="64">
+  <h1>Cloud CLI（別名 Claude Code UI）</h1>
+  <p><a href="https://docs.anthropic.com/en/docs/claude-code">Claude Code</a>、<a href="https://docs.cursor.com/en/cli/overview">Cursor CLI</a>、<a href="https://developers.openai.com/codex">Codex</a>、<a href="https://geminicli.com/">Gemini-CLI</a> のためのデスクトップ／モバイル UI。<br>ローカルでもリモートでも使え、アクティブなプロジェクトとセッションをどこからでも閲覧できます。</p>
 </div>
 
+<p align="center">
+  <a href="https://cloudcli.ai">CloudCLI Cloud</a> · <a href="https://cloudcli.ai/docs">ドキュメント</a> · <a href="https://discord.gg/buxwujPNRE">Discord</a> · <a href="https://github.com/siteboon/claudecodeui/issues">バグ報告</a> · <a href="CONTRIBUTING.md">コントリビュート</a>
+</p>
 
-[Claude Code](https://docs.anthropic.com/en/docs/claude-code)、[Cursor CLI](https://docs.cursor.com/en/cli/overview)、[Codex](https://developers.openai.com/codex) 向けのデスクトップ・モバイル UI です。ローカルまたはリモートで使用して、Claude Code、Cursor、Codex のアクティブなプロジェクトやセッションを確認し、どこからでも（モバイルやデスクトップから）変更を加えることができます。どこでも使える適切なインターフェースを提供します。
+<p align="center">
+  <a href="https://cloudcli.ai"><img src="https://img.shields.io/badge/☁️_CloudCLI_Cloud-Try_Now-0066FF?style=for-the-badge" alt="CloudCLI Cloud"></a>
+  <a href="https://discord.gg/buxwujPNRE"><img src="https://img.shields.io/badge/Discord-Join%20Community-5865F2?style=for-the-badge&logo=discord&logoColor=white" alt="Discord コミュニティに参加"></a>
+  <br><br>
+  <a href="https://trendshift.io/repositories/15586" target="_blank"><img src="https://trendshift.io/api/badge/repositories/15586" alt="siteboon%2Fclaudecodeui | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/></a>
+</p>
 
-<div align="right"><i><a href="./README.md">English</a> · <a href="./README.ru.md">Русский</a> · <a href="./README.ko.md">한국어</a> · <a href="./README.zh-CN.md">中文</a> · <b>日本語</b></i></div>
+<div align="right"><i><a href="./README.md">English</a> · <a href="./README.ru.md">Русский</a> · <a href="./README.de.md">Deutsch</a> · <a href="./README.ko.md">한국어</a> · <a href="./README.zh-CN.md">中文</a> · <b>日本語</b></i></div>
+
+---
 
 ## スクリーンショット
 
@@ -16,23 +27,23 @@
 <tr>
 <td align="center">
 <h3>デスクトップビュー</h3>
-<img src="public/screenshots/desktop-main.png" alt="Desktop Interface" width="400">
+<img src="public/screenshots/desktop-main.png" alt="デスクトップインターフェース" width="400">
 <br>
-<em>プロジェクト概要とチャットを表示するメインインターフェース</em>
+<em>プロジェクト概要とチャットを表示するメイン画面</em>
 </td>
 <td align="center">
 <h3>モバイル体験</h3>
-<img src="public/screenshots/mobile-chat.png" alt="Mobile Interface" width="250">
+<img src="public/screenshots/mobile-chat.png" alt="モバイルインターフェース" width="250">
 <br>
-<em>タッチナビゲーション対応のレスポンシブモバイルデザイン</em>
+<em>タッチ操作に対応したレスポンシブなモバイルデザイン</em>
 </td>
 </tr>
 <tr>
 <td align="center" colspan="2">
 <h3>CLI 選択</h3>
-<img src="public/screenshots/cli-selection.png" alt="CLI Selection" width="400">
+<img src="public/screenshots/cli-selection.png" alt="CLI 選択" width="400">
 <br>
-<em>Claude Code、Cursor CLI、Codex から選択</em>
+<em>Claude Code、Gemini、Cursor CLI、Codex から選択</em>
 </td>
 </tr>
 </table>
@@ -43,302 +54,187 @@
 
 ## 機能
 
-- **レスポンシブデザイン** - デスクトップ、タブレット、モバイルでシームレスに動作し、モバイルからも Claude Code、Cursor、Codex を使用可能
-- **インタラクティブチャットインターフェース** - Claude Code、Cursor、Codex とシームレスに通信する組み込みチャットインターフェース
-- **統合シェルターミナル** - 組み込みシェル機能による Claude Code、Cursor CLI、Codex への直接アクセス
-- **ファイルエクスプローラー** - シンタックスハイライトとライブ編集対応のインタラクティブファイルツリー
-- **Git エクスプローラー** - 変更の確認、ステージング、コミット。ブランチの切り替えも可能
+- **レスポンシブデザイン** - デスクトップ／タブレット／モバイルでシームレスに動作し、モバイルからも Agents を利用可能
+- **インタラクティブチャット UI** - Agents とスムーズにやり取りできる内蔵チャット UI
+- **統合シェルターミナル** - 内蔵シェル機能で Agents の CLI に直接アクセス
+- **ファイルエクスプローラー** - シンタックスハイライトとライブ編集に対応したインタラクティブなファイルツリー
+- **Git エクスプローラー** - 変更の表示、ステージ、コミット。ブランチ切り替えも可能
 - **セッション管理** - 会話の再開、複数セッションの管理、履歴の追跡
-- **TaskMaster AI 統合** *（オプション）* - AI 駆動のタスク計画、PRD 解析、ワークフロー自動化による高度なプロジェクト管理
-- **モデル互換性** - Claude Sonnet 4.5、Opus 4.5、GPT-5.2 に対応
-
+- **プラグインシステム** - カスタムプラグインで CloudCLI を拡張 — 新しいタブ、バックエンドサービス、連携を追加できます。[自分で構築する →](https://github.com/cloudcli-ai/cloudcli-plugin-starter)
 
 ## クイックスタート
 
-### 前提条件
+### CloudCLI Cloud（推奨）
 
-- [Node.js](https://nodejs.org/) v22 以上
-- [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code) のインストールと設定、および/または
-- [Cursor CLI](https://docs.cursor.com/en/cli/overview) のインストールと設定、および/または
-- [Codex](https://developers.openai.com/codex) のインストールと設定
+最速で始める方法 — ローカルのセットアップは不要です。Web、モバイルアプリ、API、またはお気に入りの IDE からアクセスできる、フルマネージドでコンテナ化された開発環境を利用できます。
 
-### ワンクリック実行（推奨）
+**[CloudCLI Cloud を始める](https://cloudcli.ai)**
 
-インストール不要、直接実行：
+### セルフホスト（オープンソース）
+
+#### npm
+
+**npx** で今すぐ CloudCLI UI を試せます（**Node.js** v22+ が必要）：
 
 ```bash
-npx @siteboon/claude-code-ui
+npx @cloudcli-ai/cloudcli
 ```
 
-サーバーが起動し、`http://localhost:3001`（または設定した PORT）でアクセスできます。
-
-**再起動**: サーバーを停止した後、同じ `npx` コマンドを再度実行するだけです
-### グローバルインストール（定期的に使用する場合）
-
-頻繁に使用する場合は、一度だけグローバルインストール：
+または、普段使いするなら **グローバル** にインストール：
 
 ```bash
-npm install -g @siteboon/claude-code-ui
+npm install -g @cloudcli-ai/cloudcli
+cloudcli
 ```
 
-シンプルなコマンドで起動：
+`http://localhost:3001` を開いてください — 既存のセッションは自動的に検出されます。
 
-```bash
-claude-code-ui
-```
+より詳細な設定オプション、PM2、リモートサーバー設定などについては **[ドキュメントはこちら →](https://cloudcli.ai/docs)** を参照してください。
 
+#### Docker Sandboxes（実験的）
 
-**再起動**: Ctrl+C で停止し、`claude-code-ui` を再度実行します。
-
-**アップデート**:
-```bash
-cloudcli update
-```
-
-### CLI の使い方
-
-グローバルインストール後、`claude-code-ui` と `cloudcli` コマンドが使用できます：
-
-| コマンド / オプション | 短縮形 | 説明 |
-|------------------|-------|-------------|
-| `cloudcli` または `claude-code-ui` | | サーバーを起動（デフォルト） |
-| `cloudcli start` | | サーバーを明示的に起動 |
-| `cloudcli status` | | 設定とデータの場所を表示 |
-| `cloudcli update` | | 最新バージョンに更新 |
-| `cloudcli help` | | ヘルプ情報を表示 |
-| `cloudcli version` | | バージョン情報を表示 |
-| `--port <port>` | `-p` | サーバーポートを設定（デフォルト: 3001） |
-| `--database-path <path>` | | カスタムデータベースの場所を設定 |
-
-**例:**
-```bash
-cloudcli                          # デフォルト設定で起動
-cloudcli -p 8080              # カスタムポートで起動
-cloudcli status                   # 現在の設定を表示
-```
-
-### バックグラウンドサービスとして実行（本番環境推奨）
-
-本番環境では、PM2（Process Manager 2）を使用して Claude Code UI をバックグラウンドサービスとして実行します：
-
-#### PM2 のインストール
-
-```bash
-npm install -g pm2
-```
-
-#### バックグラウンドサービスとして起動
-
-```bash
-# バックグラウンドでサーバーを起動
-pm2 start claude-code-ui --name "claude-code-ui"
-
-# または短いエイリアスを使用
-pm2 start cloudcli --name "claude-code-ui"
-
-# カスタムポートで起動
-pm2 start cloudcli --name "claude-code-ui" -- --port 8080
-```
-
-
-#### システム起動時の自動起動
-
-システム起動時に Claude Code UI を自動的に起動するには：
-
-```bash
-# プラットフォーム用の起動スクリプトを生成
-pm2 startup
-
-# 現在のプロセスリストを保存
-pm2 save
-```
-
-
-### ローカル開発インストール
-
-1. **リポジトリをクローン:**
-```bash
-git clone https://github.com/siteboon/claudecodeui.git
-cd claudecodeui
-```
-
-2. **依存関係をインストール:**
-```bash
-npm install
-```
-
-3. **環境を設定:**
-```bash
-cp .env.example .env
-# お好みの設定で .env を編集
-```
-
-4. **アプリケーションを起動:**
-```bash
-# 開発モード（ホットリロード付き）
-npm run dev
+ハイパーバイザーレベルの分離でエージェントをサンドボックスで実行します。デフォルトでは Claude Code が起動します。[`sbx` CLI](https://docs.docker.com/ai/sandboxes/get-started/) が必要です。
 
 ```
-アプリケーションは .env で指定したポートで起動します
+npx @cloudcli-ai/cloudcli@latest sandbox ~/my-project
+```
 
-5. **ブラウザを開く:**
-   - 開発: `http://localhost:3001`
+Claude Code、Codex、Gemini CLI に対応。詳細は[サンドボックスのドキュメント](docker/)をご覧ください。
+
+---
+
+## どちらの選択肢が適していますか？
+
+CloudCLI UI は、CloudCLI Cloud を支えるオープンソースの UI レイヤーです。自分のマシンにセルフホストすることも、フルマネージドのクラウド環境、チーム機能、より深い統合を備えた CloudCLI Cloud を使うこともできます。
+
+| | CloudCLI UI（セルフホスト） | CloudCLI Cloud |
+|---|---|---|
+| **対象ユーザー** | 自分のマシン上でローカルの agent セッションに対してフル UI を使いたい開発者 | クラウド上で動く agents をどこからでも利用したいチーム／開発者 |
+| **アクセス方法** | ブラウザ（`[yourip]:port`） | ブラウザ、任意の IDE、REST API、n8n |
+| **セットアップ** | `npx @cloudcli-ai/cloudcli` | セットアップ不要 |
+| **マシンの稼働継続** | はい | いいえ |
+| **モバイルアクセス** | 同一ネットワーク内の任意のブラウザ | 任意のデバイス（ネイティブアプリも準備中） |
+| **利用可能なセッション** | `~/.claude` から全セッションを自動検出 | クラウド環境内の全セッション |
+| **対応エージェント** | Claude Code、Cursor CLI、Codex、Gemini CLI | Claude Code、Cursor CLI、Codex、Gemini CLI |
+| **ファイルエクスプローラとGit** | はい（UI に内蔵） | はい（UI に内蔵） |
+| **MCP設定** | UI で管理し、ローカルの `~/.claude` 設定と同期 | UI で管理 |
+| **IDEアクセス** | ローカル IDE | クラウド環境に接続された任意の IDE |
+| **REST API** | はい | はい |
+| **n8n ノード** | いいえ | はい |
+| **チーム共有** | いいえ | はい |
+| **料金プラン** | 無料（オープンソース） | 月 $7〜 |
+
+> どちらの選択肢でも、AI のサブスクリプション（Claude、Cursor など）はご自身のものを使用します — CloudCLI が提供するのは環境であり、AI そのものではありません。
+
+---
 
 ## セキュリティとツール設定
 
-**重要なお知らせ**: すべての Claude Code ツールは**デフォルトで無効**になっています。これにより、潜在的に有害な操作が自動的に実行されることを防ぎます。
+**🔒 重要なお知らせ** すべての Claude Code ツールは **デフォルトで無効** です。これにより、潜在的に有害な操作が自動的に実行されることを防ぎます。
 
 ### ツールの有効化
 
-Claude Code の全機能を使用するには、手動でツールを有効にする必要があります：
-
 1. **ツール設定を開く** - サイドバーの歯車アイコンをクリック
-2. **選択的に有効化** - 必要なツールのみを有効にする
-3. **設定を適用** - 環境設定はローカルに保存されます
+2. **必要なツールだけを選んで有効化** - 本当に使うものだけをオンにする
+3. **設定を適用** - 設定内容はローカルに保存されます
 
 <div align="center">
 
 ![ツール設定モーダル](public/screenshots/tools-modal.png)
-*ツール設定インターフェース - 必要なものだけを有効にしましょう*
+*Tools 設定画面 - 必要なものだけを有効にしてください*
 
 </div>
 
-**推奨アプローチ**: 基本的なツールから有効にし、必要に応じて追加してください。これらの設定はいつでも調整できます。
+**推奨アプローチ**: まずは基本ツールだけを有効にし、必要に応じて追加してください。これらの設定は後からいつでも調整できます。
 
-## TaskMaster AI 統合 *（オプション）*
+---
 
-Claude Code UI は、高度なプロジェクト管理と AI 駆動のタスク計画のための **[TaskMaster AI](https://github.com/eyaltoledano/claude-task-master)**（別名 claude-task-master）統合をサポートしています。
+## プラグイン
 
-提供機能
-- PRD（製品要件ドキュメント）からの AI 駆動タスク生成
-- スマートなタスク分解と依存関係管理
-- ビジュアルタスクボードと進捗追跡
+CloudCLI にはプラグインシステムがあり、独自のフロントエンド UI と（必要に応じて）Node.js バックエンドを持つカスタムタブを追加できます。プラグインは **Settings > Plugins** から git リポジトリを直接指定してインストールするか、自作できます。
 
-**セットアップとドキュメント**: インストール手順、設定ガイド、使用例は [TaskMaster AI GitHub リポジトリ](https://github.com/eyaltoledano/claude-task-master)をご覧ください。
-インストール後、設定から有効にできます
+### 利用可能なプラグイン
 
+| プラグイン | 説明 |
+|---|---|
+| **[Project Stats](https://github.com/cloudcli-ai/cloudcli-plugin-starter)** | 現在のプロジェクトについて、ファイル数、コード行数、ファイル種別の内訳、最大ファイル、最近変更されたファイルを表示 |
 
-## 使用ガイド
+### 自作する
 
-### 主要機能
+**[Plugin Starter Template →](https://github.com/cloudcli-ai/cloudcli-plugin-starter)** — このリポジトリを fork して独自プラグインを作れます。フロントエンド描画、ライブコンテキスト更新、バックエンドサーバーへの RPC 通信を含む動作例が入っています。
 
-#### プロジェクト管理
-Claude Code、Cursor、Codex のセッションが利用可能な場合、自動的に検出しプロジェクトとしてグループ化します
-- **プロジェクト操作** - プロジェクトの名前変更、削除、整理
-- **スマートナビゲーション** - 最近のプロジェクトやセッションへのクイックアクセス
-- **MCP サポート** - UI から独自の MCP サーバーを追加
+**[プラグインのドキュメント →](https://cloudcli.ai/docs/plugin-overview)** — プラグイン API、manifest 形式、セキュリティモデルなどの完全ガイド。
 
-#### チャットインターフェース
-- **レスポンシブチャットまたは Claude Code/Cursor CLI/Codex CLI を使用** - アダプティブチャットインターフェースを使用するか、シェルボタンで選択した CLI に接続できます
-- **リアルタイム通信** - WebSocket 接続で選択した CLI（Claude Code/Cursor/Codex）からレスポンスをストリーミング
-- **セッション管理** - 以前の会話を再開、または新しいセッションを開始
-- **メッセージ履歴** - タイムスタンプとメタデータ付きの完全な会話履歴
-- **マルチフォーマット対応** - テキスト、コードブロック、ファイル参照
+---
+## FAQ
 
-#### ファイルエクスプローラーとエディター
-- **インタラクティブファイルツリー** - 展開/折りたたみナビゲーションでプロジェクト構造を閲覧
-- **ライブファイル編集** - インターフェースで直接ファイルの読み取り、変更、保存
-- **シンタックスハイライト** - 複数のプログラミング言語に対応
-- **ファイル操作** - ファイルやディレクトリの作成、名前変更、削除
+<details>
+<summary>Claude Code Remote Control とはどう違いますか？</summary>
 
-#### Git エクスプローラー
+Claude Code Remote Control は、ローカル端末で既に動作しているセッションへメッセージを送れる仕組みです。マシンを起動したままにし、端末も開いたままにする必要があり、ネットワーク接続がない状態が約 10 分続くとセッションがタイムアウトします。
 
+CloudCLI UI と CloudCLI Cloud は、Claude Code の横に別物として存在するのではなく、Claude Code を拡張します — MCP サーバー、権限、設定、セッションは Claude Code がネイティブに使うものと完全に同一です。複製したり、別系統で管理したりしません。
 
-#### TaskMaster AI 統合 *（オプション）*
-- **ビジュアルタスクボード** - 開発タスク管理のためのカンバンスタイルインターフェース
-- **PRD パーサー** - 製品要件ドキュメントを作成し、構造化されたタスクに変換
-- **進捗追跡** - リアルタイムのステータス更新と完了追跡
+- **すべてのセッションにアクセス** — CloudCLI UI は `~/.claude` フォルダのすべてのセッションを自動検出します。Remote Control は、Claude モバイルアプリで利用可能にするため、1つのアクティブセッションだけを公開します。
+- **設定はあなたの設定** — CloudCLI UI で変更した MCP サーバー、ツール権限、プロジェクト構成は、Claude Code の設定に直接書き込まれて即座に反映され、その逆（Claude Code での変更が UI に反映）も同様です。
+- **対応エージェントがさらに充実** — Claude Code に加えて Cursor CLI、Codex、Gemini CLI にも対応しています。
+- **チャット窓だけではない完全な UI** — ファイルエクスプローラー、Git 統合、MCP 管理、シェル端末などがすべて組み込まれています。
+- **CloudCLI Cloud はクラウド上で稼働** — ノートパソコンを閉じてもエージェントは動き続けます。監視が要る端末も、スリープ防止も不要です。
 
-#### セッション管理
-- **セッション永続化** - すべての会話を自動保存
-- **セッション整理** - プロジェクトとタイムスタンプでセッションをグループ化
-- **セッション操作** - 会話履歴の名前変更、削除、エクスポート
-- **クロスデバイス同期** - どのデバイスからでもセッションにアクセス
+</details>
 
-### モバイルアプリ
-- **レスポンシブデザイン** - すべての画面サイズに最適化
-- **タッチフレンドリーインターフェース** - スワイプジェスチャーとタッチナビゲーション
-- **モバイルナビゲーション** - 親指で操作しやすいボトムタブバー
-- **アダプティブレイアウト** - 折りたたみ可能なサイドバーとスマートコンテンツ優先順位
-- **ホーム画面にショートカットを追加** - ホーム画面にショートカットを追加すると、アプリが PWA のように動作します
+<details>
+<summary>AI のサブスクリプションは別途支払いが必要ですか？</summary>
 
-## アーキテクチャ
+はい。CloudCLI は環境を提供するものであり、AI は含まれません。Claude、Cursor、Codex、または Gemini のサブスクリプションはご自身でご用意ください。CloudCLI Cloud のホスティング環境はそれに加えて月額 $7 から提供されます。
 
-### システム概要
+</details>
 
-```
-┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
-│   Frontend      │    │   Backend       │    │  Agent     │
-│   (React/Vite)  │◄──►│ (Express/WS)    │◄──►│  Integration    │
-│                 │    │                 │    │                │
-└─────────────────┘    └─────────────────┘    └─────────────────┘
-```
+<details>
+<summary>CloudCLI UI をスマホで使えますか？</summary>
 
-### バックエンド (Node.js + Express)
-- **Express サーバー** - 静的ファイル配信付きの RESTful API
-- **WebSocket サーバー** - チャットとプロジェクト更新のための通信
-- **エージェント統合 (Claude Code / Cursor CLI / Codex)** - プロセスの生成と管理
-- **ファイルシステム API** - プロジェクト向けファイルブラウザの公開
+はい。セルフホストの場合は、自身のマシンでサーバーを起動し、ネットワーク内のブラウザで `[yourip]:port` を開いてください。CloudCLI Cloud を使う場合は、任意のデバイスからアクセスできます。VPN もポートフォワーディングも不要で、セットアップも不要です。ネイティブアプリも開発中です。
 
-### フロントエンド (React + Vite)
-- **React 18** - hooks を使用したモダンなコンポーネントアーキテクチャ
-- **CodeMirror** - シンタックスハイライト対応の高度なコードエディター
+</details>
 
+<details>
+<summary>UI で加えた変更はローカルの Claude Code 設定に影響しますか？</summary>
 
+はい、セルフホストの場合です。CloudCLI UI は Claude Code がネイティブに使う `~/.claude` 設定を読み書きします。UI から追加した MCP サーバーは即座に Claude Code に反映され、その逆も同様です。
 
+</details>
 
-### コントリビューション
+---
 
-コントリビューションを歓迎します！コミット規約、開発ワークフロー、リリースプロセスの詳細は [Contributing Guide](CONTRIBUTING.md) をご覧ください。
-
-## トラブルシューティング
-
-### よくある問題と解決方法
-
-
-#### 「Claude プロジェクトが見つかりません」
-**問題**: UI にプロジェクトが表示されない、またはプロジェクトリストが空
-**解決方法**:
-- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) が正しくインストールされていることを確認
-- 少なくとも1つのプロジェクトディレクトリで `claude` コマンドを実行して初期化
-- `~/.claude/projects/` ディレクトリが存在し、適切な権限があることを確認
-
-#### ファイルエクスプローラーの問題
-**問題**: ファイルが読み込まれない、権限エラー、空のディレクトリ
-**解決方法**:
-- プロジェクトディレクトリの権限を確認（ターミナルで `ls -la`）
-- プロジェクトパスが存在しアクセス可能であることを確認
-- 詳細なエラーメッセージについてはサーバーコンソールログを確認
-- プロジェクト範囲外のシステムディレクトリにアクセスしていないことを確認
+## コミュニティとサポート
 
+- **[ドキュメント](https://cloudcli.ai/docs)** — インストール、設定、機能、トラブルシューティング
+- **[Discord](https://discord.gg/buxwujPNRE)** — ヘルプを得たり、ユーザー同士で交流したりできます
+- **[GitHub Issues](https://github.com/siteboon/claudecodeui/issues)** — バグ報告と機能要望
+- **[コントリビューションガイド](CONTRIBUTING.md)** — プロジェクトへの貢献方法
 
 ## ライセンス
 
-GNU General Public License v3.0 - 詳細は [LICENSE](LICENSE) ファイルをご覧ください。
+GNU General Public License v3.0 - 詳細は [LICENSE](LICENSE) ファイルを参照してください。
 
-このプロジェクトはオープンソースであり、GPL v3 ライセンスの下で自由に使用、変更、配布できます。
+このプロジェクトはオープンソースであり、GPL v3 ライセンスの下で無料で使用、修正、再配布できます。
 
 ## 謝辞
 
 ### 使用技術
+
 - **[Claude Code](https://docs.anthropic.com/en/docs/claude-code)** - Anthropic の公式 CLI
 - **[Cursor CLI](https://docs.cursor.com/en/cli/overview)** - Cursor の公式 CLI
 - **[Codex](https://developers.openai.com/codex)** - OpenAI Codex
+- **[Gemini-CLI](https://geminicli.com/)** - Google Gemini CLI
 - **[React](https://react.dev/)** - ユーザーインターフェースライブラリ
 - **[Vite](https://vitejs.dev/)** - 高速ビルドツールと開発サーバー
-- **[Tailwind CSS](https://tailwindcss.com/)** - ユーティリティファースト CSS フレームワーク
-- **[CodeMirror](https://codemirror.net/)** - 高度なコードエディター
-- **[TaskMaster AI](https://github.com/eyaltoledano/claude-task-master)** *（オプション）* - AI 駆動のプロジェクト管理とタスク計画
+- **[Tailwind CSS](https://tailwindcss.com/)** - ユーティリティファーストの CSS フレームワーク
+- **[CodeMirror](https://codemirror.net/)** - 高度なコードエディタ
+- **[TaskMaster AI](https://github.com/eyaltoledano/claude-task-master)** *(オプション)* - AI を活用したプロジェクト管理とタスク計画
 
-## サポートとコミュニティ
-
-### 最新情報を入手
-- このリポジトリに **Star** をつけてサポートを表明
-- **Watch** で更新や新リリースを確認
-- プロジェクトを **Follow** してお知らせを受け取る
-
-### スポンサー
-- [Siteboon - AI powered website builder](https://siteboon.ai)
+## スポンサー
+- [Siteboon - AI を活用したウェブサイトビルダー](https://siteboon.ai)
 ---
 
 <div align="center">

README.ko.md

@@ -1,12 +1,23 @@
 <div align="center">
-  <img src="public/logo.svg" alt="Claude Code UI" width="64" height="64">
+  <img src="public/logo.svg" alt="CloudCLI UI" width="64" height="64">
   <h1>Cloud CLI (일명 Claude Code UI)</h1>
+  <p><a href="https://docs.anthropic.com/en/docs/claude-code">Claude Code</a>, <a href="https://docs.cursor.com/en/cli/overview">Cursor CLI</a>, <a href="https://developers.openai.com/codex">Codex</a>, <a href="https://geminicli.com/">Gemini-CLI</a> 용 데스크톱 및 모바일 UI입니다.<br>로컬 또는 원격에서 실행하여 어디서나 활성 프로젝트와 세션을 확인하세요.</p>
 </div>
 
+<p align="center">
+  <a href="https://cloudcli.ai">CloudCLI Cloud</a> · <a href="https://cloudcli.ai/docs">문서</a> · <a href="https://discord.gg/buxwujPNRE">Discord</a> · <a href="https://github.com/siteboon/claudecodeui/issues">버그 신고</a> · <a href="CONTRIBUTING.md">기여 안내</a>
+</p>
 
-[Claude Code](https://docs.anthropic.com/en/docs/claude-code), [Cursor CLI](https://docs.cursor.com/en/cli/overview) 및 [Codex](https://developers.openai.com/codex)를 위한 데스크톱 및 모바일 UI입니다. 로컬 또는 원격으로 사용하여 Claude Code, Cursor 또는 Codex의 활성 프로젝트와 세션을 확인하고, 어디서든(모바일 또는 데스크톱) 변경할 수 있습니다. 어디서든 작동하는 적절한 인터페이스를 제공합니다.
+<p align="center">
+  <a href="https://cloudcli.ai"><img src="https://img.shields.io/badge/☁️_CloudCLI_Cloud-Try_Now-0066FF?style=for-the-badge" alt="CloudCLI Cloud"></a>
+  <a href="https://discord.gg/buxwujPNRE"><img src="https://img.shields.io/badge/Discord-Join%20Community-5865F2?style=for-the-badge&logo=discord&logoColor=white" alt="Discord 커뮤니티"></a>
+  <br><br>
+  <a href="https://trendshift.io/repositories/15586" target="_blank"><img src="https://trendshift.io/api/badge/repositories/15586" alt="siteboon%2Fclaudecodeui | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/></a>
+</p>
 
-<div align="right"><i><a href="./README.md">English</a> · <a href="./README.ru.md">Русский</a> · <b>한국어</b> · <a href="./README.zh-CN.md">中文</a> · <a href="./README.ja.md">日本語</a></i></div>
+<div align="right"><i><a href="./README.md">English</a> · <a href="./README.ru.md">Русский</a> · <a href="./README.de.md">Deutsch</a> · <b>한국어</b> · <a href="./README.zh-CN.md">中文</a> · <a href="./README.ja.md">日本語</a></i></div>
+
+---
 
 ## 스크린샷
 
@@ -15,14 +26,14 @@
 <table>
 <tr>
 <td align="center">
-<h3>데스크톱 뷰</h3>
-<img src="public/screenshots/desktop-main.png" alt="Desktop Interface" width="400">
+<h3>데스크톱 보기</h3>
+<img src="public/screenshots/desktop-main.png" alt="데스크톱 인터페이스" width="400">
 <br>
 <em>프로젝트 개요와 채팅을 보여주는 메인 인터페이스</em>
 </td>
 <td align="center">
 <h3>모바일 경험</h3>
-<img src="public/screenshots/mobile-chat.png" alt="Mobile Interface" width="250">
+<img src="public/screenshots/mobile-chat.png" alt="모바일 인터페이스" width="250">
 <br>
 <em>터치 내비게이션이 포함된 반응형 모바일 디자인</em>
 </td>
@@ -30,316 +41,202 @@
 <tr>
 <td align="center" colspan="2">
 <h3>CLI 선택</h3>
-<img src="public/screenshots/cli-selection.png" alt="CLI Selection" width="400">
+<img src="public/screenshots/cli-selection.png" alt="CLI 선택" width="400">
 <br>
-<em>Claude Code, Cursor CLI, Codex 중 선택</em>
+<em>Claude Code, Gemini, Cursor CLI 및 Codex 중 선택</em>
 </td>
 </tr>
 </table>
 
-
-
 </div>
 
 ## 기능
 
-- **반응형 디자인** - 데스크톱, 태블릿, 모바일에서 원활하게 작동하여 모바일에서도 Claude Code, Cursor 또는 Codex를 사용할 수 있습니다
-- **대화형 채팅 인터페이스** - Claude Code, Cursor 또는 Codex와 원활하게 소통하는 내장 채팅 인터페이스
-- **통합 셸 터미널** - 내장 셸 기능을 통한 Claude Code, Cursor CLI 또는 Codex 직접 접근
-- **파일 탐색기** - 구문 강조 및 실시간 편집이 가능한 대화형 파일 트리
-- **Git 탐색기** - 변경사항 보기, 스테이징 및 커밋. 브랜치 전환도 가능
-- **세션 관리** - 대화 재개, 여러 세션 관리 및 기록 추적
-- **TaskMaster AI 통합** *(선택사항)* - AI 기반 작업 계획, PRD 분석 및 워크플로우 자동화를 통한 고급 프로젝트 관리
-- **모델 호환성** - Claude Sonnet 4.5, Opus 4.5 및 GPT-5.2 지원
-
+- **반응형 디자인** - 데스크톱, 태블릿, 모바일을 아우르는 매끄러운 경험으로 어디서든 Agents를 사용할 수 있습니다
+- **대화형 채팅 인터페이스** - 내장된 채팅 UI를 통해 에이전트와 자연스럽게 소통
+- **통합 셸 터미널** - 셸 기능을 통해 Agents CLI에 직접 접근
+- **파일 탐색기** - 구문 강조 및 실시간 편집을 갖춘 인터랙티브 파일 트리
+- **Git 탐색기** - 변경 사항 보기, 스테이징 및 커밋. 브랜치 전환 기능 포함
+- **세션 관리** - 대화를 재개하고, 여러 세션을 관리하며 기록을 추적
+- **플러그인 시스템** - 커스텀 탭, 백엔드 서비스, 통합을 추가하여 CloudCLI 확장. [직접 빌드 →](https://github.com/cloudcli-ai/cloudcli-plugin-starter)
+- **TaskMaster AI 통합** *(선택사항)* - AI 중심의 작업 계획, PRD 파싱, 워크플로 자동화를 통한 고급 프로젝트 관리
+- **모델 호환성** - Claude, GPT, Gemini 모델 계열에서 작동 (`shared/modelConstants.js`에서 전체 지원 모델 확인)
 
 ## 빠른 시작
 
-### 사전 요구사항
+### CloudCLI Cloud (추천)
 
-- [Node.js](https://nodejs.org/) v22 이상
-- [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code) 설치 및 구성, 그리고/또는
-- [Cursor CLI](https://docs.cursor.com/en/cli/overview) 설치 및 구성, 그리고/또는
-- [Codex](https://developers.openai.com/codex) 설치 및 구성
+가장 빠르게 시작하는 방법 — 로컬 설정 없이도 가능합니다. 웹, 모바일 앱, API 또는 선호하는 IDE에서 이용할 수 있는 완전 관리형 컨테이너화된 개발 환경을 제공합니다.
 
-### 원클릭 실행 (권장)
+**[CloudCLI Cloud 시작하기](https://cloudcli.ai)**
 
-설치 없이 바로 실행:
+### 셀프 호스트 (오픈 소스)
+
+#### npm
+
+**npx**로 즉시 CloudCLI UI를 실행하세요 (Node.js v22+ 필요):
 
 ```bash
-npx @siteboon/claude-code-ui
+npx @cloudcli-ai/cloudcli
 ```
 
-서버가 시작되면 `http://localhost:3001` (또는 설정한 PORT)에서 접근할 수 있습니다.
-
-**재시작**: 서버를 중지한 후 동일한 `npx` 명령을 다시 실행하면 됩니다
-### 전역 설치 (정기적 사용 시)
-
-자주 사용하는 경우 한 번만 전역 설치:
+**정기적으로 사용한다면 전역 설치:**
 
 ```bash
-npm install -g @siteboon/claude-code-ui
+npm install -g @cloudcli-ai/cloudcli
+cloudcli
 ```
 
-간단한 명령으로 시작:
+`http://localhost:3001`을 열면 기존 세션이 자동으로 발견됩니다.
 
-```bash
-claude-code-ui
-```
+자세한 구성 옵션, PM2, 원격 서버 설정 등은 **[문서 →](https://cloudcli.ai/docs)**를 참고하세요.
 
+#### Docker Sandboxes (실험적)
 
-**재시작**: Ctrl+C로 중지한 후 `claude-code-ui`를 다시 실행합니다.
-
-**업데이트**:
-```bash
-cloudcli update
-```
-
-### CLI 사용법
-
-전역 설치 후 `claude-code-ui`와 `cloudcli` 명령을 사용할 수 있습니다:
-
-| 명령 / 옵션 | 약어 | 설명 |
-|------------------|-------|-------------|
-| `cloudcli` 또는 `claude-code-ui` | | 서버 시작 (기본값) |
-| `cloudcli start` | | 서버 명시적 시작 |
-| `cloudcli status` | | 구성 및 데이터 위치 표시 |
-| `cloudcli update` | | 최신 버전으로 업데이트 |
-| `cloudcli help` | | 도움말 정보 표시 |
-| `cloudcli version` | | 버전 정보 표시 |
-| `--port <port>` | `-p` | 서버 포트 설정 (기본값: 3001) |
-| `--database-path <path>` | | 사용자 지정 데이터베이스 위치 설정 |
-
-**예시:**
-```bash
-cloudcli                          # 기본 설정으로 시작
-cloudcli -p 8080              # 사용자 지정 포트로 시작
-cloudcli status                   # 현재 구성 표시
-```
-
-### 백그라운드 서비스로 실행 (프로덕션 권장)
-
-프로덕션 환경에서는 PM2(Process Manager 2)를 사용하여 Claude Code UI를 백그라운드 서비스로 실행하세요:
-
-#### PM2 설치
-
-```bash
-npm install -g pm2
-```
-
-#### 백그라운드 서비스로 시작
-
-```bash
-# 백그라운드에서 서버 시작
-pm2 start claude-code-ui --name "claude-code-ui"
-
-# 또는 짧은 별칭 사용
-pm2 start cloudcli --name "claude-code-ui"
-
-# 사용자 지정 포트로 시작
-pm2 start cloudcli --name "claude-code-ui" -- --port 8080
-```
-
-
-#### 시스템 부팅 시 자동 시작
-
-시스템 부팅 시 Claude Code UI를 자동으로 시작하려면:
-
-```bash
-# 플랫폼에 맞는 시작 스크립트 생성
-pm2 startup
-
-# 현재 프로세스 목록 저장
-pm2 save
-```
-
-
-### 로컬 개발 설치
-
-1. **리포지토리 클론:**
-```bash
-git clone https://github.com/siteboon/claudecodeui.git
-cd claudecodeui
-```
-
-2. **의존성 설치:**
-```bash
-npm install
-```
-
-3. **환경 구성:**
-```bash
-cp .env.example .env
-# 원하는 설정으로 .env 파일 편집
-```
-
-4. **애플리케이션 시작:**
-```bash
-# 개발 모드 (핫 리로드 포함)
-npm run dev
+하이퍼바이저 수준 격리로 에이전트를 샌드박스에서 실행합니다. 기본 에이전트는 Claude Code입니다. [`sbx` CLI](https://docs.docker.com/ai/sandboxes/get-started/)가 필요합니다.
 
 ```
-애플리케이션은 .env에서 지정한 포트에서 시작됩니다
+npx @cloudcli-ai/cloudcli@latest sandbox ~/my-project
+```
 
-5. **브라우저 열기:**
-   - 개발: `http://localhost:3001`
+Claude Code, Codex, Gemini CLI를 지원합니다. 자세한 내용은 [샌드박스 문서](docker/)를 참고하세요.
 
-## 보안 및 도구 설정
+---
 
-**🔒 중요 공지**: 모든 Claude Code 도구는 **기본적으로 비활성화**되어 있습니다. 이는 잠재적으로 유해한 작업이 자동으로 실행되는 것을 방지합니다.
+## 어느 옵션이 적합한가요?
+
+CloudCLI UI는 CloudCLI Cloud를 구동하는 오픈 소스 UI 계층입니다. 로컬 머신에서 직접 셀프 호스트하거나, CloudCLI Cloud(완전 관리형 클라우드 환경, 팀 기능, 심화 통합 제공)를 사용할 수 있습니다.
+
+| | CloudCLI UI (셀프 호스트) | CloudCLI Cloud |
+|---|---|---|
+| **적합한 대상** | 로컬 에이전트 세션을 위한 전체 UI가 필요한 개발자 | 어디서든 접근 가능한 클라우드에서 에이전트를 운영하고자 하는 팀 및 개발자 |
+| **접근 방법** | `[yourip]:port`를 통해 브라우저 접속 | 브라우저, IDE, REST API, n8n |
+| **설정** | `npx @cloudcli-ai/cloudcli` | 설정 불필요 |
+| **기기 유지 필요 여부** | 예 (머신 켜둬야 함) | 아니오 |
+| **모바일 접근** | 네트워크 내 브라우저 | 모든 기기 (네이티브 앱 예정) |
+| **세션 접근** | `~/.claude`에서 자동 발견 | 클라우드 환경 내 세션 |
+| **지원 에이전트** | Claude Code, Cursor CLI, Codex, Gemini CLI | Claude Code, Cursor CLI, Codex, Gemini CLI |
+| **파일 탐색기 및 Git** | UI에 통합됨 | UI에 통합됨 |
+| **MCP 구성** | UI에서 관리, 로컬 `~/.claude` 설정과 동기화됨 | UI에서 관리 |
+| **IDE 접근** | 로컬 IDE | 클라우드 환경에 연결된 모든 IDE |
+| **REST API** | 예 | 예 |
+| **n8n 노드** | 아니오 | 예 |
+| **팀 공유** | 아니오 | 예 |
+| **플랫폼 비용** | 무료, 오픈 소스 | 월 $7부터 |
+
+> 둘 다 자체 AI 구독(Claude, Cursor 등)을 그대로 사용합니다 — CloudCLI는 환경만 제공합니다.
+
+---
+
+## 보안 및 도구 구성
+
+**🔒 중요 공지**: 모든 Claude Code 도구는 **기본적으로 비활성화**되어 있습니다. 이는 잠재적인 유해 작업이 자동 실행되는 것을 방지하기 위한 조치입니다.
 
 ### 도구 활성화
 
-Claude Code의 전체 기능을 사용하려면 수동으로 도구를 활성화해야 합니다:
-
-1. **도구 설정 열기** - 사이드바의 톱니바퀴 아이콘을 클릭
-2. **선택적으로 활성화** - 필요한 도구만 활성화
-3. **설정 적용** - 환경설정은 로컬에 저장됩니다
+1. **도구 설정 열기** - 사이드바의 톱니바퀴 아이콘 클릭
+2. **선택적으로 활성화** - 필요한 도구만 켜기
+3. **설정 적용** - 선호도는 로컬에 저장됨
 
 <div align="center">
 
 ![도구 설정 모달](public/screenshots/tools-modal.png)
-*도구 설정 인터페이스 - 필요한 것만 활성화하세요*
+*도구 설정 인터페이스 - 필요한 것만 켜세요*
 
 </div>
 
-**권장 접근법**: 기본 도구부터 활성화하고 필요에 따라 추가하세요. 언제든지 이 설정을 조정할 수 있습니다.
+**권장 방법**: 기본 도구를 먼저 켜고 필요할 때 추가하세요. 언제든지 조정 가능합니다.
 
-## TaskMaster AI 통합 *(선택사항)*
+---
 
-Claude Code UI는 고급 프로젝트 관리 및 AI 기반 작업 계획을 위한 **[TaskMaster AI](https://github.com/eyaltoledano/claude-task-master)**(일명 claude-task-master) 통합을 지원합니다.
+## 플러그인
 
-제공 기능
-- PRD(제품 요구사항 문서)에서 AI 기반 작업 생성
-- 스마트 작업 분해 및 의존성 관리
-- 시각적 작업 보드 및 진행 상황 추적
+CloudCLI는 커스텀 탭과 선택적 Node.js 백엔드가 포함된 플러그인 시스템을 제공합니다. Settings > Plugins에서 Git 저장소에서 플러그인을 설치하거나 직접 빌드할 수 있습니다.
 
-**설정 및 문서**: 설치 지침, 구성 가이드 및 사용 예시는 [TaskMaster AI GitHub 리포지토리](https://github.com/eyaltoledano/claude-task-master)를 방문하세요.
-설치 후 설정에서 활성화할 수 있습니다
+### 이용 가능한 플러그인
 
+| 플러그인 | 설명 |
+|---|---|
+| **[Project Stats](https://github.com/cloudcli-ai/cloudcli-plugin-starter)** | 현재 프로젝트의 파일 수, 코드 줄 수, 파일 유형 분포, 가장 큰 파일, 최근 수정 파일을 표시 |
 
-## 사용 가이드
+### 직접 만들기
 
-### 핵심 기능
+**[Plugin Starter Template →](https://github.com/cloudcli-ai/cloudcli-plugin-starter)** — 이 저장소를 포크하여 플러그인 구축. 프런트엔드 렌더링, 실시간 컨텍스트 업데이트, RPC 통신 예제 포함.
 
-#### 프로젝트 관리
-Claude Code, Cursor 또는 Codex 세션을 사용할 수 있을 때 자동으로 발견하고 프로젝트로 그룹화합니다
-- **프로젝트 작업** - 프로젝트 이름 변경, 삭제 및 정리
-- **스마트 내비게이션** - 최근 프로젝트 및 세션에 빠르게 접근
-- **MCP 지원** - UI를 통해 자체 MCP 서버 추가
+**[플러그인 문서 →](https://cloudcli.ai/docs/plugin-overview)** — 플러그인 API, 매니페스트 포맷, 보안 모델 등을 설명.
 
-#### 채팅 인터페이스
-- **반응형 채팅 또는 Claude Code/Cursor CLI/Codex CLI 사용** - 적응형 채팅 인터페이스를 사용하거나 셸 버튼을 사용하여 선택한 CLI에 연결할 수 있습니다
-- **실시간 통신** - WebSocket 연결을 통해 선택한 CLI(Claude Code/Cursor/Codex)에서 응답 스트리밍
-- **세션 관리** - 이전 대화 재개 또는 새 세션 시작
-- **메시지 기록** - 타임스탬프 및 메타데이터가 포함된 전체 대화 기록
-- **다중 형식 지원** - 텍스트, 코드 블록 및 파일 참조
+---
 
-#### 파일 탐색기 및 편집기
-- **대화형 파일 트리** - 확장/축소 내비게이션으로 프로젝트 구조 탐색
-- **실시간 파일 편집** - 인터페이스에서 직접 파일 읽기, 수정 및 저장
-- **구문 강조** - 다양한 프로그래밍 언어 지원
-- **파일 작업** - 파일 및 디렉토리 생성, 이름 변경, 삭제
+## FAQ
 
-#### Git 탐색기
+<details>
+<summary>Claude Code Remote Control과 어떻게 다른가요?</summary>
 
+Claude Code Remote Control은 이미 로컬 터미널에서 실행 중인 세션으로 메시지를 전송합니다. 이 경우 기계가 켜져 있어야 하고 터미널을 열어 둬야 하며, 네트워크 연결 없이 약 10분 후 타임아웃됩니다.
 
-#### TaskMaster AI 통합 *(선택사항)*
-- **시각적 작업 보드** - 개발 작업 관리를 위한 칸반 스타일 인터페이스
-- **PRD 파서** - 제품 요구사항 문서를 생성하고 구조화된 작업으로 변환
-- **진행 상황 추적** - 실시간 상태 업데이트 및 완료 추적
+CloudCLI UI와 CloudCLI Cloud는 Claude Code를 확장하며 별도로 존재하지 않습니다 — MCP 서버, 권한, 설정, 세션은 Claude Code에서 그대로 사용됩니다.
 
-#### 세션 관리
-- **세션 지속성** - 모든 대화 자동 저장
-- **세션 정리** - 프로젝트 및 타임스탬프별 세션 그룹화
-- **세션 작업** - 대화 기록 이름 변경, 삭제 및 내보내기
-- **크로스 디바이스 동기화** - 모든 기기에서 세션 접근
+- **모든 세션을 다룬다** — CloudCLI UI는 `~/.claude` 폴더에서 모든 세션을 자동 발견합니다. Remote Control은 단일 활성 세션만 노출합니다.
+- **설정은 그대로** — CloudCLI UI에서 변경한 MCP, 도구 권한, 프로젝트 설정은 Claude Code에 즉시 반영됩니다.
+- **지원 에이전트가 더 많음** — Claude Code, Cursor CLI, Codex, Gemini CLI 지원.
+- **전체 UI 제공** — 단일 채팅 창이 아닌 파일 탐색기, Git 통합, MCP 관리 및 셸 터미널 포함.
+- **CloudCLI Cloud는 클라우드에서 실행** — 노트북을 닫아도 에이전트가 실행됩니다. 터미널을 계속 확인할 필요 없음.
 
-### 모바일 앱
-- **반응형 디자인** - 모든 화면 크기에 최적화
-- **터치 친화적 인터페이스** - 스와이프 제스처 및 터치 내비게이션
-- **모바일 내비게이션** - 엄지 내비게이션을 위한 하단 탭 바
-- **적응형 레이아웃** - 접을 수 있는 사이드바 및 스마트 콘텐츠 우선순위
-- **홈 화면 바로가기 추가** - 홈 화면에 바로가기를 추가하면 앱이 PWA처럼 작동합니다
+</details>
 
-## 아키텍처
+<details>
+<summary>AI 구독을 별도로 결제해야 하나요?</summary>
 
-### 시스템 개요
+네. CloudCLI는 환경만 제공합니다. Claude, Cursor, Codex, Gemini 구독 비용은 별도로 부과됩니다. CloudCLI Cloud는 관리형 환경을 월 $7부터 제공합니다.
 
-```
-┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
-│   Frontend      │    │   Backend       │    │  Agent     │
-│   (React/Vite)  │◄──►│ (Express/WS)    │◄──►│  Integration    │
-│                 │    │                 │    │                │
-└─────────────────┘    └─────────────────┘    └─────────────────┘
-```
+</details>
 
-### 백엔드 (Node.js + Express)
-- **Express 서버** - 정적 파일 제공이 포함된 RESTful API
-- **WebSocket 서버** - 채팅 및 프로젝트 새로고침을 위한 통신
-- **에이전트 통합 (Claude Code / Cursor CLI / Codex)** - 프로세스 생성 및 관리
-- **파일 시스템 API** - 프로젝트를 위한 파일 브라우저 노출
+<details>
+<summary>CloudCLI UI를 휴대폰에서 사용할 수 있나요?</summary>
 
-### 프론트엔드 (React + Vite)
-- **React 18** - hooks를 사용한 현대적 컴포넌트 아키텍처
-- **CodeMirror** - 구문 강조를 지원하는 고급 코드 편집기
+네. 셀프 호스트인 경우 기계에서 서버를 실행하고 네트워크의 아무 브라우저에서 `[yourip]:port`를 열면 됩니다. CloudCLI Cloud는 어떤 기기에서도 열 수 있으며, 네이티브 앱도 준비 중입니다.
 
+</details>
 
+<details>
+<summary>UI에서 변경하면 로컬 Claude Code 설정에 영향을 주나요?</summary>
 
-### 기여하기
+네, 셀프 호스트에서는 그렇습니다. CloudCLI UI는 Claude Code가 사용하는 동일한 `~/.claude` 설정을 읽고 씁니다. UI에서 추가한 MCP 서버가 Claude Code에 즉시 나타납니다.
 
-기여를 환영합니다! 커밋 규칙, 개발 워크플로우, 릴리스 프로세스에 대한 자세한 내용은 [Contributing Guide](CONTRIBUTING.md)를 참조해주세요.
+</details>
 
-## 문제 해결
+---
 
-### 일반적인 문제 및 해결 방법
-
-
-#### "Claude 프로젝트를 찾을 수 없음"
-**문제**: UI에 프로젝트가 없거나 프로젝트 목록이 비어 있음
-**해결 방법**:
-- [Claude Code](https://docs.anthropic.com/en/docs/claude-code)가 올바르게 설치되었는지 확인
-- 초기화를 위해 최소 하나의 프로젝트 디렉토리에서 `claude` 명령 실행
-- `~/.claude/projects/` 디렉토리가 존재하고 적절한 권한이 있는지 확인
-
-#### 파일 탐색기 문제
-**문제**: 파일이 로드되지 않음, 권한 오류, 빈 디렉토리
-**해결 방법**:
-- 프로젝트 디렉토리 권한 확인 (터미널에서 `ls -la`)
-- 프로젝트 경로가 존재하고 접근 가능한지 확인
-- 자세한 오류 메시지는 서버 콘솔 로그 검토
-- 프로젝트 범위 밖의 시스템 디렉토리에 접근하지 않는지 확인
+## 커뮤니티 및 지원
 
+- **[문서](https://cloudcli.ai/docs)** — 설치, 구성, 기능, 문제 해결 안내
+- **[Discord](https://discord.gg/buxwujPNRE)** — 도움 및 커뮤니티 참여
+- **[GitHub Issues](https://github.com/siteboon/claudecodeui/issues)** — 버그 보고 및 기능 요청
+- **[기여 안내](CONTRIBUTING.md)** — 프로젝트 참여 방법
 
 ## 라이선스
 
-GNU General Public License v3.0 - 자세한 내용은 [LICENSE](LICENSE) 파일을 참조하세요.
+GNU General Public License v3.0 - 자세한 내용은 [LICENSE](LICENSE) 파일 참조.
 
-이 프로젝트는 오픈 소스이며 GPL v3 라이선스에 따라 자유롭게 사용, 수정 및 배포할 수 있습니다.
+이 프로젝트는 GPL v3 라이선스 하에 오픈 소스로 공개되어 있으며 자유롭게 사용, 수정, 배포할 수 있습니다.
 
 ## 감사의 말
 
 ### 사용 기술
-- **[Claude Code](https://docs.anthropic.com/en/docs/claude-code)** - Anthropic의 공식 CLI
-- **[Cursor CLI](https://docs.cursor.com/en/cli/overview)** - Cursor의 공식 CLI
+- **[Claude Code](https://docs.anthropic.com/en/docs/claude-code)** - Anthropic 공식 CLI
+- **[Cursor CLI](https://docs.cursor.com/en/cli/overview)** - Cursor 공식 CLI
 - **[Codex](https://developers.openai.com/codex)** - OpenAI Codex
+- **[Gemini-CLI](https://geminicli.com/)** - Google Gemini CLI
 - **[React](https://react.dev/)** - 사용자 인터페이스 라이브러리
 - **[Vite](https://vitejs.dev/)** - 빠른 빌드 도구 및 개발 서버
 - **[Tailwind CSS](https://tailwindcss.com/)** - 유틸리티 우선 CSS 프레임워크
-- **[CodeMirror](https://codemirror.net/)** - 고급 코드 편집기
+- **[CodeMirror](https://codemirror.net/)** - 고급 코드 에디터
 - **[TaskMaster AI](https://github.com/eyaltoledano/claude-task-master)** *(선택사항)* - AI 기반 프로젝트 관리 및 작업 계획
 
-## 지원 및 커뮤니티
-
-### 최신 정보 받기
-- 이 리포지토리에 **Star**를 눌러 지지를 표시하세요
-- **Watch**로 업데이트 및 새 릴리스를 확인하세요
-- 프로젝트를 **Follow**하여 공지사항을 받으세요
-
 ### 스폰서
 - [Siteboon - AI powered website builder](https://siteboon.ai)
 ---
 
 <div align="center">
-  <strong>Claude Code, Cursor 및 Codex 커뮤니티를 위해 정성껏 만들었습니다.</strong>
+  <strong>Claude Code, Cursor, Codex 커뮤니티를 위해 정성껏 제작되었습니다.</strong>
 </div>

README.md

@@ -15,7 +15,7 @@
   <a href="https://trendshift.io/repositories/15586" target="_blank"><img src="https://trendshift.io/api/badge/repositories/15586" alt="siteboon%2Fclaudecodeui | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/></a>
 </p>
 
-<div align="right"><i><b>English</b> · <a href="./README.ru.md">Русский</a> · <a href="./README.ko.md">한국어</a> · <a href="./README.zh-CN.md">中文</a> · <a href="./README.ja.md">日本語</a></i></div>
+<div align="right"><i><b>English</b> · <a href="./README.ru.md">Русский</a> · <a href="./README.de.md">Deutsch</a> · <a href="./README.ko.md">한국어</a> · <a href="./README.zh-CN.md">中文</a> · <a href="./README.ja.md">日本語</a></i></div>
 
 ---
 
@@ -76,48 +76,58 @@ The fastest way to get started — no local setup required. Get a fully managed,
 
 ### Self-Hosted (Open source)
 
+#### npm
+
 Try CloudCLI UI instantly with **npx** (requires **Node.js** v22+):
 
 ```
-npx @siteboon/claude-code-ui
+npx @cloudcli-ai/cloudcli
 ```
 
 Or install **globally** for regular use:
 
 ```
-npm install -g @siteboon/claude-code-ui
+npm install -g @cloudcli-ai/cloudcli
 cloudcli
 ```
 
 Open `http://localhost:3001` — all your existing sessions are discovered automatically.
 
-Visit the **[documentation →](https://cloudcli.ai/docs)** for more full configuration options, PM2, remote server setup and more
+Visit the **[documentation →](https://cloudcli.ai/docs)** for full configuration options, PM2, remote server setup and more.
+
+#### Docker Sandboxes (Experimental)
+
+Run agents in isolated sandboxes with hypervisor-level isolation. Starts Claude Code by default. Requires the [`sbx` CLI](https://docs.docker.com/ai/sandboxes/get-started/).
+
+```
+npx @cloudcli-ai/cloudcli@latest sandbox ~/my-project
+```
+
+Supports Claude Code, Codex, and Gemini CLI. See the [sandbox docs](docker/) for setup and advanced options.
 
 
 ---
 
 ## Which option is right for you?
 
-CloudCLI UI is the open source UI layer that powers CloudCLI Cloud. You can self-host it on your own machine, or use CloudCLI Cloud which builds on top of it with a full managed cloud environment, team features, and deeper integrations.
+CloudCLI UI is the open source UI layer that powers CloudCLI Cloud. You can self-host it on your own machine, run it in a Docker sandbox for isolation, or use CloudCLI Cloud for a fully managed environment.
 
-| | CloudCLI UI (Self-hosted) | CloudCLI Cloud |
-|---|---|---|
-| **Best for** | Developers who want a full UI for local agent sessions on their own machine | Teams and developers who want agents running in the cloud, accessible from anywhere |
-| **How you access it** | Browser via `[yourip]:port` | Browser, any IDE, REST API, n8n |
-| **Setup** | `npx @siteboon/claude-code-ui` | No setup required |
-| **Machine needs to stay on** | Yes | No |
-| **Mobile access** | Any browser on your network | Any device, native app coming |
-| **Sessions available** | All sessions auto-discovered from `~/.claude` | All sessions within your cloud environment |
-| **Agents supported** | Claude Code, Cursor CLI, Codex, Gemini CLI | Claude Code, Cursor CLI, Codex, Gemini CLI |
-| **File explorer and Git** | Yes, built into the UI | Yes, built into the UI |
-| **MCP configuration** | Managed via UI, synced with your local `~/.claude` config | Managed via UI |
-| **IDE access** | Your local IDE | Any IDE connected to your cloud environment |
-| **REST API** | Yes | Yes |
-| **n8n node** | No | Yes |
-| **Team sharing** | No | Yes |
-| **Platform cost** | Free, open source | Starts at $7/month |
+| | Self-Hosted (npm) | Self-Hosted (Docker Sandbox) *(Experimental)* | CloudCLI Cloud |
+|---|---|---|---|
+| **Best for** | Local agent sessions on your own machine | Isolated agents with web/mobile IDE | Teams who want agents in the cloud |
+| **How you access it** | Browser via `[yourip]:port` | Browser via `localhost:port` | Browser, any IDE, REST API, n8n |
+| **Setup** | `npx @cloudcli-ai/cloudcli` | `npx @cloudcli-ai/cloudcli@latest sandbox ~/project` | No setup required |
+| **Isolation** | Runs on your host | Hypervisor-level sandbox (microVM) | Full cloud isolation |
+| **Machine needs to stay on** | Yes | Yes | No |
+| **Mobile access** | Any browser on your network | Any browser on your network | Any device, native app coming |
+| **Agents supported** | Claude Code, Cursor CLI, Codex, Gemini CLI | Claude Code, Codex, Gemini CLI | Claude Code, Cursor CLI, Codex, Gemini CLI |
+| **File explorer and Git** | Yes | Yes | Yes |
+| **MCP configuration** | Synced with `~/.claude` | Managed via UI | Managed via UI |
+| **REST API** | Yes | Yes | Yes |
+| **Team sharing** | No | No | Yes |
+| **Platform cost** | Free, open source | Free, open source | Starts at $7/month |
 
-> Both options use your own AI subscriptions (Claude, Cursor, etc.) — CloudCLI provides the environment, not the AI.
+> All options use your own AI subscriptions (Claude, Cursor, etc.) — CloudCLI provides the environment, not the AI.
 
 ---
 
@@ -153,6 +163,7 @@ CloudCLI has a plugin system that lets you add custom tabs with their own fronte
 | Plugin | Description |
 |---|---|
 | **[Project Stats](https://github.com/cloudcli-ai/cloudcli-plugin-starter)** | Shows file counts, lines of code, file-type breakdown, largest files, and recently modified files for your current project |
+| **[Web Terminal](https://github.com/cloudcli-ai/cloudcli-plugin-terminal)** | Full xterm.js terminal with multi-tab support|
 
 ### Build Your Own
 
@@ -212,9 +223,11 @@ Yes, for self-hosted. CloudCLI UI reads from and writes to the same `~/.claude`
 
 ## License
 
-GNU General Public License v3.0 - see [LICENSE](LICENSE) file for details.
+GNU Affero General Public License v3.0 or later (AGPL-3.0-or-later) — see [LICENSE](LICENSE) for the full text, including additional terms under Section 7.
 
-This project is open source and free to use, modify, and distribute under the GPL v3 license.
+This project is open source and free to use, modify, and distribute under the AGPL-3.0-or-later license. If you modify this software and run it as a network service, you must make your modified source code available to users of that service.
+
+CloudCLI UI  - (https://cloudcli.ai).
 
 ## Acknowledgments
 

README.ru.md

@@ -1,26 +1,28 @@
 <div align="center">
   <img src="public/logo.svg" alt="CloudCLI UI" width="64" height="64">
   <h1>Cloud CLI (aka Claude Code UI)</h1>
+  <p>Десктопный и мобильный UI для <a href="https://docs.anthropic.com/en/docs/claude-code">Claude Code</a>, <a href="https://docs.cursor.com/en/cli/overview">Cursor CLI</a>, <a href="https://developers.openai.com/codex">Codex</a> и <a href="https://geminicli.com/">Gemini-CLI</a>.<br>Используйте локально или удалённо, чтобы просматривать активные проекты и сессии отовсюду.</p>
 </div>
 
-
-Десктопный и мобильный UI для [Claude Code](https://docs.anthropic.com/en/docs/claude-code), [Cursor CLI](https://docs.cursor.com/en/cli/overview), [Codex](https://developers.openai.com/codex) и [Gemini-CLI](https://geminicli.com/). Его можно использовать локально или удаленно, чтобы просматривать активные проекты и сессии и вносить изменения откуда угодно, с мобильного или десктопа. Это дает полноценный интерфейс, который работает везде.
-
 <p align="center">
-  <a href="https://cloudcli.ai">CloudCLI Cloud</a> · <a href="https://discord.gg/buxwujPNRE">Discord</a> · <a href="https://github.com/siteboon/claudecodeui/issues">Сообщить об ошибке</a> · <a href="CONTRIBUTING.md">Участие в разработке</a>
+  <a href="https://cloudcli.ai">CloudCLI Cloud</a> · <a href="https://cloudcli.ai/docs">Документация</a> · <a href="https://discord.gg/buxwujPNRE">Discord</a> · <a href="https://github.com/siteboon/claudecodeui/issues">Сообщить об ошибке</a> · <a href="CONTRIBUTING.md">Участие в разработке</a>
 </p>
 
 <p align="center">
-  <a href="https://discord.gg/buxwujPNRE"><img src="https://img.shields.io/badge/Discord-Join%20Community-5865F2?logo=discord&logoColor=white" alt="Join our Discord"></a>
+  <a href="https://cloudcli.ai"><img src="https://img.shields.io/badge/☁️_CloudCLI_Cloud-Try_Now-0066FF?style=for-the-badge" alt="CloudCLI Cloud"></a>
+  <a href="https://discord.gg/buxwujPNRE"><img src="https://img.shields.io/badge/Discord-Join%20Community-5865F2?style=for-the-badge&logo=discord&logoColor=white" alt="Join our Discord"></a>
+  <br><br>
   <a href="https://trendshift.io/repositories/15586" target="_blank"><img src="https://trendshift.io/api/badge/repositories/15586" alt="siteboon%2Fclaudecodeui | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/></a>
 </p>
 
-<div align="right"><i><a href="./README.md">English</a> · <b>Русский</b> · <a href="./README.ko.md">한국어</a> · <a href="./README.zh-CN.md">中文</a> · <a href="./README.ja.md">日本語</a></i></div>
+<div align="right"><i><a href="./README.md">English</a> · <b>Русский</b> · <a href="./README.de.md">Deutsch</a> · <a href="./README.ko.md">한국어</a> · <a href="./README.zh-CN.md">中文</a> · <a href="./README.ja.md">日本語</a></i></div>
+
+---
 
 ## Скриншоты
 
 <div align="center">
-  
+
 <table>
 <tr>
 <td align="center">
@@ -33,7 +35,7 @@
 <h3>Мобильный режим</h3>
 <img src="public/screenshots/mobile-chat.png" alt="Mobile Interface" width="250">
 <br>
-<em>Адаптивный мобильный интерфейс с сенсорной навигацией</em>
+<em>Адаптивный мобильный дизайн с сенсорной навигацией</em>
 </td>
 </tr>
 <tr>
@@ -41,7 +43,7 @@
 <h3>Выбор CLI</h3>
 <img src="public/screenshots/cli-selection.png" alt="CLI Selection" width="400">
 <br>
-<em>Выбор между Claude Code, Cursor CLI, Codex и Gemini CLI</em>
+<em>Выбирайте между Claude Code, Gemini, Cursor CLI и Codex</em>
 </td>
 </tr>
 </table>
@@ -52,92 +54,122 @@
 
 ## Возможности
 
-- **Адаптивный дизайн** - одинаково хорошо работает на десктопе, планшете и телефоне, поэтому пользоваться агентами можно и с мобильных устройств
-- **Интерактивный чат-интерфейс** - встроенный чат для удобного взаимодействия с агентами
-- **Встроенный shell-терминал** - прямой доступ к CLI агентов через встроенную оболочку
-- **Файловый менеджер** - интерактивное дерево файлов с подсветкой синтаксиса и live-редактированием
-- **Git Explorer** - просмотр, stage и commit изменений, а также переключение веток
-- **Управление сессиями** - возобновление диалогов, работа с несколькими сессиями и история
-- **Интеграция с TaskMaster AI** *(опционально)* - расширенное управление проектами с AI-планированием задач, разбором PRD и автоматизацией workflows
-- **Совместимость с моделями** - работает с Claude Sonnet 4.5, Opus 4.5, GPT-5.2 и Gemini.
+- **Адаптивный дизайн** - одинаково хорошо работает на десктопе, планшете и телефоне, поэтому можно пользоваться агентами и с мобильных устройств
+- **Интерактивный чат-интерфейс** - встроенный чат для бесшовного общения с агентами
+- **Интегрированный shell-терминал** - прямой доступ к CLI агентов через встроенную оболочку
+- **Проводник файлов** - интерактивное дерево файлов с подсветкой синтаксиса и редактированием в реальном времени
+- **Git Explorer** - просмотр, stage и commit изменений. Также можно переключать ветки
+- **Управление сессиями** - возобновляйте диалоги, управляйте несколькими сессиями и отслеживайте историю
+- **Система плагинов** - расширяйте CloudCLI кастомными плагинами — добавляйте новые вкладки, бэкенд-сервисы и интеграции. [Создать свой →](https://github.com/cloudcli-ai/cloudcli-plugin-starter)
+- **Интеграция с TaskMaster AI** *(опционально)* - продвинутое управление проектами с планированием задач на базе AI, разбором PRD и автоматизацией workflow
+- **Совместимость с моделями** - работает с семействами моделей Claude, GPT и Gemini (см. [`shared/modelConstants.js`](shared/modelConstants.js) для полного списка поддерживаемых моделей)
 
 
 ## Быстрый старт
 
 ### CloudCLI Cloud (рекомендуется)
 
-Самый быстрый способ начать работу: локальная настройка не требуется. Вы получаете полностью управляемую контейнеризированную среду разработки с доступом из браузера, мобильного приложения, API или любимой IDE.
+Самый быстрый способ начать — локальная настройка не требуется. Получите полностью управляемую контейнеризированную среду разработки с доступом из веба, мобильного приложения, API или вашей любимой IDE.
 
 **[Начать с CloudCLI Cloud](https://cloudcli.ai)**
 
 
-### Self-Hosted (open source)
+### Self-Hosted (Open source)
 
-Попробовать CloudCLI UI можно сразу через **npx** (нужен **Node.js** v22+):
+#### npm
+
+Попробовать CloudCLI UI можно сразу через **npx** (требуется **Node.js** v22+):
 
 ```bash
-npx @siteboon/claude-code-ui
+npx @cloudcli-ai/cloudcli
 ```
 
-Или установить **глобально** для постоянного использования:
+Или установить **глобально** для регулярного использования:
 
 ```bash
-npm install -g @siteboon/claude-code-ui
+npm install -g @cloudcli-ai/cloudcli
 cloudcli
 ```
 
-Откройте `http://localhost:3001` — все существующие сессии будут обнаружены автоматически.
+Откройте `http://localhost:3001` — все ваши существующие сессии будут обнаружены автоматически.
 
-Больше вариантов настройки, PM2, удаленный сервер и остальное описаны в **[документации →](https://cloudcli.ai/docs)**
+Посетите **[документацию →](https://cloudcli.ai/docs)**, чтобы узнать про дополнительные варианты конфигурации, PM2, настройку удалённого сервера и многое другое.
 
+#### Docker Sandboxes (Экспериментально)
+
+Запускайте агентов в изолированных песочницах с гипервизорной изоляцией. По умолчанию запускается Claude Code. Требуется [`sbx` CLI](https://docs.docker.com/ai/sandboxes/get-started/).
+
+```
+npx @cloudcli-ai/cloudcli@latest sandbox ~/my-project
+```
+
+Поддерживаются Claude Code, Codex и Gemini CLI. Подробнее в [документации sandbox](docker/).
 
 ---
 
-## Какой вариант подойдет вам?
+## Какой вариант подходит вам?
 
-CloudCLI UI - это open source UI-слой, на котором построен CloudCLI Cloud. Вы можете развернуть его у себя на машине или использовать CloudCLI Cloud, который добавляет полностью управляемую облачную среду, командные функции и более глубокие интеграции.
+CloudCLI UI — это open source UI-слой, на котором построен CloudCLI Cloud. Вы можете развернуть его на своей машине или использовать CloudCLI Cloud, который добавляет полностью управляемую облачную среду, командные функции и более глубокие интеграции.
 
-| | CloudCLI UI (self-hosted) | CloudCLI Cloud |
+| | CloudCLI UI (Self-hosted) | CloudCLI Cloud |
 |---|---|---|
 | **Лучше всего подходит для** | Разработчиков, которым нужен полноценный UI для локальных агентских сессий на своей машине | Команд и разработчиков, которым нужны агенты в облаке с доступом откуда угодно |
-| **Способ доступа** | Браузер через `[yourip]:port` | Браузер, любая IDE, REST API, n8n |
-| **Настройка** | `npx @siteboon/claude-code-ui` | Настройка не требуется |
-| **Машина должна оставаться включенной** | Да | Нет |
+| **Как вы получаете доступ** | Браузер через `[yourip]:port` | Браузер, любая IDE, REST API, n8n |
+| **Настройка** | `npx @cloudcli-ai/cloudcli` | Настройка не требуется |
+| **Машина должна оставаться включённой** | Да | Нет |
 | **Доступ с мобильных устройств** | Любой браузер в вашей сети | Любое устройство, нативное приложение в разработке |
-| **Доступные сессии** | Все сессии автоматически обнаруживаются в `~/.claude` | Все сессии внутри вашей облачной среды |
+| **Доступные сессии** | Все сессии автоматически обнаруживаются из `~/.claude` | Все сессии внутри вашей облачной среды |
 | **Поддерживаемые агенты** | Claude Code, Cursor CLI, Codex, Gemini CLI | Claude Code, Cursor CLI, Codex, Gemini CLI |
-| **Файловый менеджер и Git** | Да, встроены в UI | Да, встроены в UI |
-| **Конфигурация MCP** | Управляется через UI, синхронизируется с локальным `~/.claude` | Управляется через UI |
-| **Доступ из IDE** | Ваша локальная IDE | Любая IDE, подключенная к облачной среде |
+| **Проводник файлов и Git** | Да, встроены в UI | Да, встроены в UI |
+| **Конфигурация MCP** | Управляется через UI, синхронизируется с вашим локальным конфигом `~/.claude` | Управляется через UI |
+| **Доступ из IDE** | Ваша локальная IDE | Любая IDE, подключенная к вашей облачной среде |
 | **REST API** | Да | Да |
-| **Узел n8n** | Нет | Да |
-| **Совместная работа в команде** | Нет | Да |
+| **n8n node** | Нет | Да |
+| **Совместная работа** | Нет | Да |
 | **Стоимость платформы** | Бесплатно, open source | От $7/месяц |
 
 > В обоих вариантах используются ваши собственные AI-подписки (Claude, Cursor и т.д.) — CloudCLI предоставляет среду, а не сам AI.
 
 ---
 
-## Безопасность и настройка инструментов
+## Безопасность и конфигурация инструментов
 
-**🔒 Важно**: все инструменты Claude Code **по умолчанию отключены**. Это предотвращает автоматический запуск потенциально опасных операций.
+**🔒 Важное примечание**: все инструменты Claude Code **по умолчанию отключены**. Это предотвращает автоматический запуск потенциально опасных операций.
 
 ### Включение инструментов
 
-Чтобы использовать всю функциональность Claude Code, инструменты нужно включить вручную:
+Чтобы использовать всю функциональность Claude Code, вам нужно вручную включить инструменты:
 
-1. **Откройте настройки инструментов** - нажмите на иконку шестеренки в боковой панели
-2. **Включайте выборочно** - активируйте только те инструменты, которые действительно нужны
-3. **Примените настройки** - предпочтения сохраняются локально
+1. **Откройте настройки инструментов** - нажмите на иконку шестерёнки в боковой панели
+2. **Включайте выборочно** - активируйте только те инструменты, которые вам нужны
+3. **Примените настройки** - ваши предпочтения сохраняются локально
 
 <div align="center">
 
 ![Tools Settings Modal](public/screenshots/tools-modal.png)
-*Окно настройки инструментов - включайте только то, что вам нужно*
+*Интерфейс настройки инструментов — включайте только то, что вам нужно*
 
 </div>
 
-**Рекомендуемый подход**: начните с базовых инструментов и добавляйте остальные по мере необходимости. Эти настройки всегда можно поменять позже.
+**Рекомендуемый подход**: начните с базовых инструментов и добавляйте остальные по мере необходимости. Эти настройки всегда можно изменить позже.
+
+---
+
+## Плагины
+
+У CloudCLI есть система плагинов, которая позволяет добавлять кастомные вкладки со своим frontend UI и (опционально) Node.js бэкендом. Устанавливайте плагины напрямую из git-репозиториев в **Settings > Plugins** или создавайте свои.
+
+### Доступные плагины
+
+| Плагин | Описание |
+|---|---|
+| **[Project Stats](https://github.com/cloudcli-ai/cloudcli-plugin-starter)** | Показывает количество файлов, строки кода, разбивку по типам файлов, самые большие файлы и недавно изменённые файлы для текущего проекта |
+
+### Создать свой
+
+**[Plugin Starter Template →](https://github.com/cloudcli-ai/cloudcli-plugin-starter)** — сделайте форк этого репозитория, чтобы создать свой плагин. В шаблоне есть рабочий пример с рендерингом на фронтенде, live-обновлением контекста и RPC-коммуникацией с бэкенд-сервером.
+
+**[Plugin Documentation →](https://cloudcli.ai/docs/plugin-overview)** — полный гайд по plugin API, формату манифеста, модели безопасности и другому.
 
 ---
 ## FAQ
@@ -145,38 +177,38 @@ CloudCLI UI - это open source UI-слой, на котором построе
 <details>
 <summary>Чем это отличается от Claude Code Remote Control?</summary>
 
-Claude Code Remote Control позволяет отправлять сообщения в сессию, уже запущенную в локальном терминале. При этом ваша машина должна оставаться включенной, терминал должен быть открыт, а сессии завершаются примерно через 10 минут без сетевого соединения.
+Claude Code Remote Control позволяет отправлять сообщения в сессию, которая уже запущена в вашем локальном терминале. Ваша машина должна оставаться включённой, терминал — открытым, а сессии завершаются примерно через 10 минут без сетевого соединения.
 
 CloudCLI UI и CloudCLI Cloud расширяют Claude Code, а не работают рядом с ним — ваши MCP-серверы, разрешения, настройки и сессии остаются теми же самыми, что и в нативном Claude Code. Ничего не дублируется и не управляется отдельно.
 
 Вот что это означает на практике:
 
-- **Все ваши сессии, а не одна** — CloudCLI UI автоматически находит каждую сессию из папки `~/.claude`. Remote Control предоставляет только одну активную сессию, чтобы сделать ее доступной в мобильном приложении Claude.
-- **Ваши настройки остаются вашими** — MCP-серверы, права инструментов и конфигурация проекта, измененные в CloudCLI UI, записываются напрямую в конфиг Claude Code и вступают в силу сразу же, и наоборот.
-- **Поддержка большего числа агентов** — Claude Code, Cursor CLI, Codex и Gemini CLI, а не только Claude Code.
-- **Полноценный UI, а не просто окно чата** — встроены файловый менеджер, Git-интеграция, управление MCP и shell-терминал.
-- **CloudCLI Cloud работает в облаке** — можно закрыть ноутбук, а агент продолжит работу. Не нужно держать терминал открытым и машину в активном состоянии.
+- **Все ваши сессии, а не одна** — CloudCLI UI автоматически находит каждую сессию из папки `~/.claude`. Remote Control предоставляет только одну активную сессию, чтобы сделать её доступной в мобильном приложении Claude.
+- **Ваши настройки — это ваши настройки** — MCP-серверы, права инструментов и конфигурация проекта, изменённые в CloudCLI UI, записываются напрямую в конфиг Claude Code и вступают в силу сразу же, и наоборот.
+- **Работает с большим числом агентов** — Claude Code, Cursor CLI, Codex и Gemini CLI, а не только Claude Code.
+- **Полноценный UI, а не просто окно чата** — проводник файлов, Git-интеграция, управление MCP и shell-терминал — всё встроено.
+- **CloudCLI Cloud работает в облаке** — закройте ноутбук, и агент продолжит работать. Не нужно следить за терминалом и держать машину постоянно активной.
 
 </details>
 
 <details>
 <summary>Нужно ли отдельно платить за AI-подписку?</summary>
 
-Да. CloudCLI предоставляет среду, а не сам AI. Вы используете собственную подписку Claude, Cursor, Codex или Gemini. CloudCLI Cloud стоит от $7/месяц за хостируемую среду сверх этого.
+Да. CloudCLI предоставляет среду, а не сам AI. Вы приносите свою подписку Claude, Cursor, Codex или Gemini. CloudCLI Cloud начинается от $7/месяц за хостируемую среду поверх этого.
 
 </details>
 
 <details>
 <summary>Можно ли пользоваться CloudCLI UI с телефона?</summary>
 
-Да. Для self-hosted запустите сервер на своей машине и откройте `[yourip]:port` в любом браузере внутри вашей сети. Для CloudCLI Cloud откройте сервис с любого устройства — без VPN, проброса портов и дополнительной настройки. Нативное приложение тоже разрабатывается.
+Да. Для self-hosted запустите сервер на своей машине и откройте `[yourip]:port` в любом браузере в вашей сети. Для CloudCLI Cloud откройте сервис с любого устройства — без VPN, проброса портов и дополнительной настройки. Нативное приложение тоже в разработке.
 
 </details>
 
 <details>
 <summary>Повлияют ли изменения, сделанные в UI, на мой локальный Claude Code?</summary>
 
-Да, в self-hosted режиме. CloudCLI UI читает и записывает тот же конфиг `~/.claude`, который нативно использует Claude Code. MCP-серверы, добавленные через UI, сразу появляются в Claude Code, и наоборот.
+Да, в self-hosted режиме. CloudCLI UI читает и записывает тот же конфиг `~/.claude`, который Claude Code использует нативно. MCP-серверы, добавленные через UI, сразу появляются в Claude Code, и наоборот.
 
 </details>
 
@@ -186,14 +218,14 @@ CloudCLI UI и CloudCLI Cloud расширяют Claude Code, а не работ
 
 - **[Документация](https://cloudcli.ai/docs)** — установка, настройка, возможности и устранение неполадок
 - **[Discord](https://discord.gg/buxwujPNRE)** — помощь и общение с другими пользователями
-- **[GitHub Issues](https://github.com/siteboon/claudecodeui/issues)** — баг-репорты и запросы новых функций
+- **[GitHub Issues](https://github.com/siteboon/claudecodeui/issues)** — сообщения об ошибках и запросы новых функций
 - **[Руководство для контрибьюторов](CONTRIBUTING.md)** — как участвовать в развитии проекта
 
 ## Лицензия
 
 GNU General Public License v3.0 - подробности в файле [LICENSE](LICENSE).
 
-Этот проект открыт и может свободно использоваться, изменяться и распространяться по лицензии GPL v3.
+Этот проект open source и бесплатен для использования, модификации и распространения в рамках лицензии GPL v3.
 
 ## Благодарности
 
@@ -214,5 +246,5 @@ GNU General Public License v3.0 - подробности в файле [LICENSE]
 ---
 
 <div align="center">
-  <strong>Сделано с любовью к сообществу Claude Code, Cursor и Codex.</strong>
+  <strong>Сделано с заботой для сообщества Claude Code, Cursor и Codex.</strong>
 </div>

README.zh-CN.md

@@ -1,12 +1,23 @@
 <div align="center">
-  <img src="public/logo.svg" alt="Claude Code UI" width="64" height="64">
-  <h1>Cloud CLI (又名 Claude Code UI)</h1>
+  <img src="public/logo.svg" alt="CloudCLI UI" width="64" height="64">
+  <h1>Cloud CLI（又名 Claude Code UI）</h1>
+  <p><a href="https://docs.anthropic.com/en/docs/claude-code">Claude Code</a>、<a href="https://docs.cursor.com/en/cli/overview">Cursor CLI</a>、<a href="https://developers.openai.com/codex">Codex</a> 和 <a href="https://geminicli.com/">Gemini-CLI</a> 的桌面和移动端 UI。可在本地或远程使用，从任何地方查看激活的项目与会话。</p>
 </div>
 
+<p align="center">
+  <a href="https://cloudcli.ai">CloudCLI Cloud</a> · <a href="https://cloudcli.ai/docs">文档</a> · <a href="https://discord.gg/buxwujPNRE">Discord</a> · <a href="https://github.com/siteboon/claudecodeui/issues">Bug 报告</a> · <a href="CONTRIBUTING.md">贡献指南</a>
+</p>
 
-[Claude Code](https://docs.anthropic.com/en/docs/claude-code)、[Cursor CLI](https://docs.cursor.com/en/cli/overview) 和 [Codex](https://developers.openai.com/codex) 的桌面端和移动端界面。您可以在本地或远程使用它来查看 Claude Code、Cursor 或 Codex 中的活跃项目和会话,并从任何地方(移动端或桌面端)对它们进行修改。这为您提供了一个在任何地方都能正常使用的合适界面。
+<p align="center">
+  <a href="https://cloudcli.ai"><img src="https://img.shields.io/badge/☁️_CloudCLI_Cloud-Try_Now-0066FF?style=for-the-badge" alt="CloudCLI Cloud"></a>
+  <a href="https://discord.gg/buxwujPNRE"><img src="https://img.shields.io/badge/Discord-Join%20Community-5865F2?style=for-the-badge&logo=discord&logoColor=white" alt="加入 Discord 社区"></a>
+  <br><br>
+  <a href="https://trendshift.io/repositories/15586" target="_blank"><img src="https://trendshift.io/api/badge/repositories/15586" alt="siteboon%2Fclaudecodeui | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/></a>
+</p>
 
-<div align="right"><i><a href="./README.md">English</a> · <a href="./README.ru.md">Русский</a> · <a href="./README.ko.md">한국어</a> · <b>中文</b> · <a href="./README.ja.md">日本語</a></i></div>
+<div align="right"><i><a href="./README.md">English</a> · <a href="./README.ru.md">Русский</a> · <a href="./README.de.md">Deutsch</a> · <a href="./README.ko.md">한국어</a> · <b>中文</b> · <a href="./README.ja.md">日本語</a></i></div>
+
+---
 
 ## 截图
 
@@ -16,327 +27,211 @@
 <tr>
 <td align="center">
 <h3>桌面视图</h3>
-<img src="public/screenshots/desktop-main.png" alt="Desktop Interface" width="400">
+<img src="public/screenshots/desktop-main.png" alt="桌面界面" width="400">
 <br>
-<em>显示项目概览和聊天界面的主界面</em>
+<em>显示项目概览和聊天的主界面</em>
 </td>
 <td align="center">
-<h3>移动端体验</h3>
-<img src="public/screenshots/mobile-chat.png" alt="Mobile Interface" width="250">
+<h3>移动体验</h3>
+<img src="public/screenshots/mobile-chat.png" alt="移动界面" width="250">
 <br>
-<em>具有触摸导航的响应式移动设计</em>
+<em>具有触控导航的响应式移动设计</em>
 </td>
 </tr>
 <tr>
 <td align="center" colspan="2">
 <h3>CLI 选择</h3>
-<img src="public/screenshots/cli-selection.png" alt="CLI Selection" width="400">
+<img src="public/screenshots/cli-selection.png" alt="CLI 选择" width="400">
 <br>
-<em>在 Claude Code、Cursor CLI 和 Codex 之间选择</em>
+<em>在 Claude Code、Gemini、Cursor CLI 与 Codex 之间进行选择</em>
 </td>
 </tr>
 </table>
 
-
-
 </div>
 
-## 功能特性
+## 功能
 
-- **响应式设计** - 在桌面、平板和移动设备上无缝运行,您也可以在移动端使用 Claude Code、Cursor 或 Codex
-- **交互式聊天界面** - 内置聊天界面,与 Claude Code、Cursor 或 Codex 无缝通信
-- **集成 Shell 终端** - 通过内置 shell 功能直接访问 Claude Code、Cursor CLI 或 Codex
-- **文件浏览器** - 交互式文件树,支持语法高亮和实时编辑
-- **Git 浏览器** - 查看、暂存和提交您的更改。您还可以切换分支
+- **响应式设计** - 在桌面、平板和移动设备上无缝运行，让您随时随地使用 Agents
+- **交互聊天界面** - 内置聊天 UI，轻松与 Agents 交流
+- **集成 Shell 终端** - 通过内置 shell 功能直接访问 Agents CLI
+- **文件浏览器** - 交互式文件树，支持语法高亮与实时编辑
+- **Git 浏览器** - 查看、暂存并提交更改，还可切换分支
 - **会话管理** - 恢复对话、管理多个会话并跟踪历史记录
-- **TaskMaster AI 集成** *(可选)* - 通过 AI 驱动的任务规划、PRD 解析和工作流自动化实现高级项目管理
-- **模型兼容性** - 适用于 Claude Sonnet 4.5、Opus 4.5 和 GPT-5.2
-
+- **插件系统** - 通过自定义选项卡、后端服务与集成扩展 CloudCLI。 [开始构建 →](https://github.com/cloudcli-ai/cloudcli-plugin-starter)
+- **TaskMaster AI 集成** *(可选)* - 结合 AI 任务规划、PRD 分析与工作流自动化，实现高级项目管理
+- **模型兼容性** - 支持 Claude、GPT、Gemini 模型家族（完整支持列表见 [`shared/modelConstants.js`](shared/modelConstants.js)）
 
 ## 快速开始
 
-### 前置要求
+### CloudCLI Cloud（推荐）
 
-- [Node.js](https://nodejs.org/) v22 或更高版本
-- 已安装并配置 [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code),和/或
-- 已安装并配置 [Cursor CLI](https://docs.cursor.com/en/cli/overview),和/或
-- 已安装并配置 [Codex](https://developers.openai.com/codex)
+无需本地设置即可快速启动。提供可通过网络浏览器、移动应用、API 或喜欢的 IDE 访问的完全集装式托管开发环境。
 
-### 一键操作(推荐)
+**[立即开始 CloudCLI Cloud](https://cloudcli.ai)**
 
-无需安装,直接运行:
+### 自托管（开源）
+
+#### npm
+
+启动 CloudCLI UI，只需一行 `npx`（需要 Node.js v22+）：
 
 ```bash
-npx @siteboon/claude-code-ui
+npx @cloudcli-ai/cloudcli
 ```
 
-服务器将启动并可通过 `http://localhost:3001`(或您配置的 PORT)访问。
-
-**重启**: 停止服务器后只需再次运行相同的 `npx` 命令
-
-### 全局安装(供常规使用)
-
-为了频繁使用,一次性全局安装:
+或进行全局安装，便于日常使用：
 
 ```bash
-npm install -g @siteboon/claude-code-ui
+npm install -g @cloudcli-ai/cloudcli
+cloudcli
 ```
 
-然后使用简单命令启动:
+打开 `http://localhost:3001`，系统会自动发现所有现有会话。
 
-```bash
-claude-code-ui
-```
+更多配置选项、PM2、远程服务器设置等，请参阅 **[文档 →](https://cloudcli.ai/docs)**。
 
+#### Docker Sandboxes（实验性）
 
-**重启**: 使用 Ctrl+C 停止,然后再次运行 `claude-code-ui`。
-
-**更新**:
-```bash
-cloudcli update
-```
-
-### CLI 使用方法
-
-全局安装后,您可以访问 `claude-code-ui` 和 `cloudcli` 命令:
-
-| 命令 / 选项 | 简写 | 描述 |
-|------------------|-------|-------------|
-| `cloudcli` 或 `claude-code-ui` | | 启动服务器(默认) |
-| `cloudcli start` | | 显式启动服务器 |
-| `cloudcli status` | | 显示配置和数据位置 |
-| `cloudcli update` | | 更新到最新版本 |
-| `cloudcli help` | | 显示帮助信息 |
-| `cloudcli version` | | 显示版本信息 |
-| `--port <port>` | `-p` | 设置服务器端口(默认: 3001) |
-| `--database-path <path>` | | 设置自定义数据库位置 |
-
-**示例:**
-```bash
-cloudcli                          # 使用默认设置启动
-cloudcli -p 8080              # 在自定义端口启动
-cloudcli status                   # 显示当前配置
-```
-
-### 作为后台服务运行(推荐用于生产环境)
-
-在生产环境中,使用 PM2(Process Manager 2)将 Claude Code UI 作为后台服务运行:
-
-#### 安装 PM2
-
-```bash
-npm install -g pm2
-```
-
-#### 作为后台服务启动
-
-```bash
-# 在后台启动服务器
-pm2 start claude-code-ui --name "claude-code-ui"
-
-# 或使用更短的别名
-pm2 start cloudcli --name "claude-code-ui"
-
-# 在自定义端口启动
-pm2 start cloudcli --name "claude-code-ui" -- --port 8080
-```
-
-
-#### 系统启动时自动启动
-
-要使 Claude Code UI 在系统启动时自动启动:
-
-```bash
-# 为您的平台生成启动脚本
-pm2 startup
-
-# 保存当前进程列表
-pm2 save
-```
-
-
-### 本地开发安装
-
-1. **克隆仓库:**
-```bash
-git clone https://github.com/siteboon/claudecodeui.git
-cd claudecodeui
-```
-
-2. **安装依赖:**
-```bash
-npm install
-```
-
-3. **配置环境:**
-```bash
-cp .env.example .env
-# 使用您喜欢的设置编辑 .env
-```
-
-4. **启动应用程序:**
-```bash
-# 开发模式(支持热重载)
-npm run dev
+在隔离的沙箱中运行代理，具有虚拟机管理程序级别的隔离。默认启动 Claude Code。需要 [`sbx` CLI](https://docs.docker.com/ai/sandboxes/get-started/)。
 
 ```
-应用程序将在您在 .env 中指定的端口启动
+npx @cloudcli-ai/cloudcli@latest sandbox ~/my-project
+```
 
-5. **打开浏览器:**
-   - 开发环境: `http://localhost:3001`
+支持 Claude Code、Codex 和 Gemini CLI。详情请参阅 [沙箱文档](docker/)。
+
+---
+
+## 哪个选项更适合你？
+
+CloudCLI UI 是 CloudCLI Cloud 的开源 UI 层。你可以在本地机器上自托管它，也可以使用提供团队功能与深入集成的 CloudCLI Cloud。
+
+| | CloudCLI UI（自托管） | CloudCLI Cloud |
+|---|---|---|
+| **适合对象** | 需要为本地代理会话提供完整 UI 的开发者 | 需要部署在云端，随时从任何地方访问代理的团队与开发者 |
+| **访问方式** | 通过 `[yourip]:port` 在浏览器中访问 | 浏览器、任意 IDE、REST API、n8n |
+| **设置** | `npx @cloudcli-ai/cloudcli` | 无需设置 |
+| **机器需保持开机吗** | 是 | 否 |
+| **移动端访问** | 网络内任意浏览器 | 任意设备（原生应用即将推出） |
+| **可用会话** | 自动发现 `~/.claude` 中的所有会话 | 云端环境内的会话 |
+| **支持的 Agents** | Claude Code、Cursor CLI、Codex、Gemini CLI | Claude Code、Cursor CLI、Codex、Gemini CLI |
+| **文件浏览与 Git** | 内置于 UI | 内置于 UI |
+| **MCP 配置** | UI 管理，与本地 `~/.claude` 配置同步 | UI 管理 |
+| **IDE 访问** | 本地 IDE | 任何连接到云环境的 IDE |
+| **REST API** | 是 | 是 |
+| **n8n 节点** | 否 | 是 |
+| **团队共享** | 否 | 是 |
+| **平台费用** | 免费开源 | 起价 $7/月 |
+
+> 两种方式都使用你自己的 AI 订阅（Claude、Cursor 等）— CloudCLI 提供环境，而非 AI。
+
+---
 
 ## 安全与工具配置
 
-**🔒 重要提示**: 所有 Claude Code 工具**默认禁用**。这可以防止潜在的有害操作自动运行。
+**🔒 重要提示**: 所有 Claude Code 工具默认**禁用**，可防止潜在的有害操作自动运行。
 
 ### 启用工具
 
-要使用 Claude Code 的完整功能,您需要手动启用工具:
-
-1. **打开工具设置** - 点击侧边栏中的齿轮图标
-2. **选择性启用** - 仅打开您需要的工具
-3. **应用设置** - 您的偏好设置将保存在本地
+1. **打开工具设置** - 点击侧边栏齿轮图标
+2. **选择性启用** - 仅启用所需工具
+3. **应用设置** - 偏好设置保存在本地
 
 <div align="center">
 
-![工具设置模态框](public/screenshots/tools-modal.png)
-*工具设置界面 - 仅启用您需要的内容*
+![工具设置弹窗](public/screenshots/tools-modal.png)
+*工具设置界面 - 只启用你需要的内容*
 
 </div>
 
-**推荐方法**: 首先启用基本工具,然后根据需要添加更多。您可以随时调整这些设置。
+**推荐做法**: 先启用基础工具，再根据需要添加其他工具。随时可以调整。
 
-## TaskMaster AI 集成 *(可选)*
+---
 
-Claude Code UI 支持 **[TaskMaster AI](https://github.com/eyaltoledano/claude-task-master)**(aka claude-task-master)集成,用于高级项目管理和 AI 驱动的任务规划。
+## 插件
 
-它提供
-- 从 PRD(产品需求文档)生成 AI 驱动的任务
-- 智能任务分解和依赖管理
-- 可视化任务板和进度跟踪
+CloudCLI 配备插件系统，允许你添加带自定义前端 UI 和可选 Node.js 后端的选项卡。在 Settings > Plugins 中直接从 Git 仓库安装插件，或自行开发。
 
-**设置与文档**: 访问 [TaskMaster AI GitHub 仓库](https://github.com/eyaltoledano/claude-task-master)获取安装说明、配置指南和使用示例。
-安装后,您应该能够从设置中启用它
+### 可用插件
 
+| 插件 | 描述 |
+|---|---|
+| **[Project Stats](https://github.com/cloudcli-ai/cloudcli-plugin-starter)** | 展示当前项目的文件数、代码行数、文件类型分布、最大文件以及最近修改的文件 |
 
-## 使用指南
+### 自行构建
 
-### 核心功能
+**[Plugin Starter Template →](https://github.com/cloudcli-ai/cloudcli-plugin-starter)** — Fork 该仓库以构建自己的插件。示例包括前端渲染、实时上下文更新和 RPC 通信。
 
-#### 项目管理
-当可用时,它会自动发现 Claude Code、Cursor 或 Codex 会话并将它们分组到项目中
-- **项目操作** - 重命名、删除和组织项目
-- **智能导航** - 快速访问最近的项目和会话
-- **MCP 支持** - 通过 UI 添加您自己的 MCP 服务器
+**[插件文档 →](https://cloudcli.ai/docs/plugin-overview)** — 提供插件 API、清单格式、安全模型等完整指南。
 
-#### 聊天界面
-- **使用响应式聊天或 Claude Code/Cursor CLI/Codex CLI** - 您可以使用自适应聊天界面或使用 shell 按钮连接到您选择的 CLI
-- **实时通信** - 通过 WebSocket 连接从您选择的 CLI(Claude Code/Cursor/Codex)流式传输响应
-- **会话管理** - 恢复之前的对话或启动新会话
-- **消息历史** - 带有时间戳和元数据的完整对话历史
-- **多格式支持** - 文本、代码块和文件引用
+---
 
-#### 文件浏览器与编辑器
-- **交互式文件树** - 使用展开/折叠导航浏览项目结构
-- **实时文件编辑** - 直接在界面中读取、修改和保存文件
-- **语法高亮** - 支持多种编程语言
-- **文件操作** - 创建、重命名、删除文件和目录
+## 常见问题
 
-#### Git 浏览器
+<details>
+<summary>与 Claude Code Remote Control 有何不同？</summary>
 
+Claude Code Remote Control 让你发送消息到本地终端中已经运行的会话。该方式要求你的机器保持开机，终端保持开启，断开网络后约 10 分钟会话会超时。
 
-#### TaskMaster AI 集成 *(可选)*
-- **可视化任务板** - 用于管理开发任务的看板风格界面
-- **PRD 解析器** - 创建产品需求文档并将其解析为结构化任务
-- **进度跟踪** - 实时状态更新和完成跟踪
+CloudCLI UI 与 CloudCLI Cloud 是对 Claude Code 的扩展，而非旁观 — MCP 服务器、权限、设置、会话与 Claude Code 完全一致。
 
-#### 会话管理
-- **会话持久化** - 所有对话自动保存
-- **会话组织** - 按项目和 timestamp 分组会话
-- **会话操作** - 重命名、删除和导出对话历史
-- **跨设备同步** - 从任何设备访问会话
+- **覆盖全部会话** — CloudCLI UI 会自动扫描 `~/.claude` 文件夹中的每个会话。Remote Control 只暴露当前活动的会话。
+- **设置统一** — 在 CloudCLI UI 中修改的 MCP、工具权限等设置会立即写入 Claude Code。
+- **支持更多 Agents** — Claude Code、Cursor CLI、Codex、Gemini CLI。
+- **完整 UI** — 除了聊天界面，还包括文件浏览器、Git 集成、MCP 管理和 Shell 终端。
+- **CloudCLI Cloud 保持运行于云端** — 关闭本地设备也不会中断代理运行，无需监控终端。
 
-### 移动应用
-- **响应式设计** - 针对所有屏幕尺寸进行优化
-- **触摸友好界面** - 滑动手势和触摸导航
-- **移动导航** - 底部选项卡栏,方便拇指导航
-- **自适应布局** - 可折叠侧边栏和智能内容优先级
-- **添加到主屏幕快捷方式** - 添加快捷方式到主屏幕,应用程序将像 PWA 一样运行
+</details>
 
-## 架构
+<details>
+<summary>需要额外购买 AI 订阅吗？</summary>
 
-### 系统概览
+需要。CloudCLI 只提供环境。你仍需自行获取 Claude、Cursor、Codex 或 Gemini 订阅。CloudCLI Cloud 从 $7/月起提供托管环境。
 
-```
-┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
-│   Frontend      │    │   Backend       │    │  Agent     │
-│   (React/Vite)  │◄──►│ (Express/WS)    │◄──►│  Integration    │
-│                 │    │                 │    │                │
-└─────────────────┘    └─────────────────┘    └─────────────────┘
-```
+</details>
 
-### 后端 (Node.js + Express)
-- **Express 服务器** - 具有静态文件服务的 RESTful API
-- **WebSocket 服务器** - 用于聊天和项目刷新的通信
-- **Agent 集成 (Claude Code / Cursor CLI / Codex)** - 进程生成和管理
-- **文件系统 API** - 为项目公开文件浏览器
+<details>
+<summary>能在手机上使用 CloudCLI UI 吗？</summary>
 
-### 前端 (React + Vite)
-- **React 18** - 带有 hooks 的现代组件架构
-- **CodeMirror** - 具有语法高亮的高级代码编辑器
+可以。自托管时，在你的设备上运行服务器，然后在网络中的任意浏览器打开 `[yourip]:port`。CloudCLI Cloud 可从任意设备访问，内置原生应用也在开发中。
 
+</details>
 
+<details>
+<summary>UI 中的更改会影响本地 Claude Code 配置吗？</summary>
 
+会的。自托管模式下，CloudCLI UI 读取并写入 Claude Code 使用的 `~/.claude` 配置。通过 UI 添加的 MCP 服务器会立即在 Claude Code 中可见。
 
-### 贡献
+</details>
 
-我们欢迎贡献！有关提交规范、开发流程和发布流程的详细信息,请参阅 [Contributing Guide](CONTRIBUTING.md)。
+---
 
-## 故障排除
-
-### 常见问题与解决方案
-
-
-#### "未找到 Claude 项目"
-**问题**: UI 显示没有项目或项目列表为空
-**解决方案**:
-- 确保已正确安装 [Claude Code](https://docs.anthropic.com/en/docs/claude-code)
-- 至少在一个项目目录中运行 `claude` 命令以进行初始化
-- 验证 `~/.claude/projects/` 目录存在并具有适当的权限
-
-#### 文件浏览器问题
-**问题**: 文件无法加载、权限错误、空目录
-**解决方案**:
-- 检查项目目录权限(在终端中使用 `ls -la`)
-- 验证项目路径存在且可访问
-- 查看服务器控制台日志以获取详细错误消息
-- 确保您未尝试访问项目范围之外的系统目录
+## 社区与支持
 
+- **[文档](https://cloudcli.ai/docs)** — 安装、配置、功能与故障排除指南
+- **[Discord](https://discord.gg/buxwujPNRE)** — 获取帮助并与社区交流
+- **[GitHub Issues](https://github.com/siteboon/claudecodeui/issues)** — 报告 Bug 与建议功能
+- **[贡献指南](CONTRIBUTING.md)** — 如何参与项目贡献
 
 ## 许可证
 
-GNU General Public License v3.0 - 详见 [LICENSE](LICENSE) 文件。
+GNU 通用公共许可证 v3.0 - 详见 [LICENSE](LICENSE) 文件。
 
-本项目是开源的,在 GPL v3 许可下可自由使用、修改和分发。
+该项目为开源软件，在 GPL v3 许可证下可自由使用、修改与分发。
 
 ## 致谢
 
-### 构建工具
-- **[Claude Code](https://docs.anthropic.com/en/docs/claude-code)** - Anthropic 的官方 CLI
-- **[Cursor CLI](https://docs.cursor.com/en/cli/overview)** - Cursor 的官方 CLI
+### 使用技术
+- **[Claude Code](https://docs.anthropic.com/en/docs/claude-code)** - Anthropic 官方 CLI
+- **[Cursor CLI](https://docs.cursor.com/en/cli/overview)** - Cursor 官方 CLI
 - **[Codex](https://developers.openai.com/codex)** - OpenAI Codex
+- **[Gemini-CLI](https://geminicli.com/)** - Google Gemini CLI
 - **[React](https://react.dev/)** - 用户界面库
-- **[Vite](https://vitejs.dev/)** - 快速构建工具和开发服务器
-- **[Tailwind CSS](https://tailwindcss.com/)** - 实用优先的 CSS 框架
+- **[Vite](https://vitejs.dev/)** - 快速构建工具与开发服务器
+- **[Tailwind CSS](https://tailwindcss.com/)** - 实用先行 CSS 框架
 - **[CodeMirror](https://codemirror.net/)** - 高级代码编辑器
-- **[TaskMaster AI](https://github.com/eyaltoledano/claude-task-master)** *(可选)* - AI 驱动的项目管理和任务规划
-
-## 支持与社区
-
-### 保持更新
-- **Star** 此仓库以表示支持
-- **Watch** 以获取更新和新版本
-- **Follow** 项目以获取公告
+- **[TaskMaster AI](https://github.com/eyaltoledano/claude-task-master)** *(可选)* - AI 驱动的项目管理与任务规划
 
 ### 赞助商
 - [Siteboon - AI powered website builder](https://siteboon.ai)

docker/README.md

@@ -0,0 +1,160 @@
+<!-- Docker Hub short description (100 chars max): -->
+<!-- Sandbox templates for running AI coding agents with a web & mobile IDE (Claude Code, Codex, Gemini) -->
+
+# Sandboxed coding agents with a web & mobile IDE (CloudCLI)
+
+[Docker Sandbox](https://docs.docker.com/ai/sandboxes/) templates that add [CloudCLI](https://cloudcli.ai) on top of Claude Code, Codex, and Gemini CLI. You get a full web and mobile IDE accessible from any browser on any device.
+
+## Get started
+
+### 1. Install the sbx CLI
+
+Docker Sandboxes run agents in isolated microVMs. Install the `sbx` CLI:
+
+- **macOS**: `brew install docker/tap/sbx`
+- **Windows**: `winget install -h Docker.sbx`
+- **Linux**: `sudo apt-get install docker-sbx`
+
+Full instructions: [docs.docker.com/ai/sandboxes/get-started](https://docs.docker.com/ai/sandboxes/get-started/)
+
+### 2. Store your API key
+
+`sbx` manages credentials securely — your API key never enters the sandbox. Store it once:
+
+```bash
+sbx login
+sbx secret set -g anthropic
+```
+
+### 3. Launch Claude Code
+
+```bash
+npx @cloudcli-ai/cloudcli@latest sandbox ~/my-project
+```
+
+Open **http://localhost:3001**. Set a password on first visit. Start building.
+
+### Using a different agent
+
+Store the matching API key and pass `--agent`:
+
+```bash
+# OpenAI Codex
+sbx secret set -g openai
+npx @cloudcli-ai/cloudcli@latest sandbox ~/my-project --agent codex
+
+# Gemini CLI
+sbx secret set -g google
+npx @cloudcli-ai/cloudcli@latest sandbox ~/my-project --agent gemini
+```
+
+### Available templates
+
+| Agent | Template |
+|-------|----------|
+| **Claude Code** (default) | `docker.io/cloudcliai/sandbox:claude-code` |
+| OpenAI Codex | `docker.io/cloudcliai/sandbox:codex` |
+| Gemini CLI | `docker.io/cloudcliai/sandbox:gemini` |
+
+These are used with `--template` when running `sbx` directly (see [Advanced usage](#advanced-usage)).
+
+## Managing sandboxes
+
+```bash
+sbx ls                               # List all sandboxes
+sbx stop my-project                  # Stop (preserves state)
+sbx start my-project                 # Restart a stopped sandbox
+sbx rm my-project                    # Remove everything
+sbx exec my-project bash             # Open a shell inside the sandbox
+```
+
+If you install CloudCLI globally (`npm install -g @cloudcli-ai/cloudcli`), you can also use:
+
+```bash
+cloudcli sandbox ls
+cloudcli sandbox start my-project    # Restart and re-launch web UI
+cloudcli sandbox logs my-project     # View server logs
+```
+
+## What you get
+
+- **Chat** — Markdown rendering, code blocks, message history
+- **Files** — File tree with syntax-highlighted editor
+- **Git** — Diff viewer, staging, branch switching, commits
+- **Shell** — Built-in terminal emulator
+- **MCP** — Configure Model Context Protocol servers visually
+- **Mobile** — Works on tablet and phone browsers
+
+Your project directory is mounted bidirectionally — edits propagate in real time, both ways.
+
+## Configuration
+
+Set variables at creation time with `--env`:
+
+```bash
+npx @cloudcli-ai/cloudcli@latest sandbox ~/my-project --env SERVER_PORT=8080
+```
+
+Or inside a running sandbox:
+
+```bash
+sbx exec my-project bash -c 'echo "export SERVER_PORT=8080" >> /etc/sandbox-persistent.sh'
+```
+
+Restart CloudCLI for changes to take effect:
+
+```bash
+sbx exec my-project bash -c 'pkill -f "server/index.js"'
+sbx exec -d my-project cloudcli start --port 3001
+```
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `SERVER_PORT` | `3001` | Web UI port |
+| `HOST` | `0.0.0.0` | Bind address (must be `0.0.0.0` for `sbx ports`) |
+| `DATABASE_PATH` | `~/.cloudcli/auth.db` | SQLite database location |
+
+## Advanced usage
+
+For branch mode, multiple workspaces, memory limits, or the terminal agent experience, use `sbx` with the template:
+
+```bash
+# Terminal agent + web UI
+sbx run --template docker.io/cloudcliai/sandbox:claude-code claude ~/my-project --name my-project
+sbx ports my-project --publish 3001:3001
+
+# Branch mode (Git worktree isolation)
+sbx run --template docker.io/cloudcliai/sandbox:claude-code claude ~/my-project --branch my-feature
+
+# Multiple workspaces
+sbx run --template docker.io/cloudcliai/sandbox:claude-code claude ~/project ~/shared-libs:ro
+
+# Pass a prompt directly
+sbx run --template docker.io/cloudcliai/sandbox:claude-code claude ~/my-project -- "Fix the auth bug"
+```
+
+CloudCLI auto-starts via `.bashrc` when using `sbx run`.
+
+Full options in the [Docker Sandboxes usage guide](https://docs.docker.com/ai/sandboxes/usage/).
+
+## Network policies
+
+Sandboxes restrict outbound access by default. To reach host services from inside the sandbox:
+
+```bash
+sbx policy allow network localhost:11434
+# Inside the sandbox: curl http://host.docker.internal:11434
+```
+
+The web UI itself doesn't need a policy — access it via `sbx ports`.
+
+## Links
+
+- [CloudCLI Cloud](https://cloudcli.ai) — fully managed, no setup required
+- [Documentation](https://cloudcli.ai/docs) — full configuration guide
+- [Discord](https://discord.gg/buxwujPNRE) — community support
+- [GitHub](https://github.com/siteboon/claudecodeui) — source code and issues
+
+## License
+
+AGPL-3.0-or-later

docker/claude-code/Dockerfile

@@ -0,0 +1,11 @@
+FROM docker/sandbox-templates:claude-code
+
+USER root
+COPY shared/install-cloudcli.sh /tmp/install-cloudcli.sh
+RUN chmod +x /tmp/install-cloudcli.sh && /tmp/install-cloudcli.sh
+
+USER agent
+RUN npm install -g @cloudcli-ai/cloudcli && cloudcli --version
+
+COPY --chown=agent:agent shared/start-cloudcli.sh /home/agent/.cloudcli-start.sh
+RUN echo '. ~/.cloudcli-start.sh' >> /home/agent/.bashrc

docker/codex/Dockerfile

@@ -0,0 +1,11 @@
+FROM docker/sandbox-templates:codex
+
+USER root
+COPY shared/install-cloudcli.sh /tmp/install-cloudcli.sh
+RUN chmod +x /tmp/install-cloudcli.sh && /tmp/install-cloudcli.sh
+
+USER agent
+RUN npm install -g @cloudcli-ai/cloudcli && cloudcli --version
+
+COPY --chown=agent:agent shared/start-cloudcli.sh /home/agent/.cloudcli-start.sh
+RUN echo '. ~/.cloudcli-start.sh' >> /home/agent/.bashrc

docker/gemini/Dockerfile

@@ -0,0 +1,11 @@
+FROM docker/sandbox-templates:gemini
+
+USER root
+COPY shared/install-cloudcli.sh /tmp/install-cloudcli.sh
+RUN chmod +x /tmp/install-cloudcli.sh && /tmp/install-cloudcli.sh
+
+USER agent
+RUN npm install -g @cloudcli-ai/cloudcli && cloudcli --version
+
+COPY --chown=agent:agent shared/start-cloudcli.sh /home/agent/.cloudcli-start.sh
+RUN echo '. ~/.cloudcli-start.sh' >> /home/agent/.bashrc

docker/shared/install-cloudcli.sh

@@ -0,0 +1,11 @@
+#!/bin/bash
+set -e
+
+# Install build tools needed for native modules (node-pty, better-sqlite3, bcrypt)
+# Node.js is already provided by the sandbox base image
+apt-get update && apt-get install -y --no-install-recommends \
+  build-essential python3 python3-setuptools \
+  jq ripgrep sqlite3 zip unzip tree vim-tiny
+
+# Clean up apt cache to reduce image size
+rm -rf /var/lib/apt/lists/*

docker/shared/start-cloudcli.sh

@@ -0,0 +1,18 @@
+#!/bin/bash
+
+# Auto-start CloudCLI server in background if not already running.
+# This script is sourced from ~/.bashrc on sandbox shell open.
+
+if ! pgrep -f "server/index.js" > /dev/null 2>&1; then
+  nohup cloudcli start --port 3001 > /tmp/cloudcli-ui.log 2>&1 &
+  disown
+
+  echo ""
+  echo "  CloudCLI is starting on port 3001..."
+  echo ""
+  echo "  Forward the port from another terminal:"
+  echo "    sbx ports <sandbox-name> --publish 3001:3001"
+  echo ""
+  echo "  Then open: http://localhost:3001"
+  echo ""
+fi

eslint.config.js

@@ -3,7 +3,9 @@ import tseslint from "typescript-eslint";
 import react from "eslint-plugin-react";
 import reactHooks from "eslint-plugin-react-hooks";
 import reactRefresh from "eslint-plugin-react-refresh";
-import importX from "eslint-plugin-import-x";
+import { createNodeResolver, importX } from "eslint-plugin-import-x";
+import { createTypeScriptImportResolver } from "eslint-import-resolver-typescript";
+import boundaries from "eslint-plugin-boundaries";
 import tailwindcss from "eslint-plugin-tailwindcss";
 import unusedImports from "eslint-plugin-unused-imports";
 import globals from "globals";
@@ -82,7 +84,7 @@ export default tseslint.config(
             "sibling",
             "index",
           ],
-          "newlines-between": "never",
+          "newlines-between": "always",
         },
       ],
 
@@ -98,5 +100,149 @@ export default tseslint.config(
       "no-control-regex": "off",
       "no-useless-escape": "off",
     },
+  },
+  {
+    files: ["server/**/*.{js,ts}"], // apply this block only to backend source files
+    ignores: ["server/**/*.d.ts"], // skip generated declaration files in backend linting
+    plugins: {
+      boundaries, // enforce backend architecture boundaries (module-to-module contracts)
+      "import-x": importX, // keep import hygiene rules (duplicates, unresolved paths, etc.)
+      "unused-imports": unusedImports, // remove dead imports/variables from backend files
+    },
+    languageOptions: {
+      parser: tseslint.parser, // parse both JS and TS syntax in backend files
+      parserOptions: {
+        ecmaVersion: "latest", // support modern ECMAScript syntax in backend code
+        sourceType: "module", // treat backend files as ESM modules
+      },
+      globals: {
+        ...globals.node, // expose Node.js globals such as process, Buffer, and __dirname equivalents
+      },
+    },
+    settings: {
+      "boundaries/include": ["server/**/*.{js,ts}"], // only analyze dependency boundaries inside backend files
+      "import/resolver": {
+        // boundaries resolves imports through eslint-module-utils, which reads the classic
+        // import/resolver setting instead of import-x/resolver-next.
+        typescript: {
+          project: ["server/tsconfig.json"], // resolve backend aliases using the canonical backend tsconfig
+          alwaysTryTypes: true, // keep normal TS package/type resolution working alongside aliases
+        },
+        node: {
+          extensions: [".mjs", ".cjs", ".js", ".json", ".node", ".ts", ".tsx"], // preserve Node-style fallback resolution for plain files
+        },
+      },
+      "import-x/resolver-next": [
+        // ESLint's import plugin does not read tsconfig path aliases on its own.
+        // This resolver teaches import-x how to understand the backend-only "@/*"
+        // mapping defined in server/tsconfig.json, which fixes false no-unresolved errors in editors.
+        createTypeScriptImportResolver({
+          project: ["server/tsconfig.json"], // point the resolver at the canonical backend tsconfig instead of the frontend one
+          alwaysTryTypes: true, // keep standard TypeScript package resolution working while backend aliases are enabled
+        }),
+        // Keep Node-style resolution available for normal package imports and plain relative JS files.
+        // The TypeScript resolver handles aliases, while the Node resolver preserves the expected fallback behavior.
+        createNodeResolver({
+          extensions: [".mjs", ".cjs", ".js", ".json", ".node", ".ts", ".tsx"],
+        }),
+      ],
+      "boundaries/elements": [
+        {
+          type: "backend-shared-type-contract", // shared backend type/interface contracts that modules may consume without creating runtime coupling
+          pattern: [
+            "server/shared/types.{js,ts}",
+            "server/shared/interfaces.{js,ts}",
+          ], // keep backend modules on explicit shared contract files for erased imports only
+          mode: "file", // treat each shared contract file itself as the boundary element instead of the whole folder
+        },
+        {
+          type: "backend-shared-utils", // shared backend runtime helpers that modules may import directly
+          pattern: ["server/shared/utils.{js,ts}"], // classify the shared utils file so modules can depend on it explicitly
+          mode: "file",
+        },
+        {
+          type: "backend-legacy-runtime", // legacy runtime persistence modules used while providers migrate into server/modules
+          pattern: [
+            "server/projects.js",
+            "server/sessionManager.js",
+            "server/database/*.{js,ts}",
+            "server/utils/runtime-paths.js",
+          ], // provider history loading still resolves session data through these legacy runtime/database files
+          mode: "file",
+        },
+        {
+          type: "backend-module", // logical element name used by boundaries rules below
+          pattern: "server/modules/*", // each direct folder in server/modules is treated as one module boundary
+          mode: "folder", // classify dependencies at folder-module level (not per individual file)
+          capture: ["moduleName"], // capture the module folder name for messages/debugging/template use
+        },
+      ],
+    },
+    rules: {
+      // --- Unused imports/vars (backend) ---
+      "unused-imports/no-unused-imports": "warn", // warn when imports are not used so they can be cleaned up
+      "unused-imports/no-unused-vars": "off", // keep backend signal focused on dead imports instead of local unused variables
+
+      // --- Import hygiene (backend) ---
+      "import-x/no-duplicates": "warn", // prevent duplicate import lines from the same module
+      "import-x/order": [
+        "warn", // keep backend import grouping/order consistent with the frontend config
+        {
+          groups: [
+            "builtin", // Node built-ins such as fs, path, and url come first
+            "external", // third-party packages come after built-ins
+            "internal", // aliased internal imports such as @/... come next
+            "parent", // ../ imports come after aliased internal imports
+            "sibling", // ./foo imports come after parent imports
+            "index", // bare ./ imports stay last
+          ],
+          "newlines-between": "always", // require a blank line between import groups in backend files too
+        },
+      ],
+      "import-x/no-unresolved": "error", // fail when an import path cannot be resolved
+      "import-x/no-useless-path-segments": "warn", // prefer cleaner paths (remove redundant ./ and ../ segments)
+      "import-x/no-absolute-path": "error", // disallow absolute filesystem imports in backend files
+
+      // --- General safety/style (backend) ---
+      eqeqeq: ["warn", "always", { null: "ignore" }], // avoid accidental coercion while still allowing x == null checks
+
+      // --- Architecture boundaries (backend modules) ---
+      "boundaries/dependencies": [
+        "error", // treat architecture violations as lint errors
+        {
+          default: "allow", // allow normal imports unless a rule below explicitly disallows them
+          checkInternals: false, // do not apply these cross-module rules to imports inside the same module
+          rules: [
+            {
+              from: { type: "backend-module" }, // modules may depend on shared type/interface contracts only as erased type-only imports
+              to: { type: "backend-shared-type-contract" },
+              disallow: {
+                dependency: { kind: ["value", "typeof"] },
+              }, // block runtime imports so shared contracts stay compile-time only instead of becoming hidden shared modules
+              message:
+                "Backend modules may only use `import type` when importing from server/shared/types.ts or server/shared/interfaces.ts.",
+            },
+            {
+              to: { type: "backend-module" }, // when importing anything that belongs to another backend module
+              disallow: { to: { internalPath: "**" } }, // block all direct/deep imports into module internals by default
+              message:
+                "Cross-module imports must go through that module's barrel file (server/modules/<module>/index.ts or index.js).", // explicit error message for architecture violations
+            },
+            {
+              to: { type: "backend-module" }, // same target scope as the disallow rule above
+              allow: {
+                to: {
+                  internalPath: [
+                    "index", // allow extensionless barrel imports resolved as module root index
+                    "index.{js,mjs,cjs,ts,tsx}", // allow explicit index.* barrel file imports
+                  ],
+                },
+              }, // re-allow only public module entry points (barrel files)
+            },
+          ],
+        },
+      ],
+      "boundaries/no-unknown": "error", // fail fast if boundaries cannot classify a dependency, which prevents silent rule bypasses
+    },
   }
 );

package.json

@@ -1,17 +1,17 @@
 {
-  "name": "@siteboon/claude-code-ui",
-  "version": "1.25.2",
+  "name": "@cloudcli-ai/cloudcli",
+  "version": "1.29.2",
   "description": "A web-based UI for Claude Code CLI",
   "type": "module",
-  "main": "server/index.js",
+  "main": "dist-server/server/index.js",
   "bin": {
-    "claude-code-ui": "server/cli.js",
-    "cloudcli": "server/cli.js"
+    "cloudcli": "dist-server/server/cli.js"
   },
   "files": [
     "server/",
     "shared/",
     "dist/",
+    "dist-server/",
     "scripts/",
     "README.md"
   ],
@@ -24,29 +24,46 @@
     "url": "https://github.com/siteboon/claudecodeui/issues"
   },
   "scripts": {
-    "dev": "concurrently --kill-others \"npm run server\" \"npm run client\"",
-    "server": "node server/index.js",
-    "client": "vite --host",
-    "build": "vite build",
+    "dev": "concurrently --kill-others \"npm run server:dev\" \"npm run client\"",
+    "server": "node dist-server/server/index.js",
+    "server:dev": "tsx --tsconfig server/tsconfig.json server/index.js",
+    "server:dev-watch": "tsx watch --tsconfig server/tsconfig.json server/index.js",
+    "client": "vite",
+    "build": "npm run build:client && npm run build:server",
+    "build:client": "vite build",
+    "prebuild:server": "node -e \"require('node:fs').rmSync('dist-server', { recursive: true, force: true })\"",
+    "build:server": "tsc -p server/tsconfig.json && tsc-alias -p server/tsconfig.json",
     "preview": "vite preview",
-    "typecheck": "tsc --noEmit -p tsconfig.json",
-    "lint": "eslint src/",
-    "lint:fix": "eslint src/ --fix",
+    "typecheck": "tsc --noEmit -p tsconfig.json && tsc --noEmit -p server/tsconfig.json",
+    "lint": "eslint src/ server/",
+    "lint:fix": "eslint src/ server/ --fix",
     "start": "npm run build && npm run server",
     "release": "./release.sh",
     "prepublishOnly": "npm run build",
     "postinstall": "node scripts/fix-node-pty.js",
-    "prepare": "husky"
+    "prepare": "husky",
+    "update:platform": "./update-platform.sh"
   },
   "keywords": [
     "claude code",
-    "ai",
+    "claude-code",
+    "claude-code-ui",
+    "cloudcli",
+    "codex",
+    "gemini",
+    "gemini-cli",
+    "cursor",
+    "cursor-cli",
     "anthropic",
+    "openai",
+    "google",
+    "coding-agent",
+    "web-ui",
     "ui",
-    "mobile"
+    "mobile IDE"
   ],
   "author": "CloudCLI UI Contributors",
-  "license": "GPL-3.0",
+  "license": "AGPL-3.0-or-later",
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.2.59",
     "@codemirror/lang-css": "^6.3.1",
@@ -103,6 +120,7 @@
     "sqlite": "^5.1.1",
     "sqlite3": "^5.1.7",
     "tailwind-merge": "^3.3.1",
+    "web-push": "^3.6.7",
     "ws": "^8.14.2"
   },
   "devDependencies": {
@@ -110,6 +128,8 @@
     "@commitlint/config-conventional": "^20.4.3",
     "@eslint/js": "^9.39.3",
     "@release-it/conventional-changelog": "^10.0.5",
+    "@types/cross-spawn": "^6.0.6",
+    "@types/express": "^5.0.6",
     "@types/node": "^22.19.7",
     "@types/react": "^18.2.43",
     "@types/react-dom": "^18.2.17",
@@ -118,6 +138,8 @@
     "autoprefixer": "^10.4.16",
     "concurrently": "^8.2.2",
     "eslint": "^9.39.3",
+    "eslint-import-resolver-typescript": "^4.4.4",
+    "eslint-plugin-boundaries": "^6.0.2",
     "eslint-plugin-import-x": "^4.16.1",
     "eslint-plugin-react": "^7.37.5",
     "eslint-plugin-react-hooks": "^7.0.1",
@@ -132,11 +154,14 @@
     "release-it": "^19.0.5",
     "sharp": "^0.34.2",
     "tailwindcss": "^3.4.0",
+    "tsc-alias": "^1.8.16",
+    "tsx": "^4.21.0",
     "typescript": "^5.9.3",
     "typescript-eslint": "^8.56.1",
     "vite": "^7.0.4"
   },
   "lint-staged": {
-    "src/**/*.{ts,tsx,js,jsx}": "eslint"
+    "src/**/*.{ts,tsx,js,jsx}": "eslint",
+    "server/**/*.{js,ts}": "eslint"
   }
 }

public/api-docs.html

@@ -3,7 +3,7 @@
 <head>
     <meta charset="UTF-8">
     <meta name="viewport" content="width=device-width, initial-scale=1.0">
-    <title>Claude Code UI - API Documentation</title>
+    <title>CloudCLI - API Documentation</title>
     <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
     <link rel="icon" type="image/png" href="/favicon.png" />
     
@@ -418,7 +418,7 @@
                     </svg>
                 </div>
                 <div class="brand-text">
-                    <h1>Claude Code UI</h1>
+                    <h1>CloudCLI</h1>
                     <div class="subtitle">API Documentation</div>
                 </div>
             </div>

public/sw.js

@@ -1,8 +1,8 @@
-// Service Worker for Claude Code UI PWA
-const CACHE_NAME = 'claude-ui-v1';
+// Service Worker for CloudCLI PWA
+// Cache only manifest (needed for PWA install). HTML and JS are never pre-cached
+// so a rebuild + refresh always picks up the latest assets.
+const CACHE_NAME = 'claude-ui-v2';
 const urlsToCache = [
-  '/',
-  '/index.html',
   '/manifest.json'
 ];
 
@@ -10,40 +10,115 @@ const urlsToCache = [
 self.addEventListener('install', event => {
   event.waitUntil(
     caches.open(CACHE_NAME)
-      .then(cache => {
-        return cache.addAll(urlsToCache);
-      })
+      .then(cache => cache.addAll(urlsToCache))
   );
   self.skipWaiting();
 });
 
-// Fetch event
+// Fetch event — network-first for everything except hashed assets
 self.addEventListener('fetch', event => {
-  event.respondWith(
-    caches.match(event.request)
-      .then(response => {
-        // Return cached response if found
-        if (response) {
+  const url = event.request.url;
+
+  // Never intercept API requests or WebSocket upgrades
+  if (url.includes('/api/') || url.includes('/ws')) {
+    return;
+  }
+
+  // Navigation requests (HTML) — always go to network, no caching
+  if (event.request.mode === 'navigate') {
+    event.respondWith(
+      fetch(event.request).catch(() => caches.match('/manifest.json').then(() =>
+        new Response('<h1>Offline</h1><p>Please check your connection.</p>', {
+          headers: { 'Content-Type': 'text/html' }
+        })
+      ))
+    );
+    return;
+  }
+
+  // Hashed assets (JS/CSS in /assets/) — cache-first since filenames change per build
+  if (url.includes('/assets/')) {
+    event.respondWith(
+      caches.match(event.request).then(cached => {
+        if (cached) return cached;
+        return fetch(event.request).then(response => {
+          const clone = response.clone();
+          caches.open(CACHE_NAME).then(cache => cache.put(event.request, clone));
           return response;
-        }
-        // Otherwise fetch from network
-        return fetch(event.request);
-      }
-    )
+        });
+      })
+    );
+    return;
+  }
+
+  // Everything else — network-first
+  event.respondWith(
+    fetch(event.request).catch(() => caches.match(event.request))
   );
 });
 
-// Activate event
+// Activate event — purge old caches
 self.addEventListener('activate', event => {
   event.waitUntil(
-    caches.keys().then(cacheNames => {
-      return Promise.all(
-        cacheNames.map(cacheName => {
-          if (cacheName !== CACHE_NAME) {
-            return caches.delete(cacheName);
-          }
-        })
-      );
+    caches.keys().then(cacheNames =>
+      Promise.all(
+        cacheNames
+          .filter(name => name !== CACHE_NAME)
+          .map(name => caches.delete(name))
+      )
+    )
+  );
+  self.clients.claim();
+});
+
+// Push notification event
+self.addEventListener('push', event => {
+  if (!event.data) return;
+
+  let payload;
+  try {
+    payload = event.data.json();
+  } catch {
+    payload = { title: 'CloudCLI', body: event.data.text() };
+  }
+
+  const options = {
+    body: payload.body || '',
+    icon: '/logo-256.png',
+    badge: '/logo-128.png',
+    data: payload.data || {},
+    tag: payload.data?.tag || `${payload.data?.sessionId || 'global'}:${payload.data?.code || 'default'}`,
+    renotify: true
+  };
+
+  event.waitUntil(
+    self.registration.showNotification(payload.title || 'CloudCLI', options)
+  );
+});
+
+// Notification click event
+self.addEventListener('notificationclick', event => {
+  event.notification.close();
+
+  const sessionId = event.notification.data?.sessionId;
+  const provider = event.notification.data?.provider || null;
+  const urlPath = sessionId ? `/session/${sessionId}` : '/';
+
+  event.waitUntil(
+    self.clients.matchAll({ type: 'window', includeUncontrolled: true }).then(async clientList => {
+      for (const client of clientList) {
+        if (client.url.includes(self.location.origin)) {
+          await client.focus();
+          client.postMessage({
+            type: 'notification:navigate',
+            sessionId: sessionId || null,
+            provider,
+            urlPath
+          });
+          return;
+        }
+      }
+      return self.clients.openWindow(urlPath);
     })
   );
-});
+});

redirect-package/README.md

@@ -0,0 +1,248 @@
+<div align="center">
+
+> ## This package has moved to [`@cloudcli-ai/cloudcli`](https://www.npmjs.com/package/@cloudcli-ai/cloudcli)
+>
+> ```bash
+> npm install -g @cloudcli-ai/cloudcli
+> ```
+>
+> This package (`@siteboon/claude-code-ui`) is now a thin wrapper that installs the new package automatically.
+> For new installations, use `@cloudcli-ai/cloudcli` directly.
+
+</div>
+
+---
+
+<div align="center">
+  <img src="https://raw.githubusercontent.com/siteboon/claudecodeui/main/public/logo.svg" alt="CloudCLI UI" width="64" height="64">
+  <h1>Cloud CLI (aka Claude Code UI)</h1>
+  <p>A desktop and mobile UI for <a href="https://docs.anthropic.com/en/docs/claude-code">Claude Code</a>, <a href="https://docs.cursor.com/en/cli/overview">Cursor CLI</a>, <a href="https://developers.openai.com/codex">Codex</a>, and <a href="https://geminicli.com/">Gemini-CLI</a>.<br>Use it locally or remotely to view your active projects and sessions from everywhere.</p>
+</div>
+
+<p align="center">
+  <a href="https://cloudcli.ai">CloudCLI Cloud</a> · <a href="https://cloudcli.ai/docs">Documentation</a> · <a href="https://discord.gg/buxwujPNRE">Discord</a> · <a href="https://github.com/siteboon/claudecodeui/issues">Bug Reports</a> · <a href="https://github.com/siteboon/claudecodeui/blob/main/CONTRIBUTING.md">Contributing</a>
+</p>
+
+<p align="center">
+  <a href="https://cloudcli.ai"><img src="https://img.shields.io/badge/☁️_CloudCLI_Cloud-Try_Now-0066FF?style=for-the-badge" alt="CloudCLI Cloud"></a>
+  <a href="https://discord.gg/buxwujPNRE"><img src="https://img.shields.io/badge/Discord-Join%20Community-5865F2?style=for-the-badge&logo=discord&logoColor=white" alt="Join our Discord"></a>
+  <br><br>
+  <a href="https://trendshift.io/repositories/15586" target="_blank"><img src="https://trendshift.io/api/badge/repositories/15586" alt="siteboon%2Fclaudecodeui | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/></a>
+</p>
+
+---
+
+## Screenshots
+
+<div align="center">
+
+<table>
+<tr>
+<td align="center">
+<h3>Desktop View</h3>
+<img src="https://raw.githubusercontent.com/siteboon/claudecodeui/main/public/screenshots/desktop-main.png" alt="Desktop Interface" width="400">
+<br>
+<em>Main interface showing project overview and chat</em>
+</td>
+<td align="center">
+<h3>Mobile Experience</h3>
+<img src="https://raw.githubusercontent.com/siteboon/claudecodeui/main/public/screenshots/mobile-chat.png" alt="Mobile Interface" width="250">
+<br>
+<em>Responsive mobile design with touch navigation</em>
+</td>
+</tr>
+<tr>
+<td align="center" colspan="2">
+<h3>CLI Selection</h3>
+<img src="https://raw.githubusercontent.com/siteboon/claudecodeui/main/public/screenshots/cli-selection.png" alt="CLI Selection" width="400">
+<br>
+<em>Select between Claude Code, Gemini, Cursor CLI and Codex</em>
+</td>
+</tr>
+</table>
+
+
+
+</div>
+
+## Features
+
+- **Responsive Design** - Works seamlessly across desktop, tablet, and mobile so you can also use Agents from mobile
+- **Interactive Chat Interface** - Built-in chat interface for seamless communication with the Agents
+- **Integrated Shell Terminal** - Direct access to the Agents CLI through built-in shell functionality
+- **File Explorer** - Interactive file tree with syntax highlighting and live editing
+- **Git Explorer** - View, stage and commit your changes. You can also switch branches
+- **Session Management** - Resume conversations, manage multiple sessions, and track history
+- **Plugin System** - Extend CloudCLI with custom plugins — add new tabs, backend services, and integrations. [Build your own →](https://github.com/cloudcli-ai/cloudcli-plugin-starter)
+- **TaskMaster AI Integration** *(Optional)* - Advanced project management with AI-powered task planning, PRD parsing, and workflow automation
+- **Model Compatibility** - Works with Claude, GPT, and Gemini model families (see [`shared/modelConstants.js`](https://github.com/siteboon/claudecodeui/blob/main/shared/modelConstants.js) for the full list of supported models)
+
+
+## Quick Start
+
+### CloudCLI Cloud (Recommended)
+
+The fastest way to get started — no local setup required. Get a fully managed, containerized development environment accessible from the web, mobile app, API, or your favorite IDE.
+
+**[Get started with CloudCLI Cloud](https://cloudcli.ai)**
+
+
+### Self-Hosted (Open source)
+
+Try CloudCLI UI instantly with **npx** (requires **Node.js** v22+):
+
+```
+npx @cloudcli-ai/cloudcli
+```
+
+Or install **globally** for regular use:
+
+```
+npm install -g @cloudcli-ai/cloudcli
+cloudcli
+```
+
+Open `http://localhost:3001` — all your existing sessions are discovered automatically.
+
+Visit the **[documentation →](https://cloudcli.ai/docs)** for more full configuration options, PM2, remote server setup and more
+
+
+---
+
+## Which option is right for you?
+
+CloudCLI UI is the open source UI layer that powers CloudCLI Cloud. You can self-host it on your own machine, or use CloudCLI Cloud which builds on top of it with a full managed cloud environment, team features, and deeper integrations.
+
+| | CloudCLI UI (Self-hosted) | CloudCLI Cloud |
+|---|---|---|
+| **Best for** | Developers who want a full UI for local agent sessions on their own machine | Teams and developers who want agents running in the cloud, accessible from anywhere |
+| **How you access it** | Browser via `[yourip]:port` | Browser, any IDE, REST API, n8n |
+| **Setup** | `npx @cloudcli-ai/cloudcli` | No setup required |
+| **Machine needs to stay on** | Yes | No |
+| **Mobile access** | Any browser on your network | Any device, native app coming |
+| **Sessions available** | All sessions auto-discovered from `~/.claude` | All sessions within your cloud environment |
+| **Agents supported** | Claude Code, Cursor CLI, Codex, Gemini CLI | Claude Code, Cursor CLI, Codex, Gemini CLI |
+| **File explorer and Git** | Yes, built into the UI | Yes, built into the UI |
+| **MCP configuration** | Managed via UI, synced with your local `~/.claude` config | Managed via UI |
+| **IDE access** | Your local IDE | Any IDE connected to your cloud environment |
+| **REST API** | Yes | Yes |
+| **n8n node** | No | Yes |
+| **Team sharing** | No | Yes |
+| **Platform cost** | Free, open source | Starts at $7/month |
+
+> Both options use your own AI subscriptions (Claude, Cursor, etc.) — CloudCLI provides the environment, not the AI.
+
+---
+
+## Security & Tools Configuration
+
+**Important Notice**: All Claude Code tools are **disabled by default**. This prevents potentially harmful operations from running automatically.
+
+### Enabling Tools
+
+To use Claude Code's full functionality, you'll need to manually enable tools:
+
+1. **Open Tools Settings** - Click the gear icon in the sidebar
+2. **Enable Selectively** - Turn on only the tools you need
+3. **Apply Settings** - Your preferences are saved locally
+
+**Recommended approach**: Start with basic tools enabled and add more as needed. You can always adjust these settings later.
+
+---
+
+## Plugins
+
+CloudCLI has a plugin system that lets you add custom tabs with their own frontend UI and optional Node.js backend. Install plugins from git repos directly in **Settings > Plugins**, or build your own.
+
+### Available Plugins
+
+| Plugin | Description |
+|---|---|
+| **[Project Stats](https://github.com/cloudcli-ai/cloudcli-plugin-starter)** | Shows file counts, lines of code, file-type breakdown, largest files, and recently modified files for your current project |
+| **[Web Terminal](https://github.com/cloudcli-ai/cloudcli-plugin-terminal)** | Full xterm.js terminal with multi-tab support|
+
+### Build Your Own
+
+**[Plugin Starter Template →](https://github.com/cloudcli-ai/cloudcli-plugin-starter)** — fork this repo to create your own plugin. It includes a working example with frontend rendering, live context updates, and RPC communication to a backend server.
+
+**[Plugin Documentation →](https://cloudcli.ai/docs/plugin-overview)** — full guide to the plugin API, manifest format, security model, and more.
+
+---
+## FAQ
+
+<details>
+<summary>How is this different from Claude Code Remote Control?</summary>
+
+Claude Code Remote Control lets you send messages to a session already running in your local terminal. Your machine has to stay on, your terminal has to stay open, and sessions time out after roughly 10 minutes without a network connection.
+
+CloudCLI UI and CloudCLI Cloud extend Claude Code rather than sit alongside it — your MCP servers, permissions, settings, and sessions are the exact same ones Claude Code uses natively. Nothing is duplicated or managed separately.
+
+Here's what that means in practice:
+
+- **All your sessions, not just one** — CloudCLI UI auto-discovers every session from your `~/.claude` folder. Remote Control only exposes the single active session to make it available in the Claude mobile app.
+- **Your settings are your settings** — MCP servers, tool permissions, and project config you change in CloudCLI UI are written directly to your Claude Code config and take effect immediately, and vice versa.
+- **Works with more agents** — Claude Code, Cursor CLI, Codex, and Gemini CLI, not just Claude Code.
+- **Full UI, not just a chat window** — file explorer, Git integration, MCP management, and a shell terminal are all built in.
+- **CloudCLI Cloud runs in the cloud** — close your laptop, the agent keeps running. No terminal to babysit, no machine to keep awake.
+
+</details>
+
+<details>
+<summary>Do I need to pay for an AI subscription separately?</summary>
+
+Yes. CloudCLI provides the environment, not the AI. You bring your own Claude, Cursor, Codex, or Gemini subscription. CloudCLI Cloud starts at $7/month for the hosted environment on top of that.
+
+</details>
+
+<details>
+<summary>Can I use CloudCLI UI on my phone?</summary>
+
+Yes. For self-hosted, run the server on your machine and open `[yourip]:port` in any browser on your network. For CloudCLI Cloud, open it from any device — no VPN, no port forwarding, no setup. A native app is also in the works.
+
+</details>
+
+<details>
+<summary>Will changes I make in the UI affect my local Claude Code setup?</summary>
+
+Yes, for self-hosted. CloudCLI UI reads from and writes to the same `~/.claude` config that Claude Code uses natively. MCP servers you add via the UI show up in Claude Code immediately and vice versa.
+
+</details>
+
+---
+
+## Community & Support
+
+- **[Documentation](https://cloudcli.ai/docs)** — installation, configuration, features, and troubleshooting
+- **[Discord](https://discord.gg/buxwujPNRE)** — get help and connect with other users
+- **[GitHub Issues](https://github.com/siteboon/claudecodeui/issues)** — bug reports and feature requests
+- **[Contributing Guide](https://github.com/siteboon/claudecodeui/blob/main/CONTRIBUTING.md)** — how to contribute to the project
+
+## License
+
+GNU Affero General Public License v3.0 or later (AGPL-3.0-or-later) — see [LICENSE](https://github.com/siteboon/claudecodeui/blob/main/LICENSE) for the full text, including additional terms under Section 7.
+
+This project is open source and free to use, modify, and distribute under the AGPL-3.0-or-later license. If you modify this software and run it as a network service, you must make your modified source code available to users of that service.
+
+CloudCLI UI  - (https://cloudcli.ai).
+
+## Acknowledgments
+
+### Built With
+- **[Claude Code](https://docs.anthropic.com/en/docs/claude-code)** - Anthropic's official CLI
+- **[Cursor CLI](https://docs.cursor.com/en/cli/overview)** - Cursor's official CLI
+- **[Codex](https://developers.openai.com/codex)** - OpenAI Codex
+- **[Gemini-CLI](https://geminicli.com/)** - Google Gemini CLI
+- **[React](https://react.dev/)** - User interface library
+- **[Vite](https://vitejs.dev/)** - Fast build tool and dev server
+- **[Tailwind CSS](https://tailwindcss.com/)** - Utility-first CSS framework
+- **[CodeMirror](https://codemirror.net/)** - Advanced code editor
+- **[TaskMaster AI](https://github.com/eyaltoledano/claude-task-master)** *(Optional)* - AI-powered project management and task planning
+
+
+### Sponsors
+- [Siteboon - AI powered website builder](https://siteboon.ai)
+---
+
+<div align="center">
+  <strong>Made with care for the Claude Code, Cursor and Codex community.</strong>
+</div>

redirect-package/bin.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import('@cloudcli-ai/cloudcli/dist-server/server/cli.js');

redirect-package/index.js

@@ -0,0 +1,2 @@
+export * from '@cloudcli-ai/cloudcli';
+export { default } from '@cloudcli-ai/cloudcli';

redirect-package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@siteboon/claude-code-ui",
+  "version": "2.0.0",
+  "description": "This package has moved to @cloudcli-ai/cloudcli",
+  "type": "module",
+  "main": "index.js",
+  "bin": {
+    "claude-code-ui": "./bin.js",
+    "cloudcli": "./bin.js"
+  },
+  "homepage": "https://cloudcli.ai",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/siteboon/claudecodeui.git"
+  },
+  "bugs": {
+    "url": "https://github.com/siteboon/claudecodeui/issues"
+  },
+  "keywords": [
+    "claude code",
+    "claude-code",
+    "claude-code-ui",
+    "cloudcli",
+    "codex",
+    "gemini",
+    "gemini-cli",
+    "cursor",
+    "cursor-cli",
+    "anthropic",
+    "openai",
+    "google",
+    "coding-agent",
+    "web-ui",
+    "ui",
+    "mobile IDE"
+  ],
+  "author": "CloudCLI UI Contributors",
+  "dependencies": {
+    "@cloudcli-ai/cloudcli": "*"
+  },
+  "deprecated": "This package has been renamed to @cloudcli-ai/cloudcli. Please install @cloudcli-ai/cloudcli instead.",
+  "license": "AGPL-3.0-or-later"
+}

server/claude-sdk.js

@@ -18,6 +18,14 @@ import { promises as fs } from 'fs';
 import path from 'path';
 import os from 'os';
 import { CLAUDE_MODELS } from '../shared/modelConstants.js';
+import {
+  createNotificationEvent,
+  notifyRunFailed,
+  notifyRunStopped,
+  notifyUserIfEnabled
+} from './services/notification-orchestrator.js';
+import { sessionsService } from './modules/providers/services/sessions.service.js';
+import { createNormalizedMessage } from './shared/utils.js';
 
 const activeSessions = new Map();
 const pendingToolApprovals = new Map();
@@ -136,7 +144,7 @@ function matchesToolPermission(entry, toolName, input) {
  * @returns {Object} SDK-compatible options
  */
 function mapCliOptionsToSDK(options = {}) {
-  const { sessionId, cwd, toolsSettings, permissionMode, images } = options;
+  const { sessionId, cwd, toolsSettings, permissionMode } = options;
 
   const sdkOptions = {};
 
@@ -187,7 +195,7 @@ function mapCliOptionsToSDK(options = {}) {
   // Map model (default to sonnet)
   // Valid models: sonnet, opus, haiku, opusplan, sonnet[1m]
   sdkOptions.model = options.model || CLAUDE_MODELS.DEFAULT;
-  console.log(`Using model: ${sdkOptions.model}`);
+  // Model logged at query start below
 
   // Map system prompt configuration
   sdkOptions.systemPrompt = {
@@ -298,7 +306,7 @@ function extractTokenBudget(resultMessage) {
   // This is the user's budget limit, not the model's context window
   const contextWindow = parseInt(process.env.CONTEXT_WINDOW) || 160000;
 
-  console.log(`Token calculation: input=${inputTokens}, output=${outputTokens}, cache=${cacheReadTokens + cacheCreationTokens}, total=${totalUsed}/${contextWindow}`);
+  // Token calc logged via token-budget WS event
 
   return {
     used: totalUsed,
@@ -354,7 +362,7 @@ async function handleImages(command, images, cwd) {
       modifiedCommand = command + imageNote;
     }
 
-    console.log(`Processed ${tempImagePaths.length} images to temp directory: ${tempDir}`);
+    // Images processed
     return { modifiedCommand, tempImagePaths, tempDir };
   } catch (error) {
     console.error('Error processing images for SDK:', error);
@@ -387,7 +395,7 @@ async function cleanupTempFiles(tempImagePaths, tempDir) {
       );
     }
 
-    console.log(`Cleaned up ${tempImagePaths.length} temp image files`);
+    // Temp files cleaned
   } catch (error) {
     console.error('Error during temp file cleanup:', error);
   }
@@ -407,7 +415,7 @@ async function loadMcpConfig(cwd) {
       await fs.access(claudeConfigPath);
     } catch (error) {
       // File doesn't exist, return null
-      console.log('No ~/.claude.json found, proceeding without MCP servers');
+      // No config file
       return null;
     }
 
@@ -427,7 +435,7 @@ async function loadMcpConfig(cwd) {
     // Add global MCP servers
     if (claudeConfig.mcpServers && typeof claudeConfig.mcpServers === 'object') {
       mcpServers = { ...claudeConfig.mcpServers };
-      console.log(`Loaded ${Object.keys(mcpServers).length} global MCP servers`);
+      // Global MCP servers loaded
     }
 
     // Add/override with project-specific MCP servers
@@ -435,17 +443,14 @@ async function loadMcpConfig(cwd) {
       const projectConfig = claudeConfig.claudeProjects[cwd];
       if (projectConfig && projectConfig.mcpServers && typeof projectConfig.mcpServers === 'object') {
         mcpServers = { ...mcpServers, ...projectConfig.mcpServers };
-        console.log(`Loaded ${Object.keys(projectConfig.mcpServers).length} project-specific MCP servers`);
+        // Project MCP servers merged
       }
     }
 
     // Return null if no servers found
     if (Object.keys(mcpServers).length === 0) {
-      console.log('No MCP servers configured');
       return null;
     }
-
-    console.log(`Total MCP servers loaded: ${Object.keys(mcpServers).length}`);
     return mcpServers;
   } catch (error) {
     console.error('Error loading MCP config:', error.message);
@@ -461,12 +466,20 @@ async function loadMcpConfig(cwd) {
  * @returns {Promise<void>}
  */
 async function queryClaudeSDK(command, options = {}, ws) {
-  const { sessionId } = options;
+  const { sessionId, sessionSummary } = options;
   let capturedSessionId = sessionId;
   let sessionCreatedSent = false;
   let tempImagePaths = [];
   let tempDir = null;
 
+  const emitNotification = (event) => {
+    notifyUserIfEnabled({
+      userId: ws?.userId || null,
+      writer: ws,
+      event
+    });
+  };
+
   try {
     // Map CLI options to SDK format
     const sdkOptions = mapCliOptionsToSDK(options);
@@ -483,6 +496,26 @@ async function queryClaudeSDK(command, options = {}, ws) {
     tempImagePaths = imageResult.tempImagePaths;
     tempDir = imageResult.tempDir;
 
+    sdkOptions.hooks = {
+      Notification: [{
+        matcher: '',
+        hooks: [async (input) => {
+          const message = typeof input?.message === 'string' ? input.message : 'Claude requires your attention.';
+          emitNotification(createNotificationEvent({
+            provider: 'claude',
+            sessionId: capturedSessionId || sessionId || null,
+            kind: 'action_required',
+            code: 'agent.notification',
+            meta: { message, sessionName: sessionSummary },
+            severity: 'warning',
+            requiresUserAction: true,
+            dedupeKey: `claude:hook:notification:${capturedSessionId || sessionId || 'none'}:${message}`
+          }));
+          return {};
+        }]
+      }]
+    };
+
     sdkOptions.canUseTool = async (toolName, input, context) => {
       const requiresInteraction = TOOLS_REQUIRING_INTERACTION.has(toolName);
 
@@ -507,13 +540,17 @@ async function queryClaudeSDK(command, options = {}, ws) {
       }
 
       const requestId = createRequestId();
-      ws.send({
-        type: 'claude-permission-request',
-        requestId,
-        toolName,
-        input,
-        sessionId: capturedSessionId || sessionId || null
-      });
+      ws.send(createNormalizedMessage({ kind: 'permission_request', requestId, toolName, input, sessionId: capturedSessionId || sessionId || null, provider: 'claude' }));
+      emitNotification(createNotificationEvent({
+        provider: 'claude',
+        sessionId: capturedSessionId || sessionId || null,
+        kind: 'action_required',
+        code: 'permission.required',
+        meta: { toolName, sessionName: sessionSummary },
+        severity: 'warning',
+        requiresUserAction: true,
+        dedupeKey: `claude:permission:${capturedSessionId || sessionId || 'none'}:${requestId}`
+      }));
 
       const decision = await waitForToolApproval(requestId, {
         timeoutMs: requiresInteraction ? 0 : undefined,
@@ -525,12 +562,7 @@ async function queryClaudeSDK(command, options = {}, ws) {
           _receivedAt: new Date(),
         },
         onCancel: (reason) => {
-          ws.send({
-            type: 'claude-permission-cancelled',
-            requestId,
-            reason,
-            sessionId: capturedSessionId || sessionId || null
-          });
+          ws.send(createNormalizedMessage({ kind: 'permission_cancelled', requestId, reason, sessionId: capturedSessionId || sessionId || null, provider: 'claude' }));
         }
       });
       if (!decision) {
@@ -560,10 +592,22 @@ async function queryClaudeSDK(command, options = {}, ws) {
     const prevStreamTimeout = process.env.CLAUDE_CODE_STREAM_CLOSE_TIMEOUT;
     process.env.CLAUDE_CODE_STREAM_CLOSE_TIMEOUT = '300000';
 
-    const queryInstance = query({
-      prompt: finalCommand,
-      options: sdkOptions
-    });
+    let queryInstance;
+    try {
+      queryInstance = query({
+        prompt: finalCommand,
+        options: sdkOptions
+      });
+    } catch (hookError) {
+      // Older/newer SDK versions may not accept hook shapes yet.
+      // Keep notification behavior operational via runtime events even if hook registration fails.
+      console.warn('Failed to initialize Claude query with hooks, retrying without hooks:', hookError?.message || hookError);
+      delete sdkOptions.hooks;
+      queryInstance = query({
+        prompt: finalCommand,
+        options: sdkOptions
+      });
+    }
 
     // Restore immediately — Query constructor already captured the value
     if (prevStreamTimeout !== undefined) {
@@ -594,39 +638,35 @@ async function queryClaudeSDK(command, options = {}, ws) {
         // Send session-created event only once for new sessions
         if (!sessionId && !sessionCreatedSent) {
           sessionCreatedSent = true;
-          ws.send({
-            type: 'session-created',
-            sessionId: capturedSessionId
-          });
-        } else {
-          console.log('Not sending session-created. sessionId:', sessionId, 'sessionCreatedSent:', sessionCreatedSent);
+          ws.send(createNormalizedMessage({ kind: 'session_created', newSessionId: capturedSessionId, sessionId: capturedSessionId, provider: 'claude' }));
         }
       } else {
-        console.log('No session_id in message or already captured. message.session_id:', message.session_id, 'capturedSessionId:', capturedSessionId);
+        // session_id already captured
       }
 
-      // Transform and send message to WebSocket
+      // Transform and normalize message via adapter
       const transformedMessage = transformMessage(message);
-      ws.send({
-        type: 'claude-response',
-        data: transformedMessage,
-        sessionId: capturedSessionId || sessionId || null
-      });
+      const sid = capturedSessionId || sessionId || null;
+
+      // Use adapter to normalize SDK events into NormalizedMessage[]
+      const normalized = sessionsService.normalizeMessage('claude', transformedMessage, sid);
+      for (const msg of normalized) {
+        // Preserve parentToolUseId from SDK wrapper for subagent tool grouping
+        if (transformedMessage.parentToolUseId && !msg.parentToolUseId) {
+          msg.parentToolUseId = transformedMessage.parentToolUseId;
+        }
+        ws.send(msg);
+      }
 
       // Extract and send token budget updates from result messages
       if (message.type === 'result') {
         const models = Object.keys(message.modelUsage || {});
         if (models.length > 0) {
-          console.log("---> Model was sent using:", models);
+          // Model info available in result message
         }
-        const tokenBudget = extractTokenBudget(message);
-        if (tokenBudget) {
-          console.log('Token budget from modelUsage:', tokenBudget);
-          ws.send({
-            type: 'token-budget',
-            data: tokenBudget,
-            sessionId: capturedSessionId || sessionId || null
-          });
+        const tokenBudgetData = extractTokenBudget(message);
+        if (tokenBudgetData) {
+          ws.send(createNormalizedMessage({ kind: 'status', text: 'token_budget', tokenBudget: tokenBudgetData, sessionId: capturedSessionId || sessionId || null, provider: 'claude' }));
         }
       }
     }
@@ -640,14 +680,15 @@ async function queryClaudeSDK(command, options = {}, ws) {
     await cleanupTempFiles(tempImagePaths, tempDir);
 
     // Send completion event
-    console.log('Streaming complete, sending claude-complete event');
-    ws.send({
-      type: 'claude-complete',
-      sessionId: capturedSessionId,
-      exitCode: 0,
-      isNewSession: !sessionId && !!command
+    ws.send(createNormalizedMessage({ kind: 'complete', exitCode: 0, isNewSession: !sessionId && !!command, sessionId: capturedSessionId, provider: 'claude' }));
+    notifyRunStopped({
+      userId: ws?.userId || null,
+      provider: 'claude',
+      sessionId: capturedSessionId || sessionId || null,
+      sessionName: sessionSummary,
+      stopReason: 'completed'
     });
-    console.log('claude-complete event sent');
+    // Complete
 
   } catch (error) {
     console.error('SDK query error:', error);
@@ -661,10 +702,13 @@ async function queryClaudeSDK(command, options = {}, ws) {
     await cleanupTempFiles(tempImagePaths, tempDir);
 
     // Send error to WebSocket
-    ws.send({
-      type: 'claude-error',
-      error: error.message,
-      sessionId: capturedSessionId || sessionId || null
+    ws.send(createNormalizedMessage({ kind: 'error', content: error.message, sessionId: capturedSessionId || sessionId || null, provider: 'claude' }));
+    notifyRunFailed({
+      userId: ws?.userId || null,
+      provider: 'claude',
+      sessionId: capturedSessionId || sessionId || null,
+      sessionName: sessionSummary,
+      error
     });
 
     throw error;

server/cli.js

@@ -1,12 +1,13 @@
 #!/usr/bin/env node
 /**
- * Claude Code UI CLI
+ * CloudCLI CLI
  *
- * Provides command-line utilities for managing Claude Code UI
+ * Provides command-line utilities for managing CloudCLI
  *
  * Commands:
  *   (no args)     - Start the server (default)
  *   start         - Start the server
+ *   sandbox       - Manage Docker sandbox environments
  *   status        - Show configuration and data locations
  *   help          - Show help information
  *   version       - Show version information
@@ -15,11 +16,12 @@
 import fs from 'fs';
 import path from 'path';
 import os from 'os';
-import { fileURLToPath } from 'url';
-import { dirname } from 'path';
+import { findAppRoot, getModuleDir } from './utils/runtime-paths.js';
 
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
+const __dirname = getModuleDir(import.meta.url);
+// The CLI is compiled into dist-server/server, but it still needs to read the top-level
+// package.json and .env file. Resolving the app root once keeps those lookups stable.
+const APP_ROOT = findAppRoot(__dirname);
 
 // ANSI color codes for terminal output
 const colors = {
@@ -49,13 +51,16 @@ const c = {
 };
 
 // Load package.json for version info
-const packageJsonPath = path.join(__dirname, '../package.json');
+const packageJsonPath = path.join(APP_ROOT, 'package.json');
 const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
+// Match the runtime fallback in load-env.js so "cloudcli status" reports the same default
+// database location that the backend will actually use when no DATABASE_PATH is configured.
+const DEFAULT_DATABASE_PATH = path.join(os.homedir(), '.cloudcli', 'auth.db');
 
 // Load environment variables from .env file if it exists
 function loadEnvFile() {
     try {
-        const envPath = path.join(__dirname, '../.env');
+        const envPath = path.join(APP_ROOT, '.env');
         const envFile = fs.readFileSync(envPath, 'utf8');
         envFile.split('\n').forEach(line => {
             const trimmedLine = line.trim();
@@ -74,17 +79,17 @@ function loadEnvFile() {
 // Get the database path (same logic as db.js)
 function getDatabasePath() {
     loadEnvFile();
-    return process.env.DATABASE_PATH || path.join(__dirname, 'database', 'auth.db');
+    return process.env.DATABASE_PATH || DEFAULT_DATABASE_PATH;
 }
 
 // Get the installation directory
 function getInstallDir() {
-    return path.join(__dirname, '..');
+    return APP_ROOT;
 }
 
 // Show status command
 function showStatus() {
-    console.log(`\n${c.bright('Claude Code UI - Status')}\n`);
+    console.log(`\n${c.bright('CloudCLI UI - Status')}\n`);
     console.log(c.dim('═'.repeat(60)));
 
     // Version info
@@ -110,7 +115,7 @@ function showStatus() {
 
     // Environment variables
     console.log(`\n${c.info('[INFO]')} Configuration:`);
-    console.log(`       PORT: ${c.bright(process.env.PORT || '3001')} ${c.dim(process.env.PORT ? '' : '(default)')}`);
+    console.log(`       SERVER_PORT: ${c.bright(process.env.SERVER_PORT || process.env.PORT || '3001')} ${c.dim(process.env.SERVER_PORT || process.env.PORT ? '' : '(default)')}`);
     console.log(`       DATABASE_PATH: ${c.dim(process.env.DATABASE_PATH || '(using default location)')}`);
     console.log(`       CLAUDE_CLI_PATH: ${c.dim(process.env.CLAUDE_CLI_PATH || 'claude (default)')}`);
     console.log(`       CONTEXT_WINDOW: ${c.dim(process.env.CONTEXT_WINDOW || '160000 (default)')}`);
@@ -123,7 +128,7 @@ function showStatus() {
     console.log(`       Status: ${projectsExists ? c.ok('[OK] Exists') : c.warn('[WARN] Not found')}`);
 
     // Config file location
-    const envFilePath = path.join(__dirname, '../.env');
+    const envFilePath = path.join(APP_ROOT, '.env');
     const envExists = fs.existsSync(envFilePath);
     console.log(`\n${c.info('[INFO]')} Configuration File:`);
     console.log(`       ${c.dim(envFilePath)}`);
@@ -134,14 +139,14 @@ function showStatus() {
     console.log(`      ${c.dim('>')} Use ${c.bright('cloudcli --port 8080')} to run on a custom port`);
     console.log(`      ${c.dim('>')} Use ${c.bright('cloudcli --database-path /path/to/db')} for custom database`);
     console.log(`      ${c.dim('>')} Run ${c.bright('cloudcli help')} for all options`);
-    console.log(`      ${c.dim('>')} Access the UI at http://localhost:${process.env.PORT || '3001'}\n`);
+    console.log(`      ${c.dim('>')} Access the UI at http://localhost:${process.env.SERVER_PORT || process.env.PORT || '3001'}\n`);
 }
 
 // Show help
 function showHelp() {
     console.log(`
 ╔═══════════════════════════════════════════════════════════════╗
-║              Claude Code UI - Command Line Tool               ║
+║              CloudCLI - Command Line Tool               ║
 ╚═══════════════════════════════════════════════════════════════╝
 
 Usage:
@@ -149,7 +154,8 @@ Usage:
   cloudcli [command] [options]
 
 Commands:
-  start          Start the Claude Code UI server (default)
+  start          Start the CloudCLI server (default)
+  sandbox        Manage Docker sandbox environments
   status         Show configuration and data locations
   update         Update to the latest version
   help           Show this help information
@@ -164,12 +170,12 @@ Options:
 Examples:
   $ cloudcli                        # Start with defaults
   $ cloudcli --port 8080            # Start on port 8080
-  $ cloudcli -p 3000                # Short form for port
-  $ cloudcli start --port 4000      # Explicit start command
+  $ cloudcli sandbox ~/my-project   # Run in a Docker sandbox
   $ cloudcli status                 # Show configuration
 
 Environment Variables:
-  PORT                Set server port (default: 3001)
+  SERVER_PORT         Set server port (default: 3001)
+  PORT                Set server port (default: 3001) (LEGACY)
   DATABASE_PATH       Set custom database location
   CLAUDE_CLI_PATH     Set custom Claude CLI path
   CONTEXT_WINDOW      Set context window size (default: 160000)
@@ -202,7 +208,7 @@ function isNewerVersion(v1, v2) {
 async function checkForUpdates(silent = false) {
     try {
         const { execSync } = await import('child_process');
-        const latestVersion = execSync('npm show @siteboon/claude-code-ui version', { encoding: 'utf8' }).trim();
+        const latestVersion = execSync('npm show @cloudcli-ai/cloudcli version', { encoding: 'utf8' }).trim();
         const currentVersion = packageJson.version;
 
         if (isNewerVersion(latestVersion, currentVersion)) {
@@ -235,14 +241,361 @@ async function updatePackage() {
         }
 
         console.log(`${c.info('[INFO]')} Updating from ${currentVersion} to ${latestVersion}...`);
-        execSync('npm update -g @siteboon/claude-code-ui', { stdio: 'inherit' });
+        execSync('npm update -g @cloudcli-ai/cloudcli', { stdio: 'inherit' });
         console.log(`${c.ok('[OK]')} Update complete! Restart cloudcli to use the new version.`);
     } catch (e) {
         console.error(`${c.error('[ERROR]')} Update failed: ${e.message}`);
-        console.log(`${c.tip('[TIP]')} Try running manually: npm update -g @siteboon/claude-code-ui`);
+        console.log(`${c.tip('[TIP]')} Try running manually: npm update -g @cloudcli-ai/cloudcli`);
     }
 }
 
+// ── Sandbox command ─────────────────────────────────────────
+
+const SANDBOX_TEMPLATES = {
+    claude: 'docker.io/cloudcliai/sandbox:claude-code',
+    codex: 'docker.io/cloudcliai/sandbox:codex',
+    gemini: 'docker.io/cloudcliai/sandbox:gemini',
+};
+
+const SANDBOX_SECRETS = {
+    claude: 'anthropic',
+    codex: 'openai',
+    gemini: 'google',
+};
+
+function parseSandboxArgs(args) {
+    const result = {
+        subcommand: null,
+        workspace: null,
+        agent: 'claude',
+        name: null,
+        port: 3001,
+        template: null,
+        env: [],
+    };
+
+    const subcommands = ['ls', 'stop', 'start', 'rm', 'logs', 'help'];
+
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+
+        if (i === 0 && subcommands.includes(arg)) {
+            result.subcommand = arg;
+        } else if (arg === '--agent' || arg === '-a') {
+            result.agent = args[++i];
+        } else if (arg === '--name' || arg === '-n') {
+            result.name = args[++i];
+        } else if (arg === '--port') {
+            result.port = parseInt(args[++i], 10);
+        } else if (arg === '--template' || arg === '-t') {
+            result.template = args[++i];
+        } else if (arg === '--env' || arg === '-e') {
+            result.env.push(args[++i]);
+        } else if (!arg.startsWith('-')) {
+            if (!result.subcommand) {
+                result.workspace = arg;
+            } else {
+                result.name = arg; // for stop/start/rm/logs <name>
+            }
+        }
+    }
+
+    // Default subcommand based on what we got
+    if (!result.subcommand) {
+        result.subcommand = 'create';
+    }
+
+    // Derive name from workspace path if not set
+    if (!result.name && result.workspace) {
+        result.name = path.basename(path.resolve(result.workspace.replace(/^~/, os.homedir())));
+    }
+
+    // Default template from agent
+    if (!result.template) {
+        result.template = SANDBOX_TEMPLATES[result.agent] || SANDBOX_TEMPLATES.claude;
+    }
+
+    return result;
+}
+
+function showSandboxHelp() {
+    console.log(`
+${c.bright('CloudCLI Sandbox')} — Run CloudCLI inside Docker Sandboxes
+
+Usage:
+  cloudcli sandbox <workspace>            Create and start a sandbox
+  cloudcli sandbox <subcommand> [name]    Manage sandboxes
+
+Subcommands:
+  ${c.bright('(default)')}    Create a sandbox and start the web UI
+  ${c.bright('ls')}           List all sandboxes
+  ${c.bright('start')}        Restart a stopped sandbox and re-launch the web UI
+  ${c.bright('stop')}         Stop a sandbox (preserves state)
+  ${c.bright('rm')}           Remove a sandbox
+  ${c.bright('logs')}         Show CloudCLI server logs
+  ${c.bright('help')}         Show this help
+
+Options:
+  -a, --agent <agent>       Agent to use: claude, codex, gemini (default: claude)
+  -n, --name <name>         Sandbox name (default: derived from workspace folder)
+  -t, --template <image>    Custom template image
+  -e, --env <KEY=VALUE>     Set environment variable (repeatable)
+      --port <port>         Host port for the web UI (default: 3001)
+
+Examples:
+  $ cloudcli sandbox ~/my-project
+  $ cloudcli sandbox ~/my-project --agent codex --port 8080
+  $ cloudcli sandbox ~/my-project --env SERVER_PORT=8080 --env HOST=0.0.0.0
+  $ cloudcli sandbox ls
+  $ cloudcli sandbox stop my-project
+  $ cloudcli sandbox start my-project
+  $ cloudcli sandbox rm my-project
+
+Prerequisites:
+  1. Install sbx CLI: https://docs.docker.com/ai/sandboxes/get-started/
+  2. Authenticate and store your API key:
+       sbx login
+       sbx secret set -g anthropic   # for Claude
+       sbx secret set -g openai      # for Codex
+       sbx secret set -g google      # for Gemini
+
+Advanced usage:
+  For branch mode, multiple workspaces, memory limits, network policies,
+  or passing prompts to the agent, use sbx directly with the template:
+
+    sbx run --template docker.io/cloudcliai/sandbox:claude-code claude ~/my-project --branch my-feature
+    sbx run --template docker.io/cloudcliai/sandbox:claude-code claude ~/project ~/libs:ro --memory 8g
+
+  Full Docker Sandboxes docs: https://docs.docker.com/ai/sandboxes/usage/
+`);
+}
+
+async function sandboxCommand(args) {
+    const { execFileSync, spawn: spawnProcess } = await import('child_process');
+
+    // Safe execution — uses execFileSync (no shell) to prevent injection
+    const sbx = (subcmd, opts = {}) => {
+        const result = execFileSync('sbx', subcmd, {
+            encoding: 'utf8',
+            stdio: opts.inherit ? 'inherit' : 'pipe',
+        });
+        return result || '';
+    };
+
+    const opts = parseSandboxArgs(args);
+
+    if (opts.subcommand === 'help') {
+        showSandboxHelp();
+        return;
+    }
+
+    // Validate name (alphanumeric, hyphens, underscores only)
+    if (opts.name && !/^[\w-]+$/.test(opts.name)) {
+        console.error(`\n${c.error('❌')} Invalid sandbox name: ${opts.name}`);
+        console.log(`   Names may only contain letters, numbers, hyphens, and underscores.\n`);
+        process.exit(1);
+    }
+
+    // Check sbx is installed
+    try {
+        sbx(['version']);
+    } catch {
+        console.error(`\n${c.error('❌')} ${c.bright('sbx')} CLI not found.\n`);
+        console.log(`   Install it from: ${c.info('https://docs.docker.com/ai/sandboxes/get-started/')}`);
+        console.log(`   Then run: ${c.bright('sbx login')}`);
+        console.log(`   And store your API key: ${c.bright('sbx secret set -g anthropic')}\n`);
+        process.exit(1);
+    }
+
+    switch (opts.subcommand) {
+
+        case 'ls':
+            sbx(['ls'], { inherit: true });
+            break;
+
+        case 'stop':
+            if (!opts.name) {
+                console.error(`\n${c.error('❌')} Sandbox name required: cloudcli sandbox stop <name>\n`);
+                process.exit(1);
+            }
+            sbx(['stop', opts.name], { inherit: true });
+            break;
+
+        case 'rm':
+            if (!opts.name) {
+                console.error(`\n${c.error('❌')} Sandbox name required: cloudcli sandbox rm <name>\n`);
+                process.exit(1);
+            }
+            sbx(['rm', opts.name], { inherit: true });
+            break;
+
+        case 'logs':
+            if (!opts.name) {
+                console.error(`\n${c.error('❌')} Sandbox name required: cloudcli sandbox logs <name>\n`);
+                process.exit(1);
+            }
+            try {
+                sbx(['exec', opts.name, 'bash', '-c', 'cat /tmp/cloudcli-ui.log'], { inherit: true });
+            } catch (e) {
+                console.error(`\n${c.error('❌')} Could not read logs: ${e.message || 'Is the sandbox running?'}\n`);
+            }
+            break;
+
+        case 'start': {
+            if (!opts.name) {
+                console.error(`\n${c.error('❌')} Sandbox name required: cloudcli sandbox start <name>\n`);
+                process.exit(1);
+            }
+            console.log(`\n${c.info('▶')} Starting sandbox ${c.bright(opts.name)}...`);
+            const restartRun = spawnProcess('sbx', ['run', opts.name], {
+                detached: true,
+                stdio: ['ignore', 'ignore', 'ignore'],
+            });
+            restartRun.unref();
+            await new Promise(resolve => setTimeout(resolve, 5000));
+
+            console.log(`${c.info('▶')} Launching CloudCLI web server...`);
+            sbx(['exec', opts.name, 'bash', '-c', 'cloudcli start --port 3001 &']);
+
+            console.log(`${c.info('▶')} Forwarding port ${opts.port} → 3001...`);
+            try {
+                sbx(['ports', opts.name, '--publish', `${opts.port}:3001`]);
+            } catch (e) {
+                const msg = e.stdout || e.stderr || e.message || '';
+                if (msg.includes('address already in use')) {
+                    const altPort = opts.port + 1;
+                    console.log(`${c.warn('⚠')}  Port ${opts.port} in use, trying ${altPort}...`);
+                    try {
+                        sbx(['ports', opts.name, '--publish', `${altPort}:3001`]);
+                        opts.port = altPort;
+                    } catch {
+                        console.error(`${c.error('❌')} Ports ${opts.port} and ${altPort} both in use. Use --port to specify a free port.`);
+                        process.exit(1);
+                    }
+                } else {
+                    throw e;
+                }
+            }
+
+            console.log(`\n${c.ok('✔')} ${c.bright('CloudCLI is ready!')}`);
+            console.log(`  ${c.info('→')} ${c.bright(`http://localhost:${opts.port}`)}\n`);
+            break;
+        }
+
+        case 'create': {
+            if (!opts.workspace) {
+                console.error(`\n${c.error('❌')} Workspace path required: cloudcli sandbox <path>\n`);
+                console.log(`   Example: ${c.bright('cloudcli sandbox ~/my-project')}\n`);
+                process.exit(1);
+            }
+
+            const workspace = opts.workspace.startsWith('~')
+                ? opts.workspace.replace(/^~/, os.homedir())
+                : path.resolve(opts.workspace);
+
+            if (!fs.existsSync(workspace)) {
+                console.error(`\n${c.error('❌')} Workspace path not found: ${c.dim(workspace)}\n`);
+                process.exit(1);
+            }
+
+            const secret = SANDBOX_SECRETS[opts.agent] || 'anthropic';
+
+            // Check if the required secret is stored
+            try {
+                const secretList = sbx(['secret', 'ls']);
+                if (!secretList.includes(secret)) {
+                    console.error(`\n${c.error('❌')} No ${c.bright(secret)} API key found.\n`);
+                    console.log(`   Run: ${c.bright(`sbx secret set -g ${secret}`)}\n`);
+                    process.exit(1);
+                }
+            } catch { /* sbx secret ls not available, skip check */ }
+
+            console.log(`\n${c.bright('CloudCLI Sandbox')}`);
+            console.log(c.dim('─'.repeat(50)));
+            console.log(`  Agent:     ${c.info(opts.agent)} ${c.dim(`(${secret} credentials)`)}`);
+            console.log(`  Workspace: ${c.dim(workspace)}`);
+            console.log(`  Name:      ${c.dim(opts.name)}`);
+            console.log(`  Template:  ${c.dim(opts.template)}`);
+            console.log(`  Port:      ${c.dim(String(opts.port))}`);
+            if (opts.env.length > 0) {
+                console.log(`  Env:       ${c.dim(opts.env.join(', '))}`);
+            }
+            console.log(c.dim('─'.repeat(50)));
+
+            // Step 1: Launch sandbox with sbx run in background.
+            // sbx run creates the sandbox (or reconnects) AND holds an active session,
+            // which prevents the sandbox from auto-stopping.
+            console.log(`\n${c.info('▶')} Creating sandbox ${c.bright(opts.name)}...`);
+            const bgRun = spawnProcess('sbx', [
+                'run', '--template', opts.template, '--name', opts.name, opts.agent, workspace,
+            ], {
+                detached: true,
+                stdio: ['ignore', 'ignore', 'ignore'],
+            });
+            bgRun.unref();
+            // Wait for sandbox to be ready
+            await new Promise(resolve => setTimeout(resolve, 5000));
+
+            // Step 2: Inject environment variables
+            if (opts.env.length > 0) {
+                console.log(`${c.info('▶')} Setting environment variables...`);
+                const exports = opts.env
+                    .filter(e => /^\w+=.+$/.test(e))
+                    .map(e => `export ${e}`)
+                    .join('\n');
+                if (exports) {
+                    sbx(['exec', opts.name, 'bash', '-c', `echo '${exports}' >> /etc/sandbox-persistent.sh`]);
+                }
+                const invalid = opts.env.filter(e => !/^\w+=.+$/.test(e));
+                if (invalid.length > 0) {
+                    console.log(`${c.warn('⚠')}  Skipped invalid env vars: ${invalid.join(', ')} (expected KEY=VALUE)`);
+                }
+            }
+
+            // Step 3: Start CloudCLI inside the sandbox
+            console.log(`${c.info('▶')} Launching CloudCLI web server...`);
+            sbx(['exec', opts.name, 'bash', '-c', 'cloudcli start --port 3001 &']);
+
+            // Step 4: Forward port
+            console.log(`${c.info('▶')} Forwarding port ${opts.port} → 3001...`);
+            try {
+                sbx(['ports', opts.name, '--publish', `${opts.port}:3001`]);
+            } catch (e) {
+                const msg = e.stdout || e.stderr || e.message || '';
+                if (msg.includes('address already in use')) {
+                    const altPort = opts.port + 1;
+                    console.log(`${c.warn('⚠')}  Port ${opts.port} in use, trying ${altPort}...`);
+                    try {
+                        sbx(['ports', opts.name, '--publish', `${altPort}:3001`]);
+                        opts.port = altPort;
+                    } catch {
+                        console.error(`${c.error('❌')} Ports ${opts.port} and ${altPort} both in use. Use --port to specify a free port.`);
+                        process.exit(1);
+                    }
+                } else {
+                    throw e;
+                }
+            }
+
+            // Done
+            console.log(`\n${c.ok('✔')} ${c.bright('CloudCLI is ready!')}`);
+            console.log(`  ${c.info('→')} Open ${c.bright(`http://localhost:${opts.port}`)}`);
+            console.log(`\n${c.dim('  Manage with:')}`);
+            console.log(`  ${c.dim('$')} sbx ls`);
+            console.log(`  ${c.dim('$')} sbx stop ${opts.name}`);
+            console.log(`  ${c.dim('$')} sbx start ${opts.name}`);
+            console.log(`  ${c.dim('$')} sbx rm ${opts.name}`);
+            console.log(`\n${c.dim('  Or install globally:')} npm install -g @cloudcli-ai/cloudcli\n`);
+            break;
+        }
+
+        default:
+            showSandboxHelp();
+    }
+}
+
+// ── Server ──────────────────────────────────────────────────
+
 // Start the server
 async function startServer() {
     // Check for updates silently on startup
@@ -260,9 +613,9 @@ function parseArgs(args) {
         const arg = args[i];
 
         if (arg === '--port' || arg === '-p') {
-            parsed.options.port = args[++i];
+            parsed.options.serverPort = args[++i];
         } else if (arg.startsWith('--port=')) {
-            parsed.options.port = arg.split('=')[1];
+            parsed.options.serverPort = arg.split('=')[1];
         } else if (arg === '--database-path') {
             parsed.options.databasePath = args[++i];
         } else if (arg.startsWith('--database-path=')) {
@@ -273,6 +626,10 @@ function parseArgs(args) {
             parsed.command = 'version';
         } else if (!arg.startsWith('-')) {
             parsed.command = arg;
+            if (arg === 'sandbox') {
+                parsed.remainingArgs = args.slice(i + 1);
+                break;
+            }
         }
     }
 
@@ -282,11 +639,13 @@ function parseArgs(args) {
 // Main CLI handler
 async function main() {
     const args = process.argv.slice(2);
-    const { command, options } = parseArgs(args);
+    const { command, options, remainingArgs } = parseArgs(args);
 
     // Apply CLI options to environment variables
-    if (options.port) {
-        process.env.PORT = options.port;
+    if (options.serverPort) {
+        process.env.SERVER_PORT = options.serverPort;
+    } else if (!process.env.SERVER_PORT && process.env.PORT) {
+        process.env.SERVER_PORT = process.env.PORT;
     }
     if (options.databasePath) {
         process.env.DATABASE_PATH = options.databasePath;
@@ -296,6 +655,9 @@ async function main() {
         case 'start':
             await startServer();
             break;
+        case 'sandbox':
+            await sandboxCommand(remainingArgs || []);
+            break;
         case 'status':
         case 'info':
             showStatus();

server/cursor-cli.js

@@ -1,5 +1,8 @@
 import { spawn } from 'child_process';
 import crossSpawn from 'cross-spawn';
+import { notifyRunFailed, notifyRunStopped } from './services/notification-orchestrator.js';
+import { sessionsService } from './modules/providers/services/sessions.service.js';
+import { createNormalizedMessage } from './shared/utils.js';
 
 // Use cross-spawn on Windows for better command execution
 const spawnFunction = process.platform === 'win32' ? crossSpawn : spawn;
@@ -23,7 +26,7 @@ function isWorkspaceTrustPrompt(text = '') {
 
 async function spawnCursor(command, options = {}, ws) {
   return new Promise(async (resolve, reject) => {
-    const { sessionId, projectPath, cwd, resume, toolsSettings, skipPermissions, model } = options;
+    const { sessionId, projectPath, cwd, resume, toolsSettings, skipPermissions, model, sessionSummary } = options;
     let capturedSessionId = sessionId; // Track session ID throughout the process
     let sessionCreatedSent = false; // Track if we've already sent session-created event
     let hasRetriedWithTrust = false;
@@ -81,6 +84,35 @@ async function spawnCursor(command, options = {}, ws) {
       const isTrustRetry = runReason === 'trust-retry';
       let runSawWorkspaceTrustPrompt = false;
       let stdoutLineBuffer = '';
+      let terminalNotificationSent = false;
+
+      const notifyTerminalState = ({ code = null, error = null } = {}) => {
+        if (terminalNotificationSent) {
+          return;
+        }
+
+        terminalNotificationSent = true;
+
+        const finalSessionId = capturedSessionId || sessionId || processKey;
+        if (code === 0 && !error) {
+          notifyRunStopped({
+            userId: ws?.userId || null,
+            provider: 'cursor',
+            sessionId: finalSessionId,
+            sessionName: sessionSummary,
+            stopReason: 'completed'
+          });
+          return;
+        }
+
+        notifyRunFailed({
+          userId: ws?.userId || null,
+          provider: 'cursor',
+          sessionId: finalSessionId,
+          sessionName: sessionSummary,
+          error: error || `Cursor CLI exited with code ${code}`
+        });
+      };
 
       if (isTrustRetry) {
         console.log('Retrying Cursor CLI with --trust after workspace trust prompt');
@@ -142,75 +174,42 @@ async function spawnCursor(command, options = {}, ws) {
                   // Send session-created event only once for new sessions
                   if (!sessionId && !sessionCreatedSent) {
                     sessionCreatedSent = true;
-                    ws.send({
-                      type: 'session-created',
-                      sessionId: capturedSessionId,
-                      model: response.model,
-                      cwd: response.cwd
-                    });
+                    ws.send(createNormalizedMessage({ kind: 'session_created', newSessionId: capturedSessionId, model: response.model, cwd: response.cwd, sessionId: capturedSessionId, provider: 'cursor' }));
                   }
                 }
 
-                // Send system info to frontend
-                ws.send({
-                  type: 'cursor-system',
-                  data: response,
-                  sessionId: capturedSessionId || sessionId || null
-                });
+                // System info — no longer needed by the frontend (session-lifecycle 'created' handles nav).
               }
               break;
 
             case 'user':
-              // Forward user message
-              ws.send({
-                type: 'cursor-user',
-                data: response,
-                sessionId: capturedSessionId || sessionId || null
-              });
+              // User messages are not displayed in the UI — skip.
               break;
 
             case 'assistant':
               // Accumulate assistant message chunks
               if (response.message && response.message.content && response.message.content.length > 0) {
-                const textContent = response.message.content[0].text;
-
-                // Send as Claude-compatible format for frontend
-                ws.send({
-                  type: 'claude-response',
-                  data: {
-                    type: 'content_block_delta',
-                    delta: {
-                      type: 'text_delta',
-                      text: textContent
-                    }
-                  },
-                  sessionId: capturedSessionId || sessionId || null
-                });
+                const normalized = sessionsService.normalizeMessage('cursor', response, capturedSessionId || sessionId || null);
+                for (const msg of normalized) ws.send(msg);
               }
               break;
 
-            case 'result':
-              // Session complete
+            case 'result': {
+              // Session complete — send stream end + lifecycle complete with result payload
               console.log('Cursor session result:', response);
-
-              // Do not emit an extra content_block_stop here.
-              // The UI already finalizes the streaming message in cursor-result handling,
-              // and emitting both can produce duplicate assistant messages.
-              ws.send({
-                type: 'cursor-result',
-                sessionId: capturedSessionId || sessionId,
-                data: response,
-                success: response.subtype === 'success'
-              });
+              const resultText = typeof response.result === 'string' ? response.result : '';
+              ws.send(createNormalizedMessage({
+                kind: 'complete',
+                exitCode: response.subtype === 'success' ? 0 : 1,
+                resultText,
+                isError: response.subtype !== 'success',
+                sessionId: capturedSessionId || sessionId, provider: 'cursor',
+              }));
               break;
+            }
 
             default:
-              // Forward any other message types
-              ws.send({
-                type: 'cursor-response',
-                data: response,
-                sessionId: capturedSessionId || sessionId || null
-              });
+              // Unknown message types — ignore.
           }
         } catch (parseError) {
           console.log('Non-JSON response:', line);
@@ -219,12 +218,9 @@ async function spawnCursor(command, options = {}, ws) {
             return;
           }
 
-          // If not JSON, send as raw text
-          ws.send({
-            type: 'cursor-output',
-            data: line,
-            sessionId: capturedSessionId || sessionId || null
-          });
+          // If not JSON, send as stream delta via adapter
+          const normalized = sessionsService.normalizeMessage('cursor', line, capturedSessionId || sessionId || null);
+          for (const msg of normalized) ws.send(msg);
         }
       };
 
@@ -252,11 +248,7 @@ async function spawnCursor(command, options = {}, ws) {
           return;
         }
 
-        ws.send({
-          type: 'cursor-error',
-          error: stderrText,
-          sessionId: capturedSessionId || sessionId || null
-        });
+        ws.send(createNormalizedMessage({ kind: 'error', content: stderrText, sessionId: capturedSessionId || sessionId || null, provider: 'cursor' }));
       });
 
       // Handle process completion
@@ -283,16 +275,13 @@ async function spawnCursor(command, options = {}, ws) {
           return;
         }
 
-        ws.send({
-          type: 'claude-complete',
-          sessionId: finalSessionId,
-          exitCode: code,
-          isNewSession: !sessionId && !!command // Flag to indicate this was a new session
-        });
+        ws.send(createNormalizedMessage({ kind: 'complete', exitCode: code, isNewSession: !sessionId && !!command, sessionId: finalSessionId, provider: 'cursor' }));
 
         if (code === 0) {
+          notifyTerminalState({ code });
           settleOnce(() => resolve());
         } else {
+          notifyTerminalState({ code });
           settleOnce(() => reject(new Error(`Cursor CLI exited with code ${code}`)));
         }
       });
@@ -305,11 +294,8 @@ async function spawnCursor(command, options = {}, ws) {
         const finalSessionId = capturedSessionId || sessionId || processKey;
         activeCursorProcesses.delete(finalSessionId);
 
-        ws.send({
-          type: 'cursor-error',
-          error: error.message,
-          sessionId: capturedSessionId || sessionId || null
-        });
+        ws.send(createNormalizedMessage({ kind: 'error', content: error.message, sessionId: capturedSessionId || sessionId || null, provider: 'cursor' }));
+        notifyTerminalState({ error });
 
         settleOnce(() => reject(error));
       });

server/database/db.js

@@ -2,11 +2,21 @@ import Database from 'better-sqlite3';
 import path from 'path';
 import fs from 'fs';
 import crypto from 'crypto';
-import { fileURLToPath } from 'url';
-import { dirname } from 'path';
+import { findAppRoot, getModuleDir } from '../utils/runtime-paths.js';
+import {
+  APP_CONFIG_TABLE_SQL,
+  USER_NOTIFICATION_PREFERENCES_TABLE_SQL,
+  VAPID_KEYS_TABLE_SQL,
+  PUSH_SUBSCRIPTIONS_TABLE_SQL,
+  SESSION_NAMES_TABLE_SQL,
+  SESSION_NAMES_LOOKUP_INDEX_SQL,
+  DATABASE_SCHEMA_SQL
+} from './schema.js';
 
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
+const __dirname = getModuleDir(import.meta.url);
+// The compiled backend lives under dist-server/server/database, but the install root we log
+// should still point at the project/app root. Resolving it here avoids build-layout drift.
+const APP_ROOT = findAppRoot(__dirname);
 
 // ANSI color codes for terminal output
 const colors = {
@@ -24,7 +34,6 @@ const c = {
 
 // Use DATABASE_PATH environment variable if set, otherwise use default location
 const DB_PATH = process.env.DATABASE_PATH || path.join(__dirname, 'auth.db');
-const INIT_SQL_PATH = path.join(__dirname, 'init.sql');
 
 // Ensure database directory exists if custom path is provided
 if (process.env.DATABASE_PATH) {
@@ -62,14 +71,10 @@ const db = new Database(DB_PATH);
 // app_config must exist before any other module imports (auth.js reads the JWT secret at load time).
 // runMigrations() also creates this table, but it runs too late for existing installations
 // where auth.js is imported before initializeDatabase() is called.
-db.exec(`CREATE TABLE IF NOT EXISTS app_config (
-  key TEXT PRIMARY KEY,
-  value TEXT NOT NULL,
-  created_at DATETIME DEFAULT CURRENT_TIMESTAMP
-)`);
+db.exec(APP_CONFIG_TABLE_SQL);
 
 // Show app installation path prominently
-const appInstallPath = path.join(__dirname, '../..');
+const appInstallPath = APP_ROOT;
 console.log('');
 console.log(c.dim('═'.repeat(60)));
 console.log(`${c.info('[INFO]')} App Installation: ${c.bright(appInstallPath)}`);
@@ -100,24 +105,12 @@ const runMigrations = () => {
       db.exec('ALTER TABLE users ADD COLUMN has_completed_onboarding BOOLEAN DEFAULT 0');
     }
 
-    // Create app_config table if it doesn't exist (for existing installations)
-    db.exec(`CREATE TABLE IF NOT EXISTS app_config (
-      key TEXT PRIMARY KEY,
-      value TEXT NOT NULL,
-      created_at DATETIME DEFAULT CURRENT_TIMESTAMP
-    )`);
-
-    // Create session_names table if it doesn't exist (for existing installations)
-    db.exec(`CREATE TABLE IF NOT EXISTS session_names (
-      id INTEGER PRIMARY KEY AUTOINCREMENT,
-      session_id TEXT NOT NULL,
-      provider TEXT NOT NULL DEFAULT 'claude',
-      custom_name TEXT NOT NULL,
-      created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
-      updated_at DATETIME DEFAULT CURRENT_TIMESTAMP,
-      UNIQUE(session_id, provider)
-    )`);
-    db.exec('CREATE INDEX IF NOT EXISTS idx_session_names_lookup ON session_names(session_id, provider)');
+    db.exec(USER_NOTIFICATION_PREFERENCES_TABLE_SQL);
+    db.exec(VAPID_KEYS_TABLE_SQL);
+    db.exec(PUSH_SUBSCRIPTIONS_TABLE_SQL);
+    db.exec(APP_CONFIG_TABLE_SQL);
+    db.exec(SESSION_NAMES_TABLE_SQL);
+    db.exec(SESSION_NAMES_LOOKUP_INDEX_SQL);
 
     console.log('Database migrations completed successfully');
   } catch (error) {
@@ -129,8 +122,7 @@ const runMigrations = () => {
 // Initialize database with schema
 const initializeDatabase = async () => {
   try {
-    const initSQL = fs.readFileSync(INIT_SQL_PATH, 'utf8');
-    db.exec(initSQL);
+    db.exec(DATABASE_SCHEMA_SQL);
     console.log('Database initialized successfully');
     runMigrations();
   } catch (error) {
@@ -376,6 +368,116 @@ const credentialsDb = {
   }
 };
 
+const DEFAULT_NOTIFICATION_PREFERENCES = {
+  channels: {
+    inApp: false,
+    webPush: false
+  },
+  events: {
+    actionRequired: true,
+    stop: true,
+    error: true
+  }
+};
+
+const normalizeNotificationPreferences = (value) => {
+  const source = value && typeof value === 'object' ? value : {};
+
+  return {
+    channels: {
+      inApp: source.channels?.inApp === true,
+      webPush: source.channels?.webPush === true
+    },
+    events: {
+      actionRequired: source.events?.actionRequired !== false,
+      stop: source.events?.stop !== false,
+      error: source.events?.error !== false
+    }
+  };
+};
+
+const notificationPreferencesDb = {
+  getPreferences: (userId) => {
+    try {
+      const row = db.prepare('SELECT preferences_json FROM user_notification_preferences WHERE user_id = ?').get(userId);
+      if (!row) {
+        const defaults = normalizeNotificationPreferences(DEFAULT_NOTIFICATION_PREFERENCES);
+        db.prepare(
+          'INSERT INTO user_notification_preferences (user_id, preferences_json, updated_at) VALUES (?, ?, CURRENT_TIMESTAMP)'
+        ).run(userId, JSON.stringify(defaults));
+        return defaults;
+      }
+
+      let parsed;
+      try {
+        parsed = JSON.parse(row.preferences_json);
+      } catch {
+        parsed = DEFAULT_NOTIFICATION_PREFERENCES;
+      }
+      return normalizeNotificationPreferences(parsed);
+    } catch (err) {
+      throw err;
+    }
+  },
+
+  updatePreferences: (userId, preferences) => {
+    try {
+      const normalized = normalizeNotificationPreferences(preferences);
+      db.prepare(
+        `INSERT INTO user_notification_preferences (user_id, preferences_json, updated_at)
+         VALUES (?, ?, CURRENT_TIMESTAMP)
+         ON CONFLICT(user_id) DO UPDATE SET
+           preferences_json = excluded.preferences_json,
+           updated_at = CURRENT_TIMESTAMP`
+      ).run(userId, JSON.stringify(normalized));
+      return normalized;
+    } catch (err) {
+      throw err;
+    }
+  }
+};
+
+const pushSubscriptionsDb = {
+  saveSubscription: (userId, endpoint, keysP256dh, keysAuth) => {
+    try {
+      db.prepare(
+        `INSERT INTO push_subscriptions (user_id, endpoint, keys_p256dh, keys_auth)
+         VALUES (?, ?, ?, ?)
+         ON CONFLICT(endpoint) DO UPDATE SET
+           user_id = excluded.user_id,
+           keys_p256dh = excluded.keys_p256dh,
+           keys_auth = excluded.keys_auth`
+      ).run(userId, endpoint, keysP256dh, keysAuth);
+    } catch (err) {
+      throw err;
+    }
+  },
+
+  getSubscriptions: (userId) => {
+    try {
+      return db.prepare('SELECT endpoint, keys_p256dh, keys_auth FROM push_subscriptions WHERE user_id = ?').all(userId);
+    } catch (err) {
+      throw err;
+    }
+  },
+
+  removeSubscription: (endpoint) => {
+    try {
+      db.prepare('DELETE FROM push_subscriptions WHERE endpoint = ?').run(endpoint);
+    } catch (err) {
+      throw err;
+    }
+  },
+
+  removeAllForUser: (userId) => {
+    try {
+      db.prepare('DELETE FROM push_subscriptions WHERE user_id = ?').run(userId);
+    } catch (err) {
+      throw err;
+    }
+  }
+};
+
 // Session custom names database operations
 const sessionNamesDb = {
   // Set (insert or update) a custom session name
@@ -482,8 +584,10 @@ export {
   userDb,
   apiKeysDb,
   credentialsDb,
+  notificationPreferencesDb,
+  pushSubscriptionsDb,
   sessionNamesDb,
   applyCustomSessionNames,
   appConfigDb,
   githubTokensDb // Backward compatibility
-};
+};

server/database/init.sql

@@ -1,72 +0,0 @@
--- Initialize authentication database
-PRAGMA foreign_keys = ON;
-
--- Users table (single user system)
-CREATE TABLE IF NOT EXISTS users (
-    id INTEGER PRIMARY KEY AUTOINCREMENT,
-    username TEXT UNIQUE NOT NULL,
-    password_hash TEXT NOT NULL,
-    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
-    last_login DATETIME,
-    is_active BOOLEAN DEFAULT 1,
-    git_name TEXT,
-    git_email TEXT,
-    has_completed_onboarding BOOLEAN DEFAULT 0
-);
-
--- Indexes for performance
-CREATE INDEX IF NOT EXISTS idx_users_username ON users(username);
-CREATE INDEX IF NOT EXISTS idx_users_active ON users(is_active);
-
--- API Keys table for external API access
-CREATE TABLE IF NOT EXISTS api_keys (
-    id INTEGER PRIMARY KEY AUTOINCREMENT,
-    user_id INTEGER NOT NULL,
-    key_name TEXT NOT NULL,
-    api_key TEXT UNIQUE NOT NULL,
-    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
-    last_used DATETIME,
-    is_active BOOLEAN DEFAULT 1,
-    FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE
-);
-
-CREATE INDEX IF NOT EXISTS idx_api_keys_key ON api_keys(api_key);
-CREATE INDEX IF NOT EXISTS idx_api_keys_user_id ON api_keys(user_id);
-CREATE INDEX IF NOT EXISTS idx_api_keys_active ON api_keys(is_active);
-
--- User credentials table for storing various tokens/credentials (GitHub, GitLab, etc.)
-CREATE TABLE IF NOT EXISTS user_credentials (
-    id INTEGER PRIMARY KEY AUTOINCREMENT,
-    user_id INTEGER NOT NULL,
-    credential_name TEXT NOT NULL,
-    credential_type TEXT NOT NULL, -- 'github_token', 'gitlab_token', 'bitbucket_token', etc.
-    credential_value TEXT NOT NULL,
-    description TEXT,
-    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
-    is_active BOOLEAN DEFAULT 1,
-    FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE
-);
-
-CREATE INDEX IF NOT EXISTS idx_user_credentials_user_id ON user_credentials(user_id);
-CREATE INDEX IF NOT EXISTS idx_user_credentials_type ON user_credentials(credential_type);
-CREATE INDEX IF NOT EXISTS idx_user_credentials_active ON user_credentials(is_active);
-
--- Session custom names (provider-agnostic display name overrides)
-CREATE TABLE IF NOT EXISTS session_names (
-    id INTEGER PRIMARY KEY AUTOINCREMENT,
-    session_id TEXT NOT NULL,
-    provider TEXT NOT NULL DEFAULT 'claude',
-    custom_name TEXT NOT NULL,
-    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
-    updated_at DATETIME DEFAULT CURRENT_TIMESTAMP,
-    UNIQUE(session_id, provider)
-);
-
-CREATE INDEX IF NOT EXISTS idx_session_names_lookup ON session_names(session_id, provider);
-
--- App configuration table (auto-generated secrets, settings, etc.)
-CREATE TABLE IF NOT EXISTS app_config (
-    key TEXT PRIMARY KEY,
-    value TEXT NOT NULL,
-    created_at DATETIME DEFAULT CURRENT_TIMESTAMP
-);

server/database/schema.js

@@ -0,0 +1,102 @@
+export const APP_CONFIG_TABLE_SQL = `CREATE TABLE IF NOT EXISTS app_config (
+  key TEXT PRIMARY KEY,
+  value TEXT NOT NULL,
+  created_at DATETIME DEFAULT CURRENT_TIMESTAMP
+);`;
+
+export const USER_NOTIFICATION_PREFERENCES_TABLE_SQL = `CREATE TABLE IF NOT EXISTS user_notification_preferences (
+  user_id INTEGER PRIMARY KEY,
+  preferences_json TEXT NOT NULL,
+  updated_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+  FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE
+);`;
+
+export const VAPID_KEYS_TABLE_SQL = `CREATE TABLE IF NOT EXISTS vapid_keys (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  public_key TEXT NOT NULL,
+  private_key TEXT NOT NULL,
+  created_at DATETIME DEFAULT CURRENT_TIMESTAMP
+);`;
+
+export const PUSH_SUBSCRIPTIONS_TABLE_SQL = `CREATE TABLE IF NOT EXISTS push_subscriptions (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  user_id INTEGER NOT NULL,
+  endpoint TEXT NOT NULL UNIQUE,
+  keys_p256dh TEXT NOT NULL,
+  keys_auth TEXT NOT NULL,
+  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+  FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE
+);`;
+
+export const SESSION_NAMES_TABLE_SQL = `CREATE TABLE IF NOT EXISTS session_names (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  session_id TEXT NOT NULL,
+  provider TEXT NOT NULL DEFAULT 'claude',
+  custom_name TEXT NOT NULL,
+  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+  updated_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+  UNIQUE(session_id, provider)
+);`;
+
+export const SESSION_NAMES_LOOKUP_INDEX_SQL = `CREATE INDEX IF NOT EXISTS idx_session_names_lookup ON session_names(session_id, provider);`;
+
+export const DATABASE_SCHEMA_SQL = `PRAGMA foreign_keys = ON;
+
+CREATE TABLE IF NOT EXISTS users (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  username TEXT UNIQUE NOT NULL,
+  password_hash TEXT NOT NULL,
+  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+  last_login DATETIME,
+  is_active BOOLEAN DEFAULT 1,
+  git_name TEXT,
+  git_email TEXT,
+  has_completed_onboarding BOOLEAN DEFAULT 0
+);
+
+CREATE INDEX IF NOT EXISTS idx_users_username ON users(username);
+CREATE INDEX IF NOT EXISTS idx_users_active ON users(is_active);
+
+CREATE TABLE IF NOT EXISTS api_keys (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  user_id INTEGER NOT NULL,
+  key_name TEXT NOT NULL,
+  api_key TEXT UNIQUE NOT NULL,
+  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+  last_used DATETIME,
+  is_active BOOLEAN DEFAULT 1,
+  FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE
+);
+
+CREATE INDEX IF NOT EXISTS idx_api_keys_key ON api_keys(api_key);
+CREATE INDEX IF NOT EXISTS idx_api_keys_user_id ON api_keys(user_id);
+CREATE INDEX IF NOT EXISTS idx_api_keys_active ON api_keys(is_active);
+
+CREATE TABLE IF NOT EXISTS user_credentials (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  user_id INTEGER NOT NULL,
+  credential_name TEXT NOT NULL,
+  credential_type TEXT NOT NULL,
+  credential_value TEXT NOT NULL,
+  description TEXT,
+  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+  is_active BOOLEAN DEFAULT 1,
+  FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE
+);
+
+CREATE INDEX IF NOT EXISTS idx_user_credentials_user_id ON user_credentials(user_id);
+CREATE INDEX IF NOT EXISTS idx_user_credentials_type ON user_credentials(credential_type);
+CREATE INDEX IF NOT EXISTS idx_user_credentials_active ON user_credentials(is_active);
+
+${USER_NOTIFICATION_PREFERENCES_TABLE_SQL}
+
+${VAPID_KEYS_TABLE_SQL}
+
+${PUSH_SUBSCRIPTIONS_TABLE_SQL}
+
+${SESSION_NAMES_TABLE_SQL}
+
+${SESSION_NAMES_LOOKUP_INDEX_SQL}
+
+${APP_CONFIG_TABLE_SQL}
+`;

server/gemini-cli.js

@@ -6,14 +6,15 @@ const spawnFunction = process.platform === 'win32' ? crossSpawn : spawn;
 import { promises as fs } from 'fs';
 import path from 'path';
 import os from 'os';
-import { getSessions, getSessionMessages } from './projects.js';
 import sessionManager from './sessionManager.js';
 import GeminiResponseHandler from './gemini-response-handler.js';
+import { notifyRunFailed, notifyRunStopped } from './services/notification-orchestrator.js';
+import { createNormalizedMessage } from './shared/utils.js';
 
 let activeGeminiProcesses = new Map(); // Track active processes by session ID
 
 async function spawnGemini(command, options = {}, ws) {
-    const { sessionId, projectPath, cwd, resume, toolsSettings, permissionMode, images } = options;
+    const { sessionId, projectPath, cwd, toolsSettings, permissionMode, images, sessionSummary } = options;
     let capturedSessionId = sessionId; // Track session ID throughout the process
     let sessionCreatedSent = false; // Track if we've already sent session-created event
     let assistantBlocks = []; // Accumulate the full response blocks including tools
@@ -172,6 +173,36 @@ async function spawnGemini(command, options = {}, ws) {
             stdio: ['pipe', 'pipe', 'pipe'],
             env: { ...process.env } // Inherit all environment variables
         });
+        let terminalNotificationSent = false;
+        let terminalFailureReason = null;
+
+        const notifyTerminalState = ({ code = null, error = null } = {}) => {
+            if (terminalNotificationSent) {
+                return;
+            }
+
+            terminalNotificationSent = true;
+
+            const finalSessionId = capturedSessionId || sessionId || processKey;
+            if (code === 0 && !error) {
+                notifyRunStopped({
+                    userId: ws?.userId || null,
+                    provider: 'gemini',
+                    sessionId: finalSessionId,
+                    sessionName: sessionSummary,
+                    stopReason: 'completed'
+                });
+                return;
+            }
+
+            notifyRunFailed({
+                userId: ws?.userId || null,
+                provider: 'gemini',
+                sessionId: finalSessionId,
+                sessionName: sessionSummary,
+                error: error || terminalFailureReason || `Gemini CLI exited with code ${code}`
+            });
+        };
 
         // Attach temp file info to process for cleanup later
         geminiProcess.tempImagePaths = tempImagePaths;
@@ -188,7 +219,6 @@ async function spawnGemini(command, options = {}, ws) {
         geminiProcess.stdin.end();
 
         // Add timeout handler
-        let hasReceivedOutput = false;
         const timeoutMs = 120000; // 120 seconds for slower models
         let timeout;
 
@@ -196,11 +226,8 @@ async function spawnGemini(command, options = {}, ws) {
             if (timeout) clearTimeout(timeout);
             timeout = setTimeout(() => {
                 const socketSessionId = typeof ws.getSessionId === 'function' ? ws.getSessionId() : (capturedSessionId || sessionId || processKey);
-                ws.send({
-                    type: 'gemini-error',
-                    sessionId: socketSessionId,
-                    error: `Gemini CLI timeout - no response received for ${timeoutMs / 1000} seconds`
-                });
+                terminalFailureReason = `Gemini CLI timeout - no response received for ${timeoutMs / 1000} seconds`;
+                ws.send(createNormalizedMessage({ kind: 'error', content: terminalFailureReason, sessionId: socketSessionId, provider: 'gemini' }));
                 try {
                     geminiProcess.kill('SIGTERM');
                 } catch (e) { }
@@ -262,7 +289,6 @@ async function spawnGemini(command, options = {}, ws) {
         // Handle stdout
         geminiProcess.stdout.on('data', (data) => {
             const rawOutput = data.toString();
-            hasReceivedOutput = true;
             startTimeout(); // Re-arm the timeout
 
             // For new sessions, create a session ID FIRST
@@ -286,21 +312,7 @@ async function spawnGemini(command, options = {}, ws) {
 
                 ws.setSessionId && typeof ws.setSessionId === 'function' && ws.setSessionId(capturedSessionId);
 
-                ws.send({
-                    type: 'session-created',
-                    sessionId: capturedSessionId
-                });
-
-                // Emit fake system init so the frontend immediately navigates and saves the session
-                ws.send({
-                    type: 'claude-response',
-                    sessionId: capturedSessionId,
-                    data: {
-                        type: 'system',
-                        subtype: 'init',
-                        session_id: capturedSessionId
-                    }
-                });
+                ws.send(createNormalizedMessage({ kind: 'session_created', newSessionId: capturedSessionId, sessionId: capturedSessionId, provider: 'gemini' }));
             }
 
             if (responseHandler) {
@@ -313,14 +325,7 @@ async function spawnGemini(command, options = {}, ws) {
                     assistantBlocks.push({ type: 'text', text: rawOutput });
                 }
                 const socketSessionId = typeof ws.getSessionId === 'function' ? ws.getSessionId() : (capturedSessionId || sessionId);
-                ws.send({
-                    type: 'gemini-response',
-                    sessionId: socketSessionId,
-                    data: {
-                        type: 'message',
-                        content: rawOutput
-                    }
-                });
+                ws.send(createNormalizedMessage({ kind: 'stream_delta', content: rawOutput, sessionId: socketSessionId, provider: 'gemini' }));
             }
         });
 
@@ -337,11 +342,7 @@ async function spawnGemini(command, options = {}, ws) {
             }
 
             const socketSessionId = typeof ws.getSessionId === 'function' ? ws.getSessionId() : (capturedSessionId || sessionId);
-            ws.send({
-                type: 'gemini-error',
-                sessionId: socketSessionId,
-                error: errorMsg
-            });
+            ws.send(createNormalizedMessage({ kind: 'error', content: errorMsg, sessionId: socketSessionId, provider: 'gemini' }));
         });
 
         // Handle process completion
@@ -363,12 +364,7 @@ async function spawnGemini(command, options = {}, ws) {
                 sessionManager.addMessage(finalSessionId, 'assistant', assistantBlocks);
             }
 
-            ws.send({
-                type: 'claude-complete', // Use claude-complete for compatibility with UI
-                sessionId: finalSessionId,
-                exitCode: code,
-                isNewSession: !sessionId && !!command // Flag to indicate this was a new session
-            });
+            ws.send(createNormalizedMessage({ kind: 'complete', exitCode: code, isNewSession: !sessionId && !!command, sessionId: finalSessionId, provider: 'gemini' }));
 
             // Clean up temporary image files if any
             if (geminiProcess.tempImagePaths && geminiProcess.tempImagePaths.length > 0) {
@@ -381,8 +377,13 @@ async function spawnGemini(command, options = {}, ws) {
             }
 
             if (code === 0) {
+                notifyTerminalState({ code });
                 resolve();
             } else {
+                notifyTerminalState({
+                    code,
+                    error: code === null ? 'Gemini CLI process was terminated or timed out' : null
+                });
                 reject(new Error(code === null ? 'Gemini CLI process was terminated or timed out' : `Gemini CLI exited with code ${code}`));
             }
         });
@@ -394,11 +395,8 @@ async function spawnGemini(command, options = {}, ws) {
             activeGeminiProcesses.delete(finalSessionId);
 
             const errorSessionId = typeof ws.getSessionId === 'function' ? ws.getSessionId() : finalSessionId;
-            ws.send({
-                type: 'gemini-error',
-                sessionId: errorSessionId,
-                error: error.message
-            });
+            ws.send(createNormalizedMessage({ kind: 'error', content: error.message, sessionId: errorSessionId, provider: 'gemini' }));
+            notifyTerminalState({ error });
 
             reject(error);
         });

server/gemini-response-handler.js

@@ -1,4 +1,6 @@
 // Gemini Response Handler - JSON Stream processing
+import { sessionsService } from './modules/providers/services/sessions.service.js';
+
 class GeminiResponseHandler {
   constructor(ws, options = {}) {
     this.ws = ws;
@@ -27,13 +29,12 @@ class GeminiResponseHandler {
         this.handleEvent(event);
       } catch (err) {
         // Not a JSON line, probably debug output or CLI warnings
-        // console.error('[Gemini Handler] Non-JSON line ignored:', line);
       }
     }
   }
 
   handleEvent(event) {
-    const socketSessionId = typeof this.ws.getSessionId === 'function' ? this.ws.getSessionId() : null;
+    const sid = typeof this.ws.getSessionId === 'function' ? this.ws.getSessionId() : null;
 
     if (event.type === 'init') {
       if (this.onInit) {
@@ -42,88 +43,26 @@ class GeminiResponseHandler {
       return;
     }
 
+    // Invoke per-type callbacks for session tracking
     if (event.type === 'message' && event.role === 'assistant') {
       const content = event.content || '';
-
-      // Notify the parent CLI handler of accumulated text
       if (this.onContentFragment && content) {
         this.onContentFragment(content);
       }
+    } else if (event.type === 'tool_use' && this.onToolUse) {
+      this.onToolUse(event);
+    } else if (event.type === 'tool_result' && this.onToolResult) {
+      this.onToolResult(event);
+    }
 
-      let payload = {
-        type: 'gemini-response',
-        data: {
-          type: 'message',
-          content: content,
-          isPartial: event.delta === true
-        }
-      };
-      if (socketSessionId) payload.sessionId = socketSessionId;
-      this.ws.send(payload);
-    }
-    else if (event.type === 'tool_use') {
-      if (this.onToolUse) {
-        this.onToolUse(event);
-      }
-      let payload = {
-        type: 'gemini-tool-use',
-        toolName: event.tool_name,
-        toolId: event.tool_id,
-        parameters: event.parameters || {}
-      };
-      if (socketSessionId) payload.sessionId = socketSessionId;
-      this.ws.send(payload);
-    }
-    else if (event.type === 'tool_result') {
-      if (this.onToolResult) {
-        this.onToolResult(event);
-      }
-      let payload = {
-        type: 'gemini-tool-result',
-        toolId: event.tool_id,
-        status: event.status,
-        output: event.output || ''
-      };
-      if (socketSessionId) payload.sessionId = socketSessionId;
-      this.ws.send(payload);
-    }
-    else if (event.type === 'result') {
-      // Send a finalize message string
-      let payload = {
-        type: 'gemini-response',
-        data: {
-          type: 'message',
-          content: '',
-          isPartial: false
-        }
-      };
-      if (socketSessionId) payload.sessionId = socketSessionId;
-      this.ws.send(payload);
-
-      if (event.stats && event.stats.total_tokens) {
-        let statsPayload = {
-          type: 'claude-status',
-          data: {
-            status: 'Complete',
-            tokens: event.stats.total_tokens
-          }
-        };
-        if (socketSessionId) statsPayload.sessionId = socketSessionId;
-        this.ws.send(statsPayload);
-      }
-    }
-    else if (event.type === 'error') {
-      let payload = {
-        type: 'gemini-error',
-        error: event.error || event.message || 'Unknown Gemini streaming error'
-      };
-      if (socketSessionId) payload.sessionId = socketSessionId;
-      this.ws.send(payload);
+    // Normalize via adapter and send all resulting messages
+    const normalized = sessionsService.normalizeMessage('gemini', event, sid);
+    for (const msg of normalized) {
+      this.ws.send(msg);
     }
   }
 
   forceFlush() {
-    // If the buffer has content, try to parse it one last time
     if (this.buffer.trim()) {
       try {
         const event = JSON.parse(this.buffer);

server/index.js

@@ -3,13 +3,16 @@
 import './load-env.js';
 import fs from 'fs';
 import path from 'path';
-import { fileURLToPath } from 'url';
-import { dirname } from 'path';
+import { findAppRoot, getModuleDir } from './utils/runtime-paths.js';
 
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
+import { AppError, createNormalizedMessage } from '@/shared/utils.js';
 
-const installMode = fs.existsSync(path.join(__dirname, '..', '.git')) ? 'git' : 'npm';
+
+const __dirname = getModuleDir(import.meta.url);
+// The server source runs from /server, while the compiled output runs from /dist-server/server.
+// Resolving the app root once keeps every repo-level lookup below aligned across both layouts.
+const APP_ROOT = findAppRoot(__dirname);
+const installMode = fs.existsSync(path.join(APP_ROOT, '.git')) ? 'git' : 'npm';
 
 // ANSI color codes for terminal output
 const colors = {
@@ -31,7 +34,7 @@ const c = {
     dim: (text) => `${colors.dim}${text}${colors.reset}`,
 };
 
-console.log('PORT from env:', process.env.PORT);
+console.log('SERVER_PORT from env:', process.env.SERVER_PORT);
 
 import express from 'express';
 import { WebSocketServer, WebSocket } from 'ws';
@@ -41,10 +44,9 @@ import cors from 'cors';
 import { promises as fsPromises } from 'fs';
 import { spawn } from 'child_process';
 import pty from 'node-pty';
-import fetch from 'node-fetch';
 import mime from 'mime-types';
 
-import { getProjects, getSessions, getSessionMessages, renameProject, deleteSession, deleteProject, addProjectManually, extractProjectDirectory, clearProjectDirectoryCache, searchConversations } from './projects.js';
+import { getProjects, getSessions, renameProject, deleteSession, deleteProject, extractProjectDirectory, clearProjectDirectoryCache, searchConversations } from './projects.js';
 import { queryClaudeSDK, abortClaudeSDKSession, isClaudeSDKSessionActive, getActiveClaudeSDKSessions, resolveToolApproval, getPendingApprovalsForSession, reconnectSessionWriter } from './claude-sdk.js';
 import { spawnCursor, abortCursorSession, isCursorSessionActive, getActiveCursorSessions } from './cursor-cli.js';
 import { queryCodex, abortCodexSession, isCodexSessionActive, getActiveCodexSessions } from './openai-codex.js';
@@ -52,7 +54,6 @@ import { spawnGemini, abortGeminiSession, isGeminiSessionActive, getActiveGemini
 import sessionManager from './sessionManager.js';
 import gitRoutes from './routes/git.js';
 import authRoutes from './routes/auth.js';
-import mcpRoutes from './routes/mcp.js';
 import cursorRoutes from './routes/cursor.js';
 import taskmasterRoutes from './routes/taskmaster.js';
 import mcpUtilsRoutes from './routes/mcp-utils.js';
@@ -60,15 +61,18 @@ import commandsRoutes from './routes/commands.js';
 import settingsRoutes from './routes/settings.js';
 import agentRoutes from './routes/agent.js';
 import projectsRoutes, { WORKSPACES_ROOT, validateWorkspacePath } from './routes/projects.js';
-import cliAuthRoutes from './routes/cli-auth.js';
 import userRoutes from './routes/user.js';
 import codexRoutes from './routes/codex.js';
 import geminiRoutes from './routes/gemini.js';
 import pluginsRoutes from './routes/plugins.js';
-import { startEnabledPluginServers, stopAllPlugins } from './utils/plugin-process-manager.js';
+import messagesRoutes from './routes/messages.js';
+import providerRoutes from './modules/providers/provider.routes.js';
+import { startEnabledPluginServers, stopAllPlugins, getPluginPort } from './utils/plugin-process-manager.js';
 import { initializeDatabase, sessionNamesDb, applyCustomSessionNames } from './database/db.js';
+import { configureWebPush } from './services/vapid-keys.js';
 import { validateApiKey, authenticateToken, authenticateWebSocket } from './middleware/auth.js';
 import { IS_PLATFORM } from './constants/config.js';
+import { getConnectableHost } from '../shared/networkHosts.js';
 
 const VALID_PROVIDERS = ['claude', 'codex', 'cursor', 'gemini'];
 
@@ -361,9 +365,6 @@ app.use('/api/projects', authenticateToken, projectsRoutes);
 // Git API Routes (protected)
 app.use('/api/git', authenticateToken, gitRoutes);
 
-// MCP API Routes (protected)
-app.use('/api/mcp', authenticateToken, mcpRoutes);
-
 // Cursor API Routes (protected)
 app.use('/api/cursor', authenticateToken, cursorRoutes);
 
@@ -379,9 +380,6 @@ app.use('/api/commands', authenticateToken, commandsRoutes);
 // Settings API Routes (protected)
 app.use('/api/settings', authenticateToken, settingsRoutes);
 
-// CLI Authentication API Routes (protected)
-app.use('/api/cli', authenticateToken, cliAuthRoutes);
-
 // User API Routes (protected)
 app.use('/api/user', authenticateToken, userRoutes);
 
@@ -394,15 +392,21 @@ app.use('/api/gemini', authenticateToken, geminiRoutes);
 // Plugins API Routes (protected)
 app.use('/api/plugins', authenticateToken, pluginsRoutes);
 
+// Unified session messages route (protected)
+app.use('/api/sessions', authenticateToken, messagesRoutes);
+
+// Unified provider MCP routes (protected)
+app.use('/api/providers', authenticateToken, providerRoutes);
+
 // Agent API Routes (uses API key authentication)
 app.use('/api/agent', agentRoutes);
 
 // Serve public files (like api-docs.html)
-app.use(express.static(path.join(__dirname, '../public')));
+app.use(express.static(path.join(APP_ROOT, 'public')));
 
 // Static files served after API routes
 // Add cache control: HTML files should not be cached, but assets can be cached
-app.use(express.static(path.join(__dirname, '../dist'), {
+app.use(express.static(path.join(APP_ROOT, 'dist'), {
     setHeaders: (res, filePath) => {
         if (filePath.endsWith('.html')) {
             // Prevent HTML caching to avoid service worker issues after builds
@@ -424,17 +428,24 @@ app.use(express.static(path.join(__dirname, '../dist'), {
 app.post('/api/system/update', authenticateToken, async (req, res) => {
     try {
         // Get the project root directory (parent of server directory)
-        const projectRoot = path.join(__dirname, '..');
+        const projectRoot = APP_ROOT;
 
         console.log('Starting system update from directory:', projectRoot);
 
-        // Run the update command based on install mode
-        const updateCommand = installMode === 'git'
-            ? 'git checkout main && git pull && npm install'
-            : 'npm install -g @siteboon/claude-code-ui@latest';
+        // Platform deployments use their own update workflow from the project root.
+        const updateCommand = IS_PLATFORM
+        // In platform, husky and dev dependencies are not needed
+            ? 'npm run update:platform'
+            : installMode === 'git'
+                ? 'git checkout main && git pull && npm install'
+                : 'npm install -g @cloudcli-ai/cloudcli@latest';
+
+        const updateCwd = IS_PLATFORM || installMode === 'git'
+            ? projectRoot
+            : os.homedir();
 
         const child = spawn('sh', ['-c', updateCommand], {
-            cwd: installMode === 'git' ? projectRoot : os.homedir(),
+            cwd: updateCwd,
             env: process.env
         });
 
@@ -507,31 +518,6 @@ app.get('/api/projects/:projectName/sessions', authenticateToken, async (req, re
     }
 });
 
-// Get messages for a specific session
-app.get('/api/projects/:projectName/sessions/:sessionId/messages', authenticateToken, async (req, res) => {
-    try {
-        const { projectName, sessionId } = req.params;
-        const { limit, offset } = req.query;
-
-        // Parse limit and offset if provided
-        const parsedLimit = limit ? parseInt(limit, 10) : null;
-        const parsedOffset = offset ? parseInt(offset, 10) : 0;
-
-        const result = await getSessionMessages(projectName, sessionId, parsedLimit, parsedOffset);
-
-        // Handle both old and new response formats
-        if (Array.isArray(result)) {
-            // Backward compatibility: no pagination parameters were provided
-            res.json({ messages: result });
-        } else {
-            // New format with pagination info
-            res.json(result);
-        }
-    } catch (error) {
-        res.status(500).json({ error: error.message });
-    }
-});
-
 // Rename project endpoint
 app.put('/api/projects/:projectName/rename', authenticateToken, async (req, res) => {
     try {
@@ -596,23 +582,6 @@ app.delete('/api/projects/:projectName', authenticateToken, async (req, res) =>
     }
 });
 
-// Create project endpoint
-app.post('/api/projects/create', authenticateToken, async (req, res) => {
-    try {
-        const { path: projectPath } = req.body;
-
-        if (!projectPath || !projectPath.trim()) {
-            return res.status(400).json({ error: 'Project path is required' });
-        }
-
-        const project = await addProjectManually(projectPath.trim());
-        res.json({ success: true, project });
-    } catch (error) {
-        console.error('Error creating project:', error);
-        res.status(500).json({ error: error.message });
-    }
-});
-
 // Search conversations content (SSE streaming)
 app.get('/api/search/conversations', authenticateToken, async (req, res) => {
     const query = typeof req.query.q === 'string' ? req.query.q.trim() : '';
@@ -830,7 +799,7 @@ app.get('/api/projects/:projectName/file', authenticateToken, async (req, res) =
     }
 });
 
-// Serve binary file content endpoint (for images, etc.)
+// Serve raw file bytes for previews and downloads.
 app.get('/api/projects/:projectName/files/content', authenticateToken, async (req, res) => {
     try {
         const { projectName } = req.params;
@@ -847,7 +816,11 @@ app.get('/api/projects/:projectName/files/content', authenticateToken, async (re
             return res.status(404).json({ error: 'Project not found' });
         }
 
-        const resolved = path.resolve(filePath);
+        // Match the text reader endpoint so callers can pass either project-relative
+        // or absolute paths without changing how the bytes are served.
+        const resolved = path.isAbsolute(filePath)
+            ? path.resolve(filePath)
+            : path.resolve(projectRoot, filePath);
         const normalizedRoot = path.resolve(projectRoot) + path.sep;
         if (!resolved.startsWith(normalizedRoot)) {
             return res.status(403).json({ error: 'Path must be under project root' });
@@ -956,7 +929,6 @@ app.get('/api/projects/:projectName/files', authenticateToken, async (req, res)
         }
 
         const files = await getFileTree(actualPath, 10, 0, true);
-        const hiddenFiles = files.filter(f => f.name.startsWith('.'));
         res.json(files);
     } catch (error) {
         console.error('[ERROR] File tree error:', error.message);
@@ -1394,6 +1366,50 @@ const uploadFilesHandler = async (req, res) => {
 
 app.post('/api/projects/:projectName/files/upload', authenticateToken, uploadFilesHandler);
 
+/**
+ * Proxy an authenticated client WebSocket to a plugin's internal WS server.
+ * Auth is enforced by verifyClient before this function is reached.
+ */
+function handlePluginWsProxy(clientWs, pathname) {
+    const pluginName = pathname.replace('/plugin-ws/', '');
+    if (!pluginName || /[^a-zA-Z0-9_-]/.test(pluginName)) {
+        clientWs.close(4400, 'Invalid plugin name');
+        return;
+    }
+
+    const port = getPluginPort(pluginName);
+    if (!port) {
+        clientWs.close(4404, 'Plugin not running');
+        return;
+    }
+
+    const upstream = new WebSocket(`ws://127.0.0.1:${port}/ws`);
+
+    upstream.on('open', () => {
+        console.log(`[Plugins] WS proxy connected to "${pluginName}" on port ${port}`);
+    });
+
+    // Relay messages bidirectionally
+    upstream.on('message', (data) => {
+        if (clientWs.readyState === WebSocket.OPEN) clientWs.send(data);
+    });
+    clientWs.on('message', (data) => {
+        if (upstream.readyState === WebSocket.OPEN) upstream.send(data);
+    });
+
+    // Propagate close in both directions
+    upstream.on('close', () => { if (clientWs.readyState === WebSocket.OPEN) clientWs.close(); });
+    clientWs.on('close', () => { if (upstream.readyState === WebSocket.OPEN) upstream.close(); });
+
+    upstream.on('error', (err) => {
+        console.error(`[Plugins] WS proxy error for "${pluginName}":`, err.message);
+        if (clientWs.readyState === WebSocket.OPEN) clientWs.close(4502, 'Upstream error');
+    });
+    clientWs.on('error', () => {
+        if (upstream.readyState === WebSocket.OPEN) upstream.close();
+    });
+}
+
 // WebSocket connection handler that routes based on URL path
 wss.on('connection', (ws, request) => {
     const url = request.url;
@@ -1406,7 +1422,9 @@ wss.on('connection', (ws, request) => {
     if (pathname === '/shell') {
         handleShellConnection(ws);
     } else if (pathname === '/ws') {
-        handleChatConnection(ws);
+        handleChatConnection(ws, request);
+    } else if (pathname.startsWith('/plugin-ws/')) {
+        handlePluginWsProxy(ws, pathname);
     } else {
         console.log('[WARN] Unknown WebSocket path:', pathname);
         ws.close();
@@ -1415,17 +1433,21 @@ wss.on('connection', (ws, request) => {
 
 /**
  * WebSocket Writer - Wrapper for WebSocket to match SSEStreamWriter interface
+ *
+ * Provider files use `createNormalizedMessage()` from `shared/utils.js` and
+ * adapter `normalizeMessage()` to produce unified NormalizedMessage events.
+ * The writer simply serialises and sends.
  */
 class WebSocketWriter {
-    constructor(ws) {
+    constructor(ws, userId = null) {
         this.ws = ws;
         this.sessionId = null;
+        this.userId = userId;
         this.isWebSocketWriter = true;  // Marker for transport detection
     }
 
     send(data) {
         if (this.ws.readyState === 1) { // WebSocket.OPEN
-            // Providers send raw objects, we stringify for WebSocket
             this.ws.send(JSON.stringify(data));
         }
     }
@@ -1444,14 +1466,14 @@ class WebSocketWriter {
 }
 
 // Handle chat WebSocket connections
-function handleChatConnection(ws) {
+function handleChatConnection(ws, request) {
     console.log('[INFO] Chat WebSocket connected');
 
     // Add to connected clients for project updates
     connectedClients.add(ws);
 
     // Wrap WebSocket with writer for consistent interface with SSEStreamWriter
-    const writer = new WebSocketWriter(ws);
+    const writer = new WebSocketWriter(ws, request?.user?.id ?? request?.user?.userId ?? null);
 
     ws.on('message', async (message) => {
         try {
@@ -1506,12 +1528,7 @@ function handleChatConnection(ws) {
                     success = await abortClaudeSDKSession(data.sessionId);
                 }
 
-                writer.send({
-                    type: 'session-aborted',
-                    sessionId: data.sessionId,
-                    provider,
-                    success
-                });
+                writer.send(createNormalizedMessage({ kind: 'complete', exitCode: success ? 0 : 1, aborted: true, success, sessionId: data.sessionId, provider }));
             } else if (data.type === 'claude-permission-response') {
                 // Relay UI approval decisions back into the SDK control flow.
                 // This does not persist permissions; it only resolves the in-flight request,
@@ -1527,12 +1544,7 @@ function handleChatConnection(ws) {
             } else if (data.type === 'cursor-abort') {
                 console.log('[DEBUG] Abort Cursor session:', data.sessionId);
                 const success = abortCursorSession(data.sessionId);
-                writer.send({
-                    type: 'session-aborted',
-                    sessionId: data.sessionId,
-                    provider: 'cursor',
-                    success
-                });
+                writer.send(createNormalizedMessage({ kind: 'complete', exitCode: success ? 0 : 1, aborted: true, success, sessionId: data.sessionId, provider: 'cursor' }));
             } else if (data.type === 'check-session-status') {
                 // Check if a specific session is currently processing
                 const provider = data.provider || 'claude';
@@ -1959,155 +1971,6 @@ function handleShellConnection(ws) {
         console.error('[ERROR] Shell WebSocket error:', error);
     });
 }
-// Audio transcription endpoint
-app.post('/api/transcribe', authenticateToken, async (req, res) => {
-    try {
-        const multer = (await import('multer')).default;
-        const upload = multer({ storage: multer.memoryStorage() });
-
-        // Handle multipart form data
-        upload.single('audio')(req, res, async (err) => {
-            if (err) {
-                return res.status(400).json({ error: 'Failed to process audio file' });
-            }
-
-            if (!req.file) {
-                return res.status(400).json({ error: 'No audio file provided' });
-            }
-
-            const apiKey = process.env.OPENAI_API_KEY;
-            if (!apiKey) {
-                return res.status(500).json({ error: 'OpenAI API key not configured. Please set OPENAI_API_KEY in server environment.' });
-            }
-
-            try {
-                // Create form data for OpenAI
-                const FormData = (await import('form-data')).default;
-                const formData = new FormData();
-                formData.append('file', req.file.buffer, {
-                    filename: req.file.originalname,
-                    contentType: req.file.mimetype
-                });
-                formData.append('model', 'whisper-1');
-                formData.append('response_format', 'json');
-                formData.append('language', 'en');
-
-                // Make request to OpenAI
-                const response = await fetch('https://api.openai.com/v1/audio/transcriptions', {
-                    method: 'POST',
-                    headers: {
-                        'Authorization': `Bearer ${apiKey}`,
-                        ...formData.getHeaders()
-                    },
-                    body: formData
-                });
-
-                if (!response.ok) {
-                    const errorData = await response.json().catch(() => ({}));
-                    throw new Error(errorData.error?.message || `Whisper API error: ${response.status}`);
-                }
-
-                const data = await response.json();
-                let transcribedText = data.text || '';
-
-                // Check if enhancement mode is enabled
-                const mode = req.body.mode || 'default';
-
-                // If no transcribed text, return empty
-                if (!transcribedText) {
-                    return res.json({ text: '' });
-                }
-
-                // If default mode, return transcribed text without enhancement
-                if (mode === 'default') {
-                    return res.json({ text: transcribedText });
-                }
-
-                // Handle different enhancement modes
-                try {
-                    const OpenAI = (await import('openai')).default;
-                    const openai = new OpenAI({ apiKey });
-
-                    let prompt, systemMessage, temperature = 0.7, maxTokens = 800;
-
-                    switch (mode) {
-                        case 'prompt':
-                            systemMessage = 'You are an expert prompt engineer who creates clear, detailed, and effective prompts.';
-                            prompt = `You are an expert prompt engineer. Transform the following rough instruction into a clear, detailed, and context-aware AI prompt.
-
-Your enhanced prompt should:
-1. Be specific and unambiguous
-2. Include relevant context and constraints
-3. Specify the desired output format
-4. Use clear, actionable language
-5. Include examples where helpful
-6. Consider edge cases and potential ambiguities
-
-Transform this rough instruction into a well-crafted prompt:
-"${transcribedText}"
-
-Enhanced prompt:`;
-                            break;
-
-                        case 'vibe':
-                        case 'instructions':
-                        case 'architect':
-                            systemMessage = 'You are a helpful assistant that formats ideas into clear, actionable instructions for AI agents.';
-                            temperature = 0.5; // Lower temperature for more controlled output
-                            prompt = `Transform the following idea into clear, well-structured instructions that an AI agent can easily understand and execute.
-
-IMPORTANT RULES:
-- Format as clear, step-by-step instructions
-- Add reasonable implementation details based on common patterns
-- Only include details directly related to what was asked
-- Do NOT add features or functionality not mentioned
-- Keep the original intent and scope intact
-- Use clear, actionable language an agent can follow
-
-Transform this idea into agent-friendly instructions:
-"${transcribedText}"
-
-Agent instructions:`;
-                            break;
-
-                        default:
-                            // No enhancement needed
-                            break;
-                    }
-
-                    // Only make GPT call if we have a prompt
-                    if (prompt) {
-                        const completion = await openai.chat.completions.create({
-                            model: 'gpt-4o-mini',
-                            messages: [
-                                { role: 'system', content: systemMessage },
-                                { role: 'user', content: prompt }
-                            ],
-                            temperature: temperature,
-                            max_tokens: maxTokens
-                        });
-
-                        transcribedText = completion.choices[0].message.content || transcribedText;
-                    }
-
-                } catch (gptError) {
-                    console.error('GPT processing error:', gptError);
-                    // Fall back to original transcription if GPT fails
-                }
-
-                res.json({ text: transcribedText });
-
-            } catch (error) {
-                console.error('Transcription error:', error);
-                res.status(500).json({ error: error.message });
-            }
-        });
-    } catch (error) {
-        console.error('Endpoint error:', error);
-        res.status(500).json({ error: 'Internal server error' });
-    }
-});
-
 // Image upload endpoint
 app.post('/api/projects/:projectName/upload-images', authenticateToken, async (req, res) => {
     try {
@@ -2390,7 +2253,7 @@ app.get('*', (req, res) => {
 
     // Only serve index.html for HTML routes, not for static assets
     // Static assets should already be handled by express.static middleware above
-    const indexPath = path.join(__dirname, '../dist/index.html');
+    const indexPath = path.join(APP_ROOT, 'dist', 'index.html');
 
     // Check if dist/index.html exists (production build available)
     if (fs.existsSync(indexPath)) {
@@ -2401,10 +2264,35 @@ app.get('*', (req, res) => {
         res.sendFile(indexPath);
     } else {
         // In development, redirect to Vite dev server only if dist doesn't exist
-        res.redirect(`http://localhost:${process.env.VITE_PORT || 5173}`);
+        const redirectHost = getConnectableHost(req.hostname);
+        res.redirect(`${req.protocol}://${redirectHost}:${VITE_PORT}`);
     }
 });
 
+// global error middleware must be last
+app.use((err, req, res, next) => {
+  if (err instanceof AppError) {
+    return res.status(err.statusCode).json({
+      success: false,
+      error: {
+        code: err.code,
+        message: err.message,
+        details: err.details,
+      },
+    });
+  }
+
+  console.error(err);
+
+  return res.status(500).json({
+    success: false,
+    error: {
+      code: 'INTERNAL_ERROR',
+      message: 'Internal server error',
+    },
+  });
+});
+
 // Helper function to convert permissions to rwx format
 function permToRwx(perm) {
     const r = perm & 4 ? 'r' : '-';
@@ -2489,10 +2377,10 @@ async function getFileTree(dirPath, maxDepth = 3, currentDepth = 0, showHidden =
     });
 }
 
-const PORT = process.env.PORT || 3001;
+const SERVER_PORT = process.env.SERVER_PORT || 3001;
 const HOST = process.env.HOST || '0.0.0.0';
-// Show localhost in URL when binding to all interfaces (0.0.0.0 isn't a connectable address)
-const DISPLAY_HOST = HOST === '0.0.0.0' ? 'localhost' : HOST;
+const DISPLAY_HOST = getConnectableHost(HOST);
+const VITE_PORT = process.env.VITE_PORT || 5173;
 
 // Initialize database and start server
 async function startServer() {
@@ -2500,27 +2388,32 @@ async function startServer() {
         // Initialize authentication database
         await initializeDatabase();
 
+        // Configure Web Push (VAPID keys)
+        configureWebPush();
+
         // Check if running in production mode (dist folder exists)
-        const distIndexPath = path.join(__dirname, '../dist/index.html');
+        const distIndexPath = path.join(APP_ROOT, 'dist', 'index.html');
         const isProduction = fs.existsSync(distIndexPath);
 
         // Log Claude implementation mode
         console.log(`${c.info('[INFO]')} Using Claude Agents SDK for Claude integration`);
-        console.log(`${c.info('[INFO]')} Running in ${c.bright(isProduction ? 'PRODUCTION' : 'DEVELOPMENT')} mode`);
+        console.log('');
 
-        if (!isProduction) {
-            console.log(`${c.warn('[WARN]')} Note: Requests will be proxied to Vite dev server at ${c.dim('http://localhost:' + (process.env.VITE_PORT || 5173))}`);
+        if (isProduction) {
+            console.log(`${c.info('[INFO]')} To run in production mode, go to http://${DISPLAY_HOST}:${SERVER_PORT}`);            
         }
 
-        server.listen(PORT, HOST, async () => {
-            const appInstallPath = path.join(__dirname, '..');
+        console.log(`${c.info('[INFO]')} To run in development mode with hot-module replacement, go to http://${DISPLAY_HOST}:${VITE_PORT}`);
+   
+        server.listen(SERVER_PORT, HOST, async () => {
+            const appInstallPath = APP_ROOT;
 
             console.log('');
             console.log(c.dim('═'.repeat(63)));
-            console.log(`  ${c.bright('Claude Code UI Server - Ready')}`);
+            console.log(`  ${c.bright('CloudCLI Server - Ready')}`);
             console.log(c.dim('═'.repeat(63)));
             console.log('');
-            console.log(`${c.info('[INFO]')} Server URL:  ${c.bright('http://' + DISPLAY_HOST + ':' + PORT)}`);
+            console.log(`${c.info('[INFO]')} Server URL:  ${c.bright('http://' + DISPLAY_HOST + ':' + SERVER_PORT)}`);
             console.log(`${c.info('[INFO]')} Installed at: ${c.dim(appInstallPath)}`);
             console.log(`${c.tip('[TIP]')}  Run "cloudcli status" for full configuration details`);
             console.log('');

server/load-env.js

@@ -2,14 +2,15 @@
 import fs from 'fs';
 import os from 'os';
 import path from 'path';
-import { fileURLToPath } from 'url';
-import { dirname } from 'path';
+import { findAppRoot, getModuleDir } from './utils/runtime-paths.js';
 
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
+const __dirname = getModuleDir(import.meta.url);
+// Resolve the repo/app root via the nearest /server folder so this file keeps finding the
+// same top-level .env file from both /server/load-env.js and /dist-server/server/load-env.js.
+const APP_ROOT = findAppRoot(__dirname);
 
 try {
-  const envPath = path.join(__dirname, '../.env');
+  const envPath = path.join(APP_ROOT, '.env');
   const envFile = fs.readFileSync(envPath, 'utf8');
   envFile.split('\n').forEach(line => {
     const trimmedLine = line.trim();
@@ -24,6 +25,10 @@ try {
   console.log('No .env file found or error reading it:', e.message);
 }
 
+// Keep the default database in a stable user-level location so rebuilding dist-server
+// never changes where the backend stores auth.db when DATABASE_PATH is not set explicitly.
+const DEFAULT_DATABASE_PATH = path.join(os.homedir(), '.cloudcli', 'auth.db');
+
 if (!process.env.DATABASE_PATH) {
-  process.env.DATABASE_PATH = path.join(os.homedir(), '.cloudcli', 'auth.db');
+  process.env.DATABASE_PATH = DEFAULT_DATABASE_PATH;
 }

server/middleware/auth.js

@@ -95,7 +95,7 @@ const authenticateWebSocket = (token) => {
     try {
       const user = userDb.getFirstUser();
       if (user) {
-        return { userId: user.id, username: user.username };
+        return { id: user.id, userId: user.id, username: user.username };
       }
       return null;
     } catch (error) {
@@ -129,4 +129,4 @@ export {
   generateToken,
   authenticateWebSocket,
   JWT_SECRET
-};
+};

server/modules/providers/list/claude/claude-auth.provider.ts

@@ -0,0 +1,123 @@
+import { readFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+
+import spawn from 'cross-spawn';
+
+import type { IProviderAuth } from '@/shared/interfaces.js';
+import type { ProviderAuthStatus } from '@/shared/types.js';
+import { readObjectRecord, readOptionalString } from '@/shared/utils.js';
+
+type ClaudeCredentialsStatus = {
+  authenticated: boolean;
+  email: string | null;
+  method: string | null;
+  error?: string;
+};
+
+export class ClaudeProviderAuth implements IProviderAuth {
+  /**
+   * Checks whether the Claude Code CLI is available on this host.
+   */
+  private checkInstalled(): boolean {
+      const cliPath = process.env.CLAUDE_CLI_PATH || 'claude';
+      try {
+        spawn.sync(cliPath, ['--version'], { stdio: 'ignore', timeout: 5000 });
+        return true;
+      } catch {
+        return false;
+      }
+  }
+
+  /**
+   * Returns Claude installation and credential status using Claude Code's auth priority.
+   */
+  async getStatus(): Promise<ProviderAuthStatus> {
+    const installed = this.checkInstalled();
+
+    if (!installed) {
+      return {
+        installed,
+        provider: 'claude',
+        authenticated: false,
+        email: null,
+        method: null,
+        error: 'Claude Code CLI is not installed',
+      };
+    }
+
+    const credentials = await this.checkCredentials();
+
+    return {
+      installed,
+      provider: 'claude',
+      authenticated: credentials.authenticated,
+      email: credentials.authenticated ? credentials.email || 'Authenticated' : credentials.email,
+      method: credentials.method,
+      error: credentials.authenticated ? undefined : credentials.error || 'Not authenticated',
+    };
+  }
+
+  /**
+   * Reads Claude settings env values that the CLI can use even when the server process env is empty.
+   */
+  private async loadSettingsEnv(): Promise<Record<string, unknown>> {
+    try {
+      const settingsPath = path.join(os.homedir(), '.claude', 'settings.json');
+      const content = await readFile(settingsPath, 'utf8');
+      const settings = readObjectRecord(JSON.parse(content));
+      return readObjectRecord(settings?.env) ?? {};
+    } catch {
+      return {};
+    }
+  }
+
+  /**
+   * Checks Claude credentials in the same priority order used by Claude Code.
+   */
+  private async checkCredentials(): Promise<ClaudeCredentialsStatus> {
+    if (process.env.ANTHROPIC_API_KEY?.trim()) {
+      return { authenticated: true, email: 'API Key Auth', method: 'api_key' };
+    }
+
+    const settingsEnv = await this.loadSettingsEnv();
+    if (readOptionalString(settingsEnv.ANTHROPIC_API_KEY)) {
+      return { authenticated: true, email: 'API Key Auth', method: 'api_key' };
+    }
+
+    if (readOptionalString(settingsEnv.ANTHROPIC_AUTH_TOKEN)) {
+      return { authenticated: true, email: 'Configured via settings.json', method: 'api_key' };
+    }
+
+    try {
+      const credPath = path.join(os.homedir(), '.claude', '.credentials.json');
+      const content = await readFile(credPath, 'utf8');
+      const creds = readObjectRecord(JSON.parse(content)) ?? {};
+      const oauth = readObjectRecord(creds.claudeAiOauth);
+      const accessToken = readOptionalString(oauth?.accessToken);
+
+      if (accessToken) {
+        const expiresAt = typeof oauth?.expiresAt === 'number' ? oauth.expiresAt : undefined;
+        const email = readOptionalString(creds.email) ?? readOptionalString(creds.user) ?? null;
+        if (!expiresAt || Date.now() < expiresAt) {
+          return {
+            authenticated: true,
+            email,
+            method: 'credentials_file',
+          };
+        }
+
+        return {
+          authenticated: false,
+          email,
+          method: 'credentials_file',
+          error: 'OAuth token has expired. Please re-authenticate with claude login',
+        };
+      }
+
+      return { authenticated: false, email: null, method: null };
+    } catch {
+      return { authenticated: false, email: null, method: null };
+    }
+  }
+}

server/modules/providers/list/claude/claude-mcp.provider.ts

@@ -0,0 +1,135 @@
+import os from 'node:os';
+import path from 'node:path';
+
+import { McpProvider } from '@/modules/providers/shared/mcp/mcp.provider.js';
+import type { McpScope, ProviderMcpServer, UpsertProviderMcpServerInput } from '@/shared/types.js';
+import {
+  AppError,
+  readJsonConfig,
+  readObjectRecord,
+  readOptionalString,
+  readStringArray,
+  readStringRecord,
+  writeJsonConfig,
+} from '@/shared/utils.js';
+
+export class ClaudeMcpProvider extends McpProvider {
+  constructor() {
+    super('claude', ['user', 'local', 'project'], ['stdio', 'http', 'sse']);
+  }
+
+  protected async readScopedServers(scope: McpScope, workspacePath: string): Promise<Record<string, unknown>> {
+    if (scope === 'project') {
+      const filePath = path.join(workspacePath, '.mcp.json');
+      const config = await readJsonConfig(filePath);
+      return readObjectRecord(config.mcpServers) ?? {};
+    }
+
+    const filePath = path.join(os.homedir(), '.claude.json');
+    const config = await readJsonConfig(filePath);
+    if (scope === 'user') {
+      return readObjectRecord(config.mcpServers) ?? {};
+    }
+
+    const projects = readObjectRecord(config.projects) ?? {};
+    const projectConfig = readObjectRecord(projects[workspacePath]) ?? {};
+    return readObjectRecord(projectConfig.mcpServers) ?? {};
+  }
+
+  protected async writeScopedServers(
+    scope: McpScope,
+    workspacePath: string,
+    servers: Record<string, unknown>,
+  ): Promise<void> {
+    if (scope === 'project') {
+      const filePath = path.join(workspacePath, '.mcp.json');
+      const config = await readJsonConfig(filePath);
+      config.mcpServers = servers;
+      await writeJsonConfig(filePath, config);
+      return;
+    }
+
+    const filePath = path.join(os.homedir(), '.claude.json');
+    const config = await readJsonConfig(filePath);
+    if (scope === 'user') {
+      config.mcpServers = servers;
+      await writeJsonConfig(filePath, config);
+      return;
+    }
+
+    const projects = readObjectRecord(config.projects) ?? {};
+    const projectConfig = readObjectRecord(projects[workspacePath]) ?? {};
+    projectConfig.mcpServers = servers;
+    projects[workspacePath] = projectConfig;
+    config.projects = projects;
+    await writeJsonConfig(filePath, config);
+  }
+
+  protected buildServerConfig(input: UpsertProviderMcpServerInput): Record<string, unknown> {
+    if (input.transport === 'stdio') {
+      if (!input.command?.trim()) {
+        throw new AppError('command is required for stdio MCP servers.', {
+          code: 'MCP_COMMAND_REQUIRED',
+          statusCode: 400,
+        });
+      }
+
+      return {
+        type: 'stdio',
+        command: input.command,
+        args: input.args ?? [],
+        env: input.env ?? {},
+      };
+    }
+
+    if (!input.url?.trim()) {
+      throw new AppError('url is required for http/sse MCP servers.', {
+        code: 'MCP_URL_REQUIRED',
+        statusCode: 400,
+      });
+    }
+
+    return {
+      type: input.transport,
+      url: input.url,
+      headers: input.headers ?? {},
+    };
+  }
+
+  protected normalizeServerConfig(
+    scope: McpScope,
+    name: string,
+    rawConfig: unknown,
+  ): ProviderMcpServer | null {
+    if (!rawConfig || typeof rawConfig !== 'object') {
+      return null;
+    }
+
+    const config = rawConfig as Record<string, unknown>;
+    if (typeof config.command === 'string') {
+      return {
+        provider: 'claude',
+        name,
+        scope,
+        transport: 'stdio',
+        command: config.command,
+        args: readStringArray(config.args),
+        env: readStringRecord(config.env),
+      };
+    }
+
+    if (typeof config.url === 'string') {
+      const transport = readOptionalString(config.type) === 'sse' ? 'sse' : 'http';
+      return {
+        provider: 'claude',
+        name,
+        scope,
+        transport,
+        url: config.url,
+        headers: readStringRecord(config.headers),
+      };
+    }
+
+    return null;
+  }
+}

server/modules/providers/list/claude/claude.provider.ts

@@ -0,0 +1,321 @@
+import { getSessionMessages } from '@/projects.js';
+import { AbstractProvider } from '@/modules/providers/shared/base/abstract.provider.js';
+import { ClaudeProviderAuth } from '@/modules/providers/list/claude/claude-auth.provider.js';
+import { ClaudeMcpProvider } from '@/modules/providers/list/claude/claude-mcp.provider.js';
+import type { IProviderAuth } from '@/shared/interfaces.js';
+import type { FetchHistoryOptions, FetchHistoryResult, NormalizedMessage } from '@/shared/types.js';
+import { createNormalizedMessage, generateMessageId, readObjectRecord } from '@/shared/utils.js';
+
+const PROVIDER = 'claude';
+
+type RawProviderMessage = Record<string, any>;
+
+type ClaudeToolResult = {
+  content: unknown;
+  isError: boolean;
+  subagentTools?: unknown;
+  toolUseResult?: unknown;
+};
+
+type ClaudeHistoryResult =
+  | RawProviderMessage[]
+  | {
+      messages?: RawProviderMessage[];
+      total?: number;
+      hasMore?: boolean;
+    };
+
+const loadClaudeSessionMessages = getSessionMessages as unknown as (
+  projectName: string,
+  sessionId: string,
+  limit: number | null,
+  offset: number,
+) => Promise<ClaudeHistoryResult>;
+
+/**
+ * Claude writes internal command and system reminder entries into history.
+ * Those are useful for the CLI but should not appear in the user-facing chat.
+ */
+const INTERNAL_CONTENT_PREFIXES = [
+  '<command-name>',
+  '<command-message>',
+  '<command-args>',
+  '<local-command-stdout>',
+  '<system-reminder>',
+  'Caveat:',
+  'This session is being continued from a previous',
+  '[Request interrupted',
+] as const;
+
+function isInternalContent(content: string): boolean {
+  return INTERNAL_CONTENT_PREFIXES.some((prefix) => content.startsWith(prefix));
+}
+
+function readRawProviderMessage(raw: unknown): RawProviderMessage | null {
+  return readObjectRecord(raw) as RawProviderMessage | null;
+}
+
+export class ClaudeProvider extends AbstractProvider {
+  readonly mcp = new ClaudeMcpProvider();
+  readonly auth: IProviderAuth = new ClaudeProviderAuth();
+
+  constructor() {
+    super('claude');
+  }
+
+  /**
+   * Normalizes one Claude JSONL entry or live SDK stream event into the shared
+   * message shape consumed by REST and WebSocket clients.
+   */
+  normalizeMessage(rawMessage: unknown, sessionId: string | null): NormalizedMessage[] {
+    const raw = readRawProviderMessage(rawMessage);
+    if (!raw) {
+      return [];
+    }
+
+    if (raw.type === 'content_block_delta' && raw.delta?.text) {
+      return [createNormalizedMessage({ kind: 'stream_delta', content: raw.delta.text, sessionId, provider: PROVIDER })];
+    }
+    if (raw.type === 'content_block_stop') {
+      return [createNormalizedMessage({ kind: 'stream_end', sessionId, provider: PROVIDER })];
+    }
+
+    const messages: NormalizedMessage[] = [];
+    const ts = raw.timestamp || new Date().toISOString();
+    const baseId = raw.uuid || generateMessageId('claude');
+
+    if (raw.message?.role === 'user' && raw.message?.content) {
+      if (Array.isArray(raw.message.content)) {
+        for (const part of raw.message.content) {
+          if (part.type === 'tool_result') {
+            messages.push(createNormalizedMessage({
+              id: `${baseId}_tr_${part.tool_use_id}`,
+              sessionId,
+              timestamp: ts,
+              provider: PROVIDER,
+              kind: 'tool_result',
+              toolId: part.tool_use_id,
+              content: typeof part.content === 'string' ? part.content : JSON.stringify(part.content),
+              isError: Boolean(part.is_error),
+              subagentTools: raw.subagentTools,
+              toolUseResult: raw.toolUseResult,
+            }));
+          } else if (part.type === 'text') {
+            const text = part.text || '';
+            if (text && !isInternalContent(text)) {
+              messages.push(createNormalizedMessage({
+                id: `${baseId}_text`,
+                sessionId,
+                timestamp: ts,
+                provider: PROVIDER,
+                kind: 'text',
+                role: 'user',
+                content: text,
+              }));
+            }
+          }
+        }
+
+        if (messages.length === 0) {
+          const textParts = raw.message.content
+            .filter((part: RawProviderMessage) => part.type === 'text')
+            .map((part: RawProviderMessage) => part.text)
+            .filter(Boolean)
+            .join('\n');
+          if (textParts && !isInternalContent(textParts)) {
+            messages.push(createNormalizedMessage({
+              id: `${baseId}_text`,
+              sessionId,
+              timestamp: ts,
+              provider: PROVIDER,
+              kind: 'text',
+              role: 'user',
+              content: textParts,
+            }));
+          }
+        }
+      } else if (typeof raw.message.content === 'string') {
+        const text = raw.message.content;
+        if (text && !isInternalContent(text)) {
+          messages.push(createNormalizedMessage({
+            id: baseId,
+            sessionId,
+            timestamp: ts,
+            provider: PROVIDER,
+            kind: 'text',
+            role: 'user',
+            content: text,
+          }));
+        }
+      }
+      return messages;
+    }
+
+    if (raw.type === 'thinking' && raw.message?.content) {
+      messages.push(createNormalizedMessage({
+        id: baseId,
+        sessionId,
+        timestamp: ts,
+        provider: PROVIDER,
+        kind: 'thinking',
+        content: raw.message.content,
+      }));
+      return messages;
+    }
+
+    if (raw.type === 'tool_use' && raw.toolName) {
+      messages.push(createNormalizedMessage({
+        id: baseId,
+        sessionId,
+        timestamp: ts,
+        provider: PROVIDER,
+        kind: 'tool_use',
+        toolName: raw.toolName,
+        toolInput: raw.toolInput,
+        toolId: raw.toolCallId || baseId,
+      }));
+      return messages;
+    }
+
+    if (raw.type === 'tool_result') {
+      messages.push(createNormalizedMessage({
+        id: baseId,
+        sessionId,
+        timestamp: ts,
+        provider: PROVIDER,
+        kind: 'tool_result',
+        toolId: raw.toolCallId || '',
+        content: raw.output || '',
+        isError: false,
+      }));
+      return messages;
+    }
+
+    if (raw.message?.role === 'assistant' && raw.message?.content) {
+      if (Array.isArray(raw.message.content)) {
+        let partIndex = 0;
+        for (const part of raw.message.content) {
+          if (part.type === 'text' && part.text) {
+            messages.push(createNormalizedMessage({
+              id: `${baseId}_${partIndex}`,
+              sessionId,
+              timestamp: ts,
+              provider: PROVIDER,
+              kind: 'text',
+              role: 'assistant',
+              content: part.text,
+            }));
+          } else if (part.type === 'tool_use') {
+            messages.push(createNormalizedMessage({
+              id: `${baseId}_${partIndex}`,
+              sessionId,
+              timestamp: ts,
+              provider: PROVIDER,
+              kind: 'tool_use',
+              toolName: part.name,
+              toolInput: part.input,
+              toolId: part.id,
+            }));
+          } else if (part.type === 'thinking' && part.thinking) {
+            messages.push(createNormalizedMessage({
+              id: `${baseId}_${partIndex}`,
+              sessionId,
+              timestamp: ts,
+              provider: PROVIDER,
+              kind: 'thinking',
+              content: part.thinking,
+            }));
+          }
+          partIndex++;
+        }
+      } else if (typeof raw.message.content === 'string') {
+        messages.push(createNormalizedMessage({
+          id: baseId,
+          sessionId,
+          timestamp: ts,
+          provider: PROVIDER,
+          kind: 'text',
+          role: 'assistant',
+          content: raw.message.content,
+        }));
+      }
+      return messages;
+    }
+
+    return messages;
+  }
+
+  /**
+   * Loads Claude JSONL history for a project/session and returns normalized
+   * messages, preserving the existing pagination behavior from projects.js.
+   */
+  async fetchHistory(
+    sessionId: string,
+    options: FetchHistoryOptions = {},
+  ): Promise<FetchHistoryResult> {
+    const { projectName, limit = null, offset = 0 } = options;
+    if (!projectName) {
+      return { messages: [], total: 0, hasMore: false, offset: 0, limit: null };
+    }
+
+    let result: ClaudeHistoryResult;
+    try {
+      result = await loadClaudeSessionMessages(projectName, sessionId, limit, offset);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      console.warn(`[ClaudeProvider] Failed to load session ${sessionId}:`, message);
+      return { messages: [], total: 0, hasMore: false, offset: 0, limit: null };
+    }
+
+    const rawMessages = Array.isArray(result) ? result : (result.messages || []);
+    const total = Array.isArray(result) ? rawMessages.length : (result.total || 0);
+    const hasMore = Array.isArray(result) ? false : Boolean(result.hasMore);
+
+    const toolResultMap = new Map<string, ClaudeToolResult>();
+    for (const raw of rawMessages) {
+      if (raw.message?.role === 'user' && Array.isArray(raw.message?.content)) {
+        for (const part of raw.message.content) {
+          if (part.type === 'tool_result' && part.tool_use_id) {
+            toolResultMap.set(part.tool_use_id, {
+              content: part.content,
+              isError: Boolean(part.is_error),
+              subagentTools: raw.subagentTools,
+              toolUseResult: raw.toolUseResult,
+            });
+          }
+        }
+      }
+    }
+
+    const normalized: NormalizedMessage[] = [];
+    for (const raw of rawMessages) {
+      normalized.push(...this.normalizeMessage(raw, sessionId));
+    }
+
+    for (const msg of normalized) {
+      if (msg.kind === 'tool_use' && msg.toolId && toolResultMap.has(msg.toolId)) {
+        const toolResult = toolResultMap.get(msg.toolId);
+        if (!toolResult) {
+          continue;
+        }
+
+        msg.toolResult = {
+          content: typeof toolResult.content === 'string'
+            ? toolResult.content
+            : JSON.stringify(toolResult.content),
+          isError: toolResult.isError,
+          toolUseResult: toolResult.toolUseResult,
+        };
+        msg.subagentTools = toolResult.subagentTools;
+      }
+    }
+
+    return {
+      messages: normalized,
+      total,
+      hasMore,
+      offset,
+      limit,
+    };
+  }
+}

server/modules/providers/list/codex/codex-auth.provider.ts

@@ -0,0 +1,100 @@
+import { readFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+
+import spawn from 'cross-spawn';
+
+import type { IProviderAuth } from '@/shared/interfaces.js';
+import type { ProviderAuthStatus } from '@/shared/types.js';
+import { readObjectRecord, readOptionalString } from '@/shared/utils.js';
+
+type CodexCredentialsStatus = {
+  authenticated: boolean;
+  email: string | null;
+  method: string | null;
+  error?: string;
+};
+
+export class CodexProviderAuth implements IProviderAuth {
+  /**
+   * Checks whether Codex is available to the server runtime.
+   */
+  private checkInstalled(): boolean {
+    try {
+      spawn.sync('codex', ['--version'], { stdio: 'ignore', timeout: 5000 });
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Returns Codex SDK availability and credential status.
+   */
+  async getStatus(): Promise<ProviderAuthStatus> {
+    const installed = this.checkInstalled();
+    const credentials = await this.checkCredentials();
+
+    return {
+      installed,
+      provider: 'codex',
+      authenticated: credentials.authenticated,
+      email: credentials.email,
+      method: credentials.method,
+      error: credentials.authenticated ? undefined : credentials.error || 'Not authenticated',
+    };
+  }
+
+  /**
+   * Reads Codex auth.json and checks OAuth tokens or an API key fallback.
+   */
+  private async checkCredentials(): Promise<CodexCredentialsStatus> {
+    try {
+      const authPath = path.join(os.homedir(), '.codex', 'auth.json');
+      const content = await readFile(authPath, 'utf8');
+      const auth = readObjectRecord(JSON.parse(content)) ?? {};
+      const tokens = readObjectRecord(auth.tokens) ?? {};
+      const idToken = readOptionalString(tokens.id_token);
+      const accessToken = readOptionalString(tokens.access_token);
+
+      if (idToken || accessToken) {
+        return {
+          authenticated: true,
+          email: idToken ? this.readEmailFromIdToken(idToken) : 'Authenticated',
+          method: 'credentials_file',
+        };
+      }
+
+      if (readOptionalString(auth.OPENAI_API_KEY)) {
+        return { authenticated: true, email: 'API Key Auth', method: 'api_key' };
+      }
+
+      return { authenticated: false, email: null, method: null, error: 'No valid tokens found' };
+    } catch (error) {
+      const code = (error as NodeJS.ErrnoException).code;
+      return {
+        authenticated: false,
+        email: null,
+        method: null,
+        error: code === 'ENOENT' ? 'Codex not configured' : error instanceof Error ? error.message : 'Failed to read Codex auth',
+      };
+    }
+  }
+
+  /**
+   * Extracts the user email from a Codex id_token when a readable JWT payload exists.
+   */
+  private readEmailFromIdToken(idToken: string): string {
+    try {
+      const parts = idToken.split('.');
+      if (parts.length >= 2) {
+        const payload = readObjectRecord(JSON.parse(Buffer.from(parts[1], 'base64url').toString('utf8')));
+        return readOptionalString(payload?.email) ?? readOptionalString(payload?.user) ?? 'Authenticated';
+      }
+    } catch {
+      // Fall back to a generic authenticated marker if the token payload is not readable.
+    }
+
+    return 'Authenticated';
+  }
+}

server/modules/providers/list/codex/codex-mcp.provider.ts

@@ -0,0 +1,135 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+
+import TOML from '@iarna/toml';
+
+import { McpProvider } from '@/modules/providers/shared/mcp/mcp.provider.js';
+import type { McpScope, ProviderMcpServer, UpsertProviderMcpServerInput } from '@/shared/types.js';
+import {
+  AppError,
+  readObjectRecord,
+  readOptionalString,
+  readStringArray,
+  readStringRecord,
+} from '@/shared/utils.js';
+
+const readTomlConfig = async (filePath: string): Promise<Record<string, unknown>> => {
+  try {
+    const content = await readFile(filePath, 'utf8');
+    const parsed = TOML.parse(content) as Record<string, unknown>;
+    return readObjectRecord(parsed) ?? {};
+  } catch (error) {
+    const code = (error as NodeJS.ErrnoException).code;
+    if (code === 'ENOENT') {
+      return {};
+    }
+    throw error;
+  }
+};
+
+const writeTomlConfig = async (filePath: string, data: Record<string, unknown>): Promise<void> => {
+  await mkdir(path.dirname(filePath), { recursive: true });
+  const toml = TOML.stringify(data as never);
+  await writeFile(filePath, toml, 'utf8');
+};
+
+export class CodexMcpProvider extends McpProvider {
+  constructor() {
+    super('codex', ['user', 'project'], ['stdio', 'http']);
+  }
+
+  protected async readScopedServers(scope: McpScope, workspacePath: string): Promise<Record<string, unknown>> {
+    const filePath = scope === 'user'
+      ? path.join(os.homedir(), '.codex', 'config.toml')
+      : path.join(workspacePath, '.codex', 'config.toml');
+    const config = await readTomlConfig(filePath);
+    return readObjectRecord(config.mcp_servers) ?? {};
+  }
+
+  protected async writeScopedServers(
+    scope: McpScope,
+    workspacePath: string,
+    servers: Record<string, unknown>,
+  ): Promise<void> {
+    const filePath = scope === 'user'
+      ? path.join(os.homedir(), '.codex', 'config.toml')
+      : path.join(workspacePath, '.codex', 'config.toml');
+    const config = await readTomlConfig(filePath);
+    config.mcp_servers = servers;
+    await writeTomlConfig(filePath, config);
+  }
+
+  protected buildServerConfig(input: UpsertProviderMcpServerInput): Record<string, unknown> {
+    if (input.transport === 'stdio') {
+      if (!input.command?.trim()) {
+        throw new AppError('command is required for stdio MCP servers.', {
+          code: 'MCP_COMMAND_REQUIRED',
+          statusCode: 400,
+        });
+      }
+
+      return {
+        command: input.command,
+        args: input.args ?? [],
+        env: input.env ?? {},
+        env_vars: input.envVars ?? [],
+        cwd: input.cwd,
+      };
+    }
+
+    if (!input.url?.trim()) {
+      throw new AppError('url is required for http MCP servers.', {
+        code: 'MCP_URL_REQUIRED',
+        statusCode: 400,
+      });
+    }
+
+    return {
+      url: input.url,
+      bearer_token_env_var: input.bearerTokenEnvVar,
+      http_headers: input.headers ?? {},
+      env_http_headers: input.envHttpHeaders ?? {},
+    };
+  }
+
+  protected normalizeServerConfig(
+    scope: McpScope,
+    name: string,
+    rawConfig: unknown,
+  ): ProviderMcpServer | null {
+    if (!rawConfig || typeof rawConfig !== 'object') {
+      return null;
+    }
+
+    const config = rawConfig as Record<string, unknown>;
+    if (typeof config.command === 'string') {
+      return {
+        provider: 'codex',
+        name,
+        scope,
+        transport: 'stdio',
+        command: config.command,
+        args: readStringArray(config.args),
+        env: readStringRecord(config.env),
+        cwd: readOptionalString(config.cwd),
+        envVars: readStringArray(config.env_vars),
+      };
+    }
+
+    if (typeof config.url === 'string') {
+      return {
+        provider: 'codex',
+        name,
+        scope,
+        transport: 'http',
+        url: config.url,
+        headers: readStringRecord(config.http_headers),
+        bearerTokenEnvVar: readOptionalString(config.bearer_token_env_var),
+        envHttpHeaders: readStringRecord(config.env_http_headers),
+      };
+    }
+
+    return null;
+  }
+}

server/modules/providers/list/codex/codex.provider.ts

@@ -0,0 +1,335 @@
+import { getCodexSessionMessages } from '@/projects.js';
+import { AbstractProvider } from '@/modules/providers/shared/base/abstract.provider.js';
+import { CodexProviderAuth } from '@/modules/providers/list/codex/codex-auth.provider.js';
+import { CodexMcpProvider } from '@/modules/providers/list/codex/codex-mcp.provider.js';
+import type { IProviderAuth } from '@/shared/interfaces.js';
+import type { FetchHistoryOptions, FetchHistoryResult, NormalizedMessage } from '@/shared/types.js';
+import { createNormalizedMessage, generateMessageId, readObjectRecord } from '@/shared/utils.js';
+
+const PROVIDER = 'codex';
+
+type RawProviderMessage = Record<string, any>;
+
+type CodexHistoryResult =
+  | RawProviderMessage[]
+  | {
+      messages?: RawProviderMessage[];
+      total?: number;
+      hasMore?: boolean;
+      tokenUsage?: unknown;
+    };
+
+const loadCodexSessionMessages = getCodexSessionMessages as unknown as (
+  sessionId: string,
+  limit: number | null,
+  offset: number,
+) => Promise<CodexHistoryResult>;
+
+function readRawProviderMessage(raw: unknown): RawProviderMessage | null {
+  return readObjectRecord(raw) as RawProviderMessage | null;
+}
+
+export class CodexProvider extends AbstractProvider {
+  readonly mcp = new CodexMcpProvider();
+  readonly auth: IProviderAuth = new CodexProviderAuth();
+
+  constructor() {
+    super('codex');
+  }
+
+  /**
+   * Normalizes a persisted Codex JSONL entry.
+   *
+   * Live Codex SDK events are transformed before they reach normalizeMessage(),
+   * while history entries already use a compact message/tool shape from projects.js.
+   */
+  private normalizeHistoryEntry(raw: RawProviderMessage, sessionId: string | null): NormalizedMessage[] {
+    const ts = raw.timestamp || new Date().toISOString();
+    const baseId = raw.uuid || generateMessageId('codex');
+
+    if (raw.message?.role === 'user') {
+      const content = typeof raw.message.content === 'string'
+        ? raw.message.content
+        : Array.isArray(raw.message.content)
+          ? raw.message.content
+              .map((part: string | RawProviderMessage) => typeof part === 'string' ? part : part?.text || '')
+              .filter(Boolean)
+              .join('\n')
+          : String(raw.message.content || '');
+      if (!content.trim()) {
+        return [];
+      }
+      return [createNormalizedMessage({
+        id: baseId,
+        sessionId,
+        timestamp: ts,
+        provider: PROVIDER,
+        kind: 'text',
+        role: 'user',
+        content,
+      })];
+    }
+
+    if (raw.message?.role === 'assistant') {
+      const content = typeof raw.message.content === 'string'
+        ? raw.message.content
+        : Array.isArray(raw.message.content)
+          ? raw.message.content
+              .map((part: string | RawProviderMessage) => typeof part === 'string' ? part : part?.text || '')
+              .filter(Boolean)
+              .join('\n')
+          : '';
+      if (!content.trim()) {
+        return [];
+      }
+      return [createNormalizedMessage({
+        id: baseId,
+        sessionId,
+        timestamp: ts,
+        provider: PROVIDER,
+        kind: 'text',
+        role: 'assistant',
+        content,
+      })];
+    }
+
+    if (raw.type === 'thinking' || raw.isReasoning) {
+      return [createNormalizedMessage({
+        id: baseId,
+        sessionId,
+        timestamp: ts,
+        provider: PROVIDER,
+        kind: 'thinking',
+        content: raw.message?.content || '',
+      })];
+    }
+
+    if (raw.type === 'tool_use' || raw.toolName) {
+      return [createNormalizedMessage({
+        id: baseId,
+        sessionId,
+        timestamp: ts,
+        provider: PROVIDER,
+        kind: 'tool_use',
+        toolName: raw.toolName || 'Unknown',
+        toolInput: raw.toolInput,
+        toolId: raw.toolCallId || baseId,
+      })];
+    }
+
+    if (raw.type === 'tool_result') {
+      return [createNormalizedMessage({
+        id: baseId,
+        sessionId,
+        timestamp: ts,
+        provider: PROVIDER,
+        kind: 'tool_result',
+        toolId: raw.toolCallId || '',
+        content: raw.output || '',
+        isError: Boolean(raw.isError),
+      })];
+    }
+
+    return [];
+  }
+
+  /**
+   * Normalizes either a Codex history entry or a transformed live SDK event.
+   */
+  normalizeMessage(rawMessage: unknown, sessionId: string | null): NormalizedMessage[] {
+    const raw = readRawProviderMessage(rawMessage);
+    if (!raw) {
+      return [];
+    }
+
+    if (raw.message?.role) {
+      return this.normalizeHistoryEntry(raw, sessionId);
+    }
+
+    const ts = raw.timestamp || new Date().toISOString();
+    const baseId = raw.uuid || generateMessageId('codex');
+
+    if (raw.type === 'item') {
+      switch (raw.itemType) {
+        case 'agent_message':
+          return [createNormalizedMessage({
+            id: baseId,
+            sessionId,
+            timestamp: ts,
+            provider: PROVIDER,
+            kind: 'text',
+            role: 'assistant',
+            content: raw.message?.content || '',
+          })];
+        case 'reasoning':
+          return [createNormalizedMessage({
+            id: baseId,
+            sessionId,
+            timestamp: ts,
+            provider: PROVIDER,
+            kind: 'thinking',
+            content: raw.message?.content || '',
+          })];
+        case 'command_execution':
+          return [createNormalizedMessage({
+            id: baseId,
+            sessionId,
+            timestamp: ts,
+            provider: PROVIDER,
+            kind: 'tool_use',
+            toolName: 'Bash',
+            toolInput: { command: raw.command },
+            toolId: baseId,
+            output: raw.output,
+            exitCode: raw.exitCode,
+            status: raw.status,
+          })];
+        case 'file_change':
+          return [createNormalizedMessage({
+            id: baseId,
+            sessionId,
+            timestamp: ts,
+            provider: PROVIDER,
+            kind: 'tool_use',
+            toolName: 'FileChanges',
+            toolInput: raw.changes,
+            toolId: baseId,
+            status: raw.status,
+          })];
+        case 'mcp_tool_call':
+          return [createNormalizedMessage({
+            id: baseId,
+            sessionId,
+            timestamp: ts,
+            provider: PROVIDER,
+            kind: 'tool_use',
+            toolName: raw.tool || 'MCP',
+            toolInput: raw.arguments,
+            toolId: baseId,
+            server: raw.server,
+            result: raw.result,
+            error: raw.error,
+            status: raw.status,
+          })];
+        case 'web_search':
+          return [createNormalizedMessage({
+            id: baseId,
+            sessionId,
+            timestamp: ts,
+            provider: PROVIDER,
+            kind: 'tool_use',
+            toolName: 'WebSearch',
+            toolInput: { query: raw.query },
+            toolId: baseId,
+          })];
+        case 'todo_list':
+          return [createNormalizedMessage({
+            id: baseId,
+            sessionId,
+            timestamp: ts,
+            provider: PROVIDER,
+            kind: 'tool_use',
+            toolName: 'TodoList',
+            toolInput: { items: raw.items },
+            toolId: baseId,
+          })];
+        case 'error':
+          return [createNormalizedMessage({
+            id: baseId,
+            sessionId,
+            timestamp: ts,
+            provider: PROVIDER,
+            kind: 'error',
+            content: raw.message?.content || 'Unknown error',
+          })];
+        default:
+          return [createNormalizedMessage({
+            id: baseId,
+            sessionId,
+            timestamp: ts,
+            provider: PROVIDER,
+            kind: 'tool_use',
+            toolName: raw.itemType || 'Unknown',
+            toolInput: raw.item || raw,
+            toolId: baseId,
+          })];
+      }
+    }
+
+    if (raw.type === 'turn_complete') {
+      return [createNormalizedMessage({
+        id: baseId,
+        sessionId,
+        timestamp: ts,
+        provider: PROVIDER,
+        kind: 'complete',
+      })];
+    }
+    if (raw.type === 'turn_failed') {
+      return [createNormalizedMessage({
+        id: baseId,
+        sessionId,
+        timestamp: ts,
+        provider: PROVIDER,
+        kind: 'error',
+        content: raw.error?.message || 'Turn failed',
+      })];
+    }
+
+    return [];
+  }
+
+  /**
+   * Loads Codex JSONL history and keeps token usage metadata when projects.js
+   * provides it.
+   */
+  async fetchHistory(
+    sessionId: string,
+    options: FetchHistoryOptions = {},
+  ): Promise<FetchHistoryResult> {
+    const { limit = null, offset = 0 } = options;
+
+    let result: CodexHistoryResult;
+    try {
+      result = await loadCodexSessionMessages(sessionId, limit, offset);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      console.warn(`[CodexProvider] Failed to load session ${sessionId}:`, message);
+      return { messages: [], total: 0, hasMore: false, offset: 0, limit: null };
+    }
+
+    const rawMessages = Array.isArray(result) ? result : (result.messages || []);
+    const total = Array.isArray(result) ? rawMessages.length : (result.total || 0);
+    const hasMore = Array.isArray(result) ? false : Boolean(result.hasMore);
+    const tokenUsage = Array.isArray(result) ? undefined : result.tokenUsage;
+
+    const normalized: NormalizedMessage[] = [];
+    for (const raw of rawMessages) {
+      normalized.push(...this.normalizeHistoryEntry(raw, sessionId));
+    }
+
+    const toolResultMap = new Map<string, NormalizedMessage>();
+    for (const msg of normalized) {
+      if (msg.kind === 'tool_result' && msg.toolId) {
+        toolResultMap.set(msg.toolId, msg);
+      }
+    }
+    for (const msg of normalized) {
+      if (msg.kind === 'tool_use' && msg.toolId && toolResultMap.has(msg.toolId)) {
+        const toolResult = toolResultMap.get(msg.toolId);
+        if (toolResult) {
+          msg.toolResult = { content: toolResult.content, isError: toolResult.isError };
+        }
+      }
+    }
+
+    return {
+      messages: normalized,
+      total,
+      hasMore,
+      offset,
+      limit,
+      tokenUsage,
+    };
+  }
+}

server/modules/providers/list/cursor/cursor-auth.provider.ts

@@ -0,0 +1,143 @@
+import spawn from 'cross-spawn';
+
+import type { IProviderAuth } from '@/shared/interfaces.js';
+import type { ProviderAuthStatus } from '@/shared/types.js';
+
+type CursorLoginStatus = {
+  authenticated: boolean;
+  email: string | null;
+  method: string | null;
+  error?: string;
+};
+
+export class CursorProviderAuth implements IProviderAuth {
+  /**
+   * Checks whether the cursor-agent CLI is available on this host.
+   */
+  private checkInstalled(): boolean {
+    try {
+      spawn.sync('cursor-agent', ['--version'], { stdio: 'ignore', timeout: 5000 });
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Returns Cursor CLI installation and login status.
+   */
+  async getStatus(): Promise<ProviderAuthStatus> {
+    const installed = this.checkInstalled();
+
+    if (!installed) {
+      return {
+        installed,
+        provider: 'cursor',
+        authenticated: false,
+        email: null,
+        method: null,
+        error: 'Cursor CLI is not installed',
+      };
+    }
+
+    const login = await this.checkCursorLogin();
+
+    return {
+      installed,
+      provider: 'cursor',
+      authenticated: login.authenticated,
+      email: login.email,
+      method: login.method,
+      error: login.authenticated ? undefined : login.error || 'Not logged in',
+    };
+  }
+
+  /**
+   * Runs cursor-agent status and parses the login marker from stdout.
+   */
+  private checkCursorLogin(): Promise<CursorLoginStatus> {
+    return new Promise((resolve) => {
+      let processCompleted = false;
+      let childProcess: ReturnType<typeof spawn> | undefined;
+
+      const timeout = setTimeout(() => {
+        if (!processCompleted) {
+          processCompleted = true;
+          childProcess?.kill();
+          resolve({
+            authenticated: false,
+            email: null,
+            method: null,
+            error: 'Command timeout',
+          });
+        }
+      }, 5000);
+
+      try {
+        childProcess = spawn('cursor-agent', ['status']);
+      } catch {
+        clearTimeout(timeout);
+        processCompleted = true;
+        resolve({
+          authenticated: false,
+          email: null,
+          method: null,
+          error: 'Cursor CLI not found or not installed',
+        });
+        return;
+      }
+
+      let stdout = '';
+      let stderr = '';
+
+      childProcess.stdout?.on('data', (data: Buffer) => {
+        stdout += data.toString();
+      });
+
+      childProcess.stderr?.on('data', (data: Buffer) => {
+        stderr += data.toString();
+      });
+
+      childProcess.on('close', (code) => {
+        if (processCompleted) {
+          return;
+        }
+        processCompleted = true;
+        clearTimeout(timeout);
+
+        if (code === 0) {
+          const emailMatch = stdout.match(/Logged in as ([a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,})/i);
+          if (emailMatch?.[1]) {
+            resolve({ authenticated: true, email: emailMatch[1], method: 'cli' });
+            return;
+          }
+
+          if (stdout.includes('Logged in')) {
+            resolve({ authenticated: true, email: 'Logged in', method: 'cli' });
+            return;
+          }
+
+          resolve({ authenticated: false, email: null, method: null, error: 'Not logged in' });
+          return;
+        }
+
+        resolve({ authenticated: false, email: null, method: null, error: stderr || 'Not logged in' });
+      });
+
+      childProcess.on('error', () => {
+        if (processCompleted) {
+          return;
+        }
+        processCompleted = true;
+        clearTimeout(timeout);
+
+        resolve({
+          authenticated: false,
+          email: null,
+          method: null,
+          error: 'Cursor CLI not found or not installed',
+        });
+      });
+    });
+  }
+}

server/modules/providers/list/cursor/cursor-mcp.provider.ts

@@ -0,0 +1,108 @@
+import os from 'node:os';
+import path from 'node:path';
+
+import { McpProvider } from '@/modules/providers/shared/mcp/mcp.provider.js';
+import type { McpScope, ProviderMcpServer, UpsertProviderMcpServerInput } from '@/shared/types.js';
+import {
+  AppError,
+  readJsonConfig,
+  readObjectRecord,
+  readOptionalString,
+  readStringArray,
+  readStringRecord,
+  writeJsonConfig,
+} from '@/shared/utils.js';
+
+export class CursorMcpProvider extends McpProvider {
+  constructor() {
+    super('cursor', ['user', 'project'], ['stdio', 'http', 'sse']);
+  }
+
+  protected async readScopedServers(scope: McpScope, workspacePath: string): Promise<Record<string, unknown>> {
+    const filePath = scope === 'user'
+      ? path.join(os.homedir(), '.cursor', 'mcp.json')
+      : path.join(workspacePath, '.cursor', 'mcp.json');
+    const config = await readJsonConfig(filePath);
+    return readObjectRecord(config.mcpServers) ?? {};
+  }
+
+  protected async writeScopedServers(
+    scope: McpScope,
+    workspacePath: string,
+    servers: Record<string, unknown>,
+  ): Promise<void> {
+    const filePath = scope === 'user'
+      ? path.join(os.homedir(), '.cursor', 'mcp.json')
+      : path.join(workspacePath, '.cursor', 'mcp.json');
+    const config = await readJsonConfig(filePath);
+    config.mcpServers = servers;
+    await writeJsonConfig(filePath, config);
+  }
+
+  protected buildServerConfig(input: UpsertProviderMcpServerInput): Record<string, unknown> {
+    if (input.transport === 'stdio') {
+      if (!input.command?.trim()) {
+        throw new AppError('command is required for stdio MCP servers.', {
+          code: 'MCP_COMMAND_REQUIRED',
+          statusCode: 400,
+        });
+      }
+
+      return {
+        command: input.command,
+        args: input.args ?? [],
+        env: input.env ?? {},
+        cwd: input.cwd,
+      };
+    }
+
+    if (!input.url?.trim()) {
+      throw new AppError('url is required for http/sse MCP servers.', {
+        code: 'MCP_URL_REQUIRED',
+        statusCode: 400,
+      });
+    }
+
+    return {
+      url: input.url,
+      headers: input.headers ?? {},
+    };
+  }
+
+  protected normalizeServerConfig(
+    scope: McpScope,
+    name: string,
+    rawConfig: unknown,
+  ): ProviderMcpServer | null {
+    if (!rawConfig || typeof rawConfig !== 'object') {
+      return null;
+    }
+
+    const config = rawConfig as Record<string, unknown>;
+    if (typeof config.command === 'string') {
+      return {
+        provider: 'cursor',
+        name,
+        scope,
+        transport: 'stdio',
+        command: config.command,
+        args: readStringArray(config.args),
+        env: readStringRecord(config.env),
+        cwd: readOptionalString(config.cwd),
+      };
+    }
+
+    if (typeof config.url === 'string') {
+      return {
+        provider: 'cursor',
+        name,
+        scope,
+        transport: 'http',
+        url: config.url,
+        headers: readStringRecord(config.headers),
+      };
+    }
+
+    return null;
+  }
+}

server/modules/providers/list/cursor/cursor.provider.ts

@@ -0,0 +1,403 @@
+import crypto from 'node:crypto';
+import os from 'node:os';
+import path from 'node:path';
+
+import { AbstractProvider } from '@/modules/providers/shared/base/abstract.provider.js';
+import { CursorProviderAuth } from '@/modules/providers/list/cursor/cursor-auth.provider.js';
+import { CursorMcpProvider } from '@/modules/providers/list/cursor/cursor-mcp.provider.js';
+import type { IProviderAuth } from '@/shared/interfaces.js';
+import type { FetchHistoryOptions, FetchHistoryResult, NormalizedMessage } from '@/shared/types.js';
+import { createNormalizedMessage, generateMessageId, readObjectRecord } from '@/shared/utils.js';
+
+const PROVIDER = 'cursor';
+
+type RawProviderMessage = Record<string, any>;
+
+type CursorDbBlob = {
+  rowid: number;
+  id: string;
+  data?: Buffer;
+};
+
+type CursorJsonBlob = CursorDbBlob & {
+  parsed: RawProviderMessage;
+};
+
+type CursorMessageBlob = {
+  id: string;
+  sequence: number;
+  rowid: number;
+  content: RawProviderMessage;
+};
+
+function readRawProviderMessage(raw: unknown): RawProviderMessage | null {
+  return readObjectRecord(raw) as RawProviderMessage | null;
+}
+
+export class CursorProvider extends AbstractProvider {
+  readonly mcp = new CursorMcpProvider();
+  readonly auth: IProviderAuth = new CursorProviderAuth();
+
+  constructor() {
+    super('cursor');
+  }
+
+  /**
+   * Loads Cursor's SQLite blob DAG and returns message blobs in conversation
+   * order. Cursor history is stored as content-addressed blobs rather than JSONL.
+   */
+  private async loadCursorBlobs(sessionId: string, projectPath: string): Promise<CursorMessageBlob[]> {
+    const sqlite3Module = await import('sqlite3');
+    const sqlite3 = sqlite3Module.default;
+    const { open } = await import('sqlite');
+
+    const cwdId = crypto.createHash('md5').update(projectPath || process.cwd()).digest('hex');
+    const storeDbPath = path.join(os.homedir(), '.cursor', 'chats', cwdId, sessionId, 'store.db');
+
+    const db = await open({
+      filename: storeDbPath,
+      driver: sqlite3.Database,
+      mode: sqlite3.OPEN_READONLY,
+    });
+
+    try {
+      const allBlobs = await db.all('SELECT rowid, id, data FROM blobs') as CursorDbBlob[];
+
+      const blobMap = new Map<string, CursorDbBlob>();
+      const parentRefs = new Map<string, string[]>();
+      const childRefs = new Map<string, string[]>();
+      const jsonBlobs: CursorJsonBlob[] = [];
+
+      for (const blob of allBlobs) {
+        blobMap.set(blob.id, blob);
+
+        if (blob.data && blob.data[0] === 0x7B) {
+          try {
+            const parsed = JSON.parse(blob.data.toString('utf8')) as RawProviderMessage;
+            jsonBlobs.push({ ...blob, parsed });
+          } catch {
+            // Cursor can include binary or partial blobs; only JSON blobs become messages.
+          }
+        } else if (blob.data) {
+          const parents: string[] = [];
+          let i = 0;
+          while (i < blob.data.length - 33) {
+            if (blob.data[i] === 0x0A && blob.data[i + 1] === 0x20) {
+              const parentHash = blob.data.slice(i + 2, i + 34).toString('hex');
+              if (blobMap.has(parentHash)) {
+                parents.push(parentHash);
+              }
+              i += 34;
+            } else {
+              i++;
+            }
+          }
+          if (parents.length > 0) {
+            parentRefs.set(blob.id, parents);
+            for (const parentId of parents) {
+              if (!childRefs.has(parentId)) {
+                childRefs.set(parentId, []);
+              }
+              childRefs.get(parentId)?.push(blob.id);
+            }
+          }
+        }
+      }
+
+      const visited = new Set<string>();
+      const sorted: CursorDbBlob[] = [];
+      const visit = (nodeId: string): void => {
+        if (visited.has(nodeId)) {
+          return;
+        }
+        visited.add(nodeId);
+        for (const parentId of parentRefs.get(nodeId) || []) {
+          visit(parentId);
+        }
+        const blob = blobMap.get(nodeId);
+        if (blob) {
+          sorted.push(blob);
+        }
+      };
+
+      for (const blob of allBlobs) {
+        if (!parentRefs.has(blob.id)) {
+          visit(blob.id);
+        }
+      }
+      for (const blob of allBlobs) {
+        visit(blob.id);
+      }
+
+      const messageOrder = new Map<string, number>();
+      let orderIndex = 0;
+      for (const blob of sorted) {
+        if (blob.data && blob.data[0] !== 0x7B) {
+          for (const jsonBlob of jsonBlobs) {
+            try {
+              const idBytes = Buffer.from(jsonBlob.id, 'hex');
+              if (blob.data.includes(idBytes) && !messageOrder.has(jsonBlob.id)) {
+                messageOrder.set(jsonBlob.id, orderIndex++);
+              }
+            } catch {
+              // Ignore malformed blob ids that cannot be decoded as hex.
+            }
+          }
+        }
+      }
+
+      const sortedJsonBlobs = jsonBlobs.sort((a, b) => {
+        const aOrder = messageOrder.get(a.id) ?? Number.MAX_SAFE_INTEGER;
+        const bOrder = messageOrder.get(b.id) ?? Number.MAX_SAFE_INTEGER;
+        return aOrder !== bOrder ? aOrder - bOrder : a.rowid - b.rowid;
+      });
+
+      const messages: CursorMessageBlob[] = [];
+      for (let idx = 0; idx < sortedJsonBlobs.length; idx++) {
+        const blob = sortedJsonBlobs[idx];
+        const parsed = blob.parsed;
+        const role = parsed?.role || parsed?.message?.role;
+        if (role === 'system') {
+          continue;
+        }
+        messages.push({
+          id: blob.id,
+          sequence: idx + 1,
+          rowid: blob.rowid,
+          content: parsed,
+        });
+      }
+
+      return messages;
+    } finally {
+      await db.close();
+    }
+  }
+
+  /**
+   * Normalizes live Cursor CLI NDJSON events. Persisted Cursor history is
+   * normalized from SQLite blobs in fetchHistory().
+   */
+  normalizeMessage(rawMessage: unknown, sessionId: string | null): NormalizedMessage[] {
+    const raw = readRawProviderMessage(rawMessage);
+    if (raw?.type === 'assistant' && raw.message?.content?.[0]?.text) {
+      return [createNormalizedMessage({
+        kind: 'stream_delta',
+        content: raw.message.content[0].text,
+        sessionId,
+        provider: PROVIDER,
+      })];
+    }
+
+    if (typeof rawMessage === 'string' && rawMessage.trim()) {
+      return [createNormalizedMessage({
+        kind: 'stream_delta',
+        content: rawMessage,
+        sessionId,
+        provider: PROVIDER,
+      })];
+    }
+
+    return [];
+  }
+
+  /**
+   * Fetches and paginates Cursor session history from its project-scoped store.db.
+   */
+  async fetchHistory(
+    sessionId: string,
+    options: FetchHistoryOptions = {},
+  ): Promise<FetchHistoryResult> {
+    const { projectPath = '', limit = null, offset = 0 } = options;
+
+    try {
+      const blobs = await this.loadCursorBlobs(sessionId, projectPath);
+      const allNormalized = this.normalizeCursorBlobs(blobs, sessionId);
+
+      if (limit !== null && limit > 0) {
+        const start = offset;
+        const page = allNormalized.slice(start, start + limit);
+        return {
+          messages: page,
+          total: allNormalized.length,
+          hasMore: start + limit < allNormalized.length,
+          offset,
+          limit,
+        };
+      }
+
+      return {
+        messages: allNormalized,
+        total: allNormalized.length,
+        hasMore: false,
+        offset: 0,
+        limit: null,
+      };
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      console.warn(`[CursorProvider] Failed to load session ${sessionId}:`, message);
+      return { messages: [], total: 0, hasMore: false, offset: 0, limit: null };
+    }
+  }
+
+  /**
+   * Converts Cursor SQLite message blobs into normalized messages and attaches
+   * matching tool results to their tool_use entries.
+   */
+  private normalizeCursorBlobs(blobs: CursorMessageBlob[], sessionId: string | null): NormalizedMessage[] {
+    const messages: NormalizedMessage[] = [];
+    const toolUseMap = new Map<string, NormalizedMessage>();
+    const baseTime = Date.now();
+
+    for (let i = 0; i < blobs.length; i++) {
+      const blob = blobs[i];
+      const content = blob.content;
+      const ts = new Date(baseTime + (blob.sequence ?? i) * 100).toISOString();
+      const baseId = blob.id || generateMessageId('cursor');
+
+      try {
+        if (!content?.role || !content?.content) {
+          if (content?.message?.role && content?.message?.content) {
+            if (content.message.role === 'system') {
+              continue;
+            }
+            const role = content.message.role === 'user' ? 'user' : 'assistant';
+            let text = '';
+            if (Array.isArray(content.message.content)) {
+              text = content.message.content
+                .map((part: string | RawProviderMessage) => typeof part === 'string' ? part : part?.text || '')
+                .filter(Boolean)
+                .join('\n');
+            } else if (typeof content.message.content === 'string') {
+              text = content.message.content;
+            }
+            if (text?.trim()) {
+              messages.push(createNormalizedMessage({
+                id: baseId,
+                sessionId,
+                timestamp: ts,
+                provider: PROVIDER,
+                kind: 'text',
+                role,
+                content: text,
+                sequence: blob.sequence,
+                rowid: blob.rowid,
+              }));
+            }
+          }
+          continue;
+        }
+
+        if (content.role === 'system') {
+          continue;
+        }
+
+        if (content.role === 'tool') {
+          const toolItems = Array.isArray(content.content) ? content.content : [];
+          for (const item of toolItems) {
+            if (item?.type !== 'tool-result') {
+              continue;
+            }
+            const toolCallId = item.toolCallId || content.id;
+            messages.push(createNormalizedMessage({
+              id: `${baseId}_tr`,
+              sessionId,
+              timestamp: ts,
+              provider: PROVIDER,
+              kind: 'tool_result',
+              toolId: toolCallId,
+              content: item.result || '',
+              isError: false,
+            }));
+          }
+          continue;
+        }
+
+        const role = content.role === 'user' ? 'user' : 'assistant';
+
+        if (Array.isArray(content.content)) {
+          for (let partIdx = 0; partIdx < content.content.length; partIdx++) {
+            const part = content.content[partIdx];
+
+            if (part?.type === 'text' && part?.text) {
+              messages.push(createNormalizedMessage({
+                id: `${baseId}_${partIdx}`,
+                sessionId,
+                timestamp: ts,
+                provider: PROVIDER,
+                kind: 'text',
+                role,
+                content: part.text,
+                sequence: blob.sequence,
+                rowid: blob.rowid,
+              }));
+            } else if (part?.type === 'reasoning' && part?.text) {
+              messages.push(createNormalizedMessage({
+                id: `${baseId}_${partIdx}`,
+                sessionId,
+                timestamp: ts,
+                provider: PROVIDER,
+                kind: 'thinking',
+                content: part.text,
+              }));
+            } else if (part?.type === 'tool-call' || part?.type === 'tool_use') {
+              const rawToolName = part.toolName || part.name || 'Unknown Tool';
+              const toolName = rawToolName === 'ApplyPatch' ? 'Edit' : rawToolName;
+              const toolId = part.toolCallId || part.id || `tool_${i}_${partIdx}`;
+              const message = createNormalizedMessage({
+                id: `${baseId}_${partIdx}`,
+                sessionId,
+                timestamp: ts,
+                provider: PROVIDER,
+                kind: 'tool_use',
+                toolName,
+                toolInput: part.args || part.input,
+                toolId,
+              });
+              messages.push(message);
+              toolUseMap.set(toolId, message);
+            }
+          }
+        } else if (typeof content.content === 'string' && content.content.trim()) {
+          messages.push(createNormalizedMessage({
+            id: baseId,
+            sessionId,
+            timestamp: ts,
+            provider: PROVIDER,
+            kind: 'text',
+            role,
+            content: content.content,
+            sequence: blob.sequence,
+            rowid: blob.rowid,
+          }));
+        }
+      } catch (error) {
+        console.warn('Error normalizing cursor blob:', error);
+      }
+    }
+
+    for (const msg of messages) {
+      if (msg.kind === 'tool_result' && msg.toolId && toolUseMap.has(msg.toolId)) {
+        const toolUse = toolUseMap.get(msg.toolId);
+        if (toolUse) {
+          toolUse.toolResult = {
+            content: msg.content,
+            isError: msg.isError,
+          };
+        }
+      }
+    }
+
+    messages.sort((a, b) => {
+      if (a.sequence !== undefined && b.sequence !== undefined) {
+        return a.sequence - b.sequence;
+      }
+      if (a.rowid !== undefined && b.rowid !== undefined) {
+        return a.rowid - b.rowid;
+      }
+      return new Date(a.timestamp).getTime() - new Date(b.timestamp).getTime();
+    });
+
+    return messages;
+  }
+}

server/modules/providers/list/gemini/gemini-auth.provider.ts

@@ -0,0 +1,151 @@
+import { readFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+
+import spawn from 'cross-spawn';
+
+import type { IProviderAuth } from '@/shared/interfaces.js';
+import type { ProviderAuthStatus } from '@/shared/types.js';
+import { readObjectRecord, readOptionalString } from '@/shared/utils.js';
+
+type GeminiCredentialsStatus = {
+  authenticated: boolean;
+  email: string | null;
+  method: string | null;
+  error?: string;
+};
+
+export class GeminiProviderAuth implements IProviderAuth {
+  /**
+   * Checks whether the Gemini CLI is available on this host.
+   */
+  private checkInstalled(): boolean {
+    const cliPath = process.env.GEMINI_PATH || 'gemini';
+    try {
+      spawn.sync(cliPath, ['--version'], { stdio: 'ignore', timeout: 5000 });
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Returns Gemini CLI installation and credential status.
+   */
+  async getStatus(): Promise<ProviderAuthStatus> {
+    const installed = this.checkInstalled();
+
+    if (!installed) {
+      return {
+        installed,
+        provider: 'gemini',
+        authenticated: false,
+        email: null,
+        method: null,
+        error: 'Gemini CLI is not installed',
+      };
+    }
+
+    const credentials = await this.checkCredentials();
+
+    return {
+      installed,
+      provider: 'gemini',
+      authenticated: credentials.authenticated,
+      email: credentials.email,
+      method: credentials.method,
+      error: credentials.authenticated ? undefined : credentials.error || 'Not authenticated',
+    };
+  }
+
+  /**
+   * Checks Gemini credentials from API key env vars or local OAuth credential files.
+   */
+  private async checkCredentials(): Promise<GeminiCredentialsStatus> {
+    if (process.env.GEMINI_API_KEY?.trim()) {
+      return { authenticated: true, email: 'API Key Auth', method: 'api_key' };
+    }
+
+    try {
+      const credsPath = path.join(os.homedir(), '.gemini', 'oauth_creds.json');
+      const content = await readFile(credsPath, 'utf8');
+      const creds = readObjectRecord(JSON.parse(content)) ?? {};
+      const accessToken = readOptionalString(creds.access_token);
+
+      if (!accessToken) {
+        return {
+          authenticated: false,
+          email: null,
+          method: null,
+          error: 'No valid tokens found in oauth_creds',
+        };
+      }
+
+      const refreshToken = readOptionalString(creds.refresh_token);
+      const tokenInfo = await this.getTokenInfoEmail(accessToken);
+      if (tokenInfo.valid) {
+        return {
+          authenticated: true,
+          email: tokenInfo.email || 'OAuth Session',
+          method: 'credentials_file',
+        };
+      }
+
+      if (!refreshToken) {
+        return {
+          authenticated: false,
+          email: null,
+          method: 'credentials_file',
+          error: 'Access token invalid and no refresh token found',
+        };
+      }
+
+      return {
+        authenticated: true,
+        email: await this.getActiveAccountEmail() || 'OAuth Session',
+        method: 'credentials_file',
+      };
+    } catch {
+      return {
+        authenticated: false,
+        email: null,
+        method: null,
+        error: 'Gemini CLI not configured',
+      };
+    }
+  }
+
+  /**
+   * Validates a Gemini OAuth access token and returns an email when Google reports one.
+   */
+  private async getTokenInfoEmail(accessToken: string): Promise<{ valid: boolean; email: string | null }> {
+    try {
+      const tokenRes = await fetch(`https://oauth2.googleapis.com/tokeninfo?access_token=${accessToken}`);
+      if (!tokenRes.ok) {
+        return { valid: false, email: null };
+      }
+
+      const tokenInfo = readObjectRecord(await tokenRes.json());
+      return {
+        valid: true,
+        email: readOptionalString(tokenInfo?.email) ?? null,
+      };
+    } catch {
+      return { valid: false, email: null };
+    }
+  }
+
+  /**
+   * Reads Gemini's active local Google account as an offline fallback for display.
+   */
+  private async getActiveAccountEmail(): Promise<string | null> {
+    try {
+      const accPath = path.join(os.homedir(), '.gemini', 'google_accounts.json');
+      const accContent = await readFile(accPath, 'utf8');
+      const accounts = readObjectRecord(JSON.parse(accContent));
+      return readOptionalString(accounts?.active) ?? null;
+    } catch {
+      return null;
+    }
+  }
+}

server/modules/providers/list/gemini/gemini-mcp.provider.ts

@@ -0,0 +1,110 @@
+import os from 'node:os';
+import path from 'node:path';
+
+import { McpProvider } from '@/modules/providers/shared/mcp/mcp.provider.js';
+import type { McpScope, ProviderMcpServer, UpsertProviderMcpServerInput } from '@/shared/types.js';
+import {
+  AppError,
+  readJsonConfig,
+  readObjectRecord,
+  readOptionalString,
+  readStringArray,
+  readStringRecord,
+  writeJsonConfig,
+} from '@/shared/utils.js';
+
+export class GeminiMcpProvider extends McpProvider {
+  constructor() {
+    super('gemini', ['user', 'project'], ['stdio', 'http', 'sse']);
+  }
+
+  protected async readScopedServers(scope: McpScope, workspacePath: string): Promise<Record<string, unknown>> {
+    const filePath = scope === 'user'
+      ? path.join(os.homedir(), '.gemini', 'settings.json')
+      : path.join(workspacePath, '.gemini', 'settings.json');
+    const config = await readJsonConfig(filePath);
+    return readObjectRecord(config.mcpServers) ?? {};
+  }
+
+  protected async writeScopedServers(
+    scope: McpScope,
+    workspacePath: string,
+    servers: Record<string, unknown>,
+  ): Promise<void> {
+    const filePath = scope === 'user'
+      ? path.join(os.homedir(), '.gemini', 'settings.json')
+      : path.join(workspacePath, '.gemini', 'settings.json');
+    const config = await readJsonConfig(filePath);
+    config.mcpServers = servers;
+    await writeJsonConfig(filePath, config);
+  }
+
+  protected buildServerConfig(input: UpsertProviderMcpServerInput): Record<string, unknown> {
+    if (input.transport === 'stdio') {
+      if (!input.command?.trim()) {
+        throw new AppError('command is required for stdio MCP servers.', {
+          code: 'MCP_COMMAND_REQUIRED',
+          statusCode: 400,
+        });
+      }
+
+      return {
+        command: input.command,
+        args: input.args ?? [],
+        env: input.env ?? {},
+        cwd: input.cwd,
+      };
+    }
+
+    if (!input.url?.trim()) {
+      throw new AppError('url is required for http/sse MCP servers.', {
+        code: 'MCP_URL_REQUIRED',
+        statusCode: 400,
+      });
+    }
+
+    return {
+      type: input.transport,
+      url: input.url,
+      headers: input.headers ?? {},
+    };
+  }
+
+  protected normalizeServerConfig(
+    scope: McpScope,
+    name: string,
+    rawConfig: unknown,
+  ): ProviderMcpServer | null {
+    if (!rawConfig || typeof rawConfig !== 'object') {
+      return null;
+    }
+
+    const config = rawConfig as Record<string, unknown>;
+    if (typeof config.command === 'string') {
+      return {
+        provider: 'gemini',
+        name,
+        scope,
+        transport: 'stdio',
+        command: config.command,
+        args: readStringArray(config.args),
+        env: readStringRecord(config.env),
+        cwd: readOptionalString(config.cwd),
+      };
+    }
+
+    if (typeof config.url === 'string') {
+      const transport = readOptionalString(config.type) === 'sse' ? 'sse' : 'http';
+      return {
+        provider: 'gemini',
+        name,
+        scope,
+        transport,
+        url: config.url,
+        headers: readStringRecord(config.headers),
+      };
+    }
+
+    return null;
+  }
+}

server/modules/providers/list/gemini/gemini.provider.ts

@@ -0,0 +1,235 @@
+import sessionManager from '@/sessionManager.js';
+import { getGeminiCliSessionMessages } from '@/projects.js';
+import { AbstractProvider } from '@/modules/providers/shared/base/abstract.provider.js';
+import { GeminiProviderAuth } from '@/modules/providers/list/gemini/gemini-auth.provider.js';
+import { GeminiMcpProvider } from '@/modules/providers/list/gemini/gemini-mcp.provider.js';
+import type { IProviderAuth } from '@/shared/interfaces.js';
+import type { FetchHistoryOptions, FetchHistoryResult, NormalizedMessage } from '@/shared/types.js';
+import { createNormalizedMessage, generateMessageId, readObjectRecord } from '@/shared/utils.js';
+
+const PROVIDER = 'gemini';
+
+type RawProviderMessage = Record<string, any>;
+
+function readRawProviderMessage(raw: unknown): RawProviderMessage | null {
+  return readObjectRecord(raw) as RawProviderMessage | null;
+}
+
+export class GeminiProvider extends AbstractProvider {
+  readonly mcp = new GeminiMcpProvider();
+  readonly auth: IProviderAuth = new GeminiProviderAuth();
+
+  constructor() {
+    super('gemini');
+  }
+
+  /**
+   * Normalizes live Gemini stream-json events into the shared message shape.
+   *
+   * Gemini history uses a different session file shape, so fetchHistory handles
+   * that separately after loading raw persisted messages.
+   */
+  normalizeMessage(rawMessage: unknown, sessionId: string | null): NormalizedMessage[] {
+    const raw = readRawProviderMessage(rawMessage);
+    if (!raw) {
+      return [];
+    }
+
+    const ts = raw.timestamp || new Date().toISOString();
+    const baseId = raw.uuid || generateMessageId('gemini');
+
+    if (raw.type === 'message' && raw.role === 'assistant') {
+      const content = raw.content || '';
+      const messages: NormalizedMessage[] = [];
+      if (content) {
+        messages.push(createNormalizedMessage({
+          id: baseId,
+          sessionId,
+          timestamp: ts,
+          provider: PROVIDER,
+          kind: 'stream_delta',
+          content,
+        }));
+      }
+      if (raw.delta !== true) {
+        messages.push(createNormalizedMessage({
+          sessionId,
+          timestamp: ts,
+          provider: PROVIDER,
+          kind: 'stream_end',
+        }));
+      }
+      return messages;
+    }
+
+    if (raw.type === 'tool_use') {
+      return [createNormalizedMessage({
+        id: baseId,
+        sessionId,
+        timestamp: ts,
+        provider: PROVIDER,
+        kind: 'tool_use',
+        toolName: raw.tool_name,
+        toolInput: raw.parameters || {},
+        toolId: raw.tool_id || baseId,
+      })];
+    }
+
+    if (raw.type === 'tool_result') {
+      return [createNormalizedMessage({
+        id: baseId,
+        sessionId,
+        timestamp: ts,
+        provider: PROVIDER,
+        kind: 'tool_result',
+        toolId: raw.tool_id || '',
+        content: raw.output === undefined ? '' : String(raw.output),
+        isError: raw.status === 'error',
+      })];
+    }
+
+    if (raw.type === 'result') {
+      const messages = [createNormalizedMessage({
+        sessionId,
+        timestamp: ts,
+        provider: PROVIDER,
+        kind: 'stream_end',
+      })];
+      if (raw.stats?.total_tokens) {
+        messages.push(createNormalizedMessage({
+          sessionId,
+          timestamp: ts,
+          provider: PROVIDER,
+          kind: 'status',
+          text: 'Complete',
+          tokens: raw.stats.total_tokens,
+          canInterrupt: false,
+        }));
+      }
+      return messages;
+    }
+
+    if (raw.type === 'error') {
+      return [createNormalizedMessage({
+        id: baseId,
+        sessionId,
+        timestamp: ts,
+        provider: PROVIDER,
+        kind: 'error',
+        content: raw.error || raw.message || 'Unknown Gemini streaming error',
+      })];
+    }
+
+    return [];
+  }
+
+  /**
+   * Loads Gemini history from the in-memory session manager first, then falls
+   * back to Gemini CLI session files on disk.
+   */
+  async fetchHistory(
+    sessionId: string,
+    _options: FetchHistoryOptions = {},
+  ): Promise<FetchHistoryResult> {
+    let rawMessages: RawProviderMessage[];
+    try {
+      rawMessages = sessionManager.getSessionMessages(sessionId) as RawProviderMessage[];
+
+      if (rawMessages.length === 0) {
+        rawMessages = await getGeminiCliSessionMessages(sessionId) as RawProviderMessage[];
+      }
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      console.warn(`[GeminiProvider] Failed to load session ${sessionId}:`, message);
+      return { messages: [], total: 0, hasMore: false, offset: 0, limit: null };
+    }
+
+    const normalized: NormalizedMessage[] = [];
+    for (let i = 0; i < rawMessages.length; i++) {
+      const raw = rawMessages[i];
+      const ts = raw.timestamp || new Date().toISOString();
+      const baseId = raw.uuid || generateMessageId('gemini');
+
+      const role = raw.message?.role || raw.role;
+      const content = raw.message?.content || raw.content;
+
+      if (!role || !content) {
+        continue;
+      }
+
+      const normalizedRole = role === 'user' ? 'user' : 'assistant';
+
+      if (Array.isArray(content)) {
+        for (let partIdx = 0; partIdx < content.length; partIdx++) {
+          const part = content[partIdx];
+          if (part.type === 'text' && part.text) {
+            normalized.push(createNormalizedMessage({
+              id: `${baseId}_${partIdx}`,
+              sessionId,
+              timestamp: ts,
+              provider: PROVIDER,
+              kind: 'text',
+              role: normalizedRole,
+              content: part.text,
+            }));
+          } else if (part.type === 'tool_use') {
+            normalized.push(createNormalizedMessage({
+              id: `${baseId}_${partIdx}`,
+              sessionId,
+              timestamp: ts,
+              provider: PROVIDER,
+              kind: 'tool_use',
+              toolName: part.name,
+              toolInput: part.input,
+              toolId: part.id || generateMessageId('gemini_tool'),
+            }));
+          } else if (part.type === 'tool_result') {
+            normalized.push(createNormalizedMessage({
+              id: `${baseId}_${partIdx}`,
+              sessionId,
+              timestamp: ts,
+              provider: PROVIDER,
+              kind: 'tool_result',
+              toolId: part.tool_use_id || '',
+              content: part.content === undefined ? '' : String(part.content),
+              isError: Boolean(part.is_error),
+            }));
+          }
+        }
+      } else if (typeof content === 'string' && content.trim()) {
+        normalized.push(createNormalizedMessage({
+          id: baseId,
+          sessionId,
+          timestamp: ts,
+          provider: PROVIDER,
+          kind: 'text',
+          role: normalizedRole,
+          content,
+        }));
+      }
+    }
+
+    const toolResultMap = new Map<string, NormalizedMessage>();
+    for (const msg of normalized) {
+      if (msg.kind === 'tool_result' && msg.toolId) {
+        toolResultMap.set(msg.toolId, msg);
+      }
+    }
+    for (const msg of normalized) {
+      if (msg.kind === 'tool_use' && msg.toolId && toolResultMap.has(msg.toolId)) {
+        const toolResult = toolResultMap.get(msg.toolId);
+        if (toolResult) {
+          msg.toolResult = { content: toolResult.content, isError: toolResult.isError };
+        }
+      }
+    }
+
+    return {
+      messages: normalized,
+      total: normalized.length,
+      hasMore: false,
+      offset: 0,
+      limit: null,
+    };
+  }
+}

server/modules/providers/provider.registry.ts

@@ -0,0 +1,36 @@
+import { ClaudeProvider } from '@/modules/providers/list/claude/claude.provider.js';
+import { CodexProvider } from '@/modules/providers/list/codex/codex.provider.js';
+import { CursorProvider } from '@/modules/providers/list/cursor/cursor.provider.js';
+import { GeminiProvider } from '@/modules/providers/list/gemini/gemini.provider.js';
+import type { IProvider } from '@/shared/interfaces.js';
+import type { LLMProvider } from '@/shared/types.js';
+import { AppError } from '@/shared/utils.js';
+
+const providers: Record<LLMProvider, IProvider> = {
+  claude: new ClaudeProvider(),
+  codex: new CodexProvider(),
+  cursor: new CursorProvider(),
+  gemini: new GeminiProvider(),
+};
+
+/**
+ * Central registry for resolving concrete provider implementations by id.
+ */
+export const providerRegistry = {
+  listProviders(): IProvider[] {
+    return Object.values(providers);
+  },
+
+  resolveProvider(provider: string): IProvider {
+    const key = provider as LLMProvider;
+    const resolvedProvider = providers[key];
+    if (!resolvedProvider) {
+      throw new AppError(`Unsupported provider "${provider}".`, {
+        code: 'UNSUPPORTED_PROVIDER',
+        statusCode: 400,
+      });
+    }
+
+    return resolvedProvider;
+  },
+};

server/modules/providers/provider.routes.ts

@@ -0,0 +1,217 @@
+import express, { type Request, type Response } from 'express';
+
+import { providerAuthService } from '@/modules/providers/services/provider-auth.service.js';
+import { providerMcpService } from '@/modules/providers/services/mcp.service.js';
+import type { LLMProvider, McpScope, McpTransport, UpsertProviderMcpServerInput } from '@/shared/types.js';
+import { AppError, asyncHandler, createApiSuccessResponse } from '@/shared/utils.js';
+
+const router = express.Router();
+
+const readPathParam = (value: unknown, name: string): string => {
+  if (typeof value === 'string') {
+    return value;
+  }
+
+  if (Array.isArray(value) && typeof value[0] === 'string') {
+    return value[0];
+  }
+
+  throw new AppError(`${name} path parameter is invalid.`, {
+    code: 'INVALID_PATH_PARAMETER',
+    statusCode: 400,
+  });
+};
+
+const normalizeProviderParam = (value: unknown): string =>
+  readPathParam(value, 'provider').trim().toLowerCase();
+
+const readOptionalQueryString = (value: unknown): string | undefined => {
+  if (typeof value !== 'string') {
+    return undefined;
+  }
+
+  const normalized = value.trim();
+  return normalized.length > 0 ? normalized : undefined;
+};
+
+const parseMcpScope = (value: unknown): McpScope | undefined => {
+  if (value === undefined) {
+    return undefined;
+  }
+
+  const normalized = readOptionalQueryString(value);
+  if (!normalized) {
+    return undefined;
+  }
+
+  if (normalized === 'user' || normalized === 'local' || normalized === 'project') {
+    return normalized;
+  }
+
+  throw new AppError(`Unsupported MCP scope "${normalized}".`, {
+    code: 'INVALID_MCP_SCOPE',
+    statusCode: 400,
+  });
+};
+
+const parseMcpTransport = (value: unknown): McpTransport => {
+  const normalized = readOptionalQueryString(value);
+  if (!normalized) {
+    throw new AppError('transport is required.', {
+      code: 'MCP_TRANSPORT_REQUIRED',
+      statusCode: 400,
+    });
+  }
+
+  if (normalized === 'stdio' || normalized === 'http' || normalized === 'sse') {
+    return normalized;
+  }
+
+  throw new AppError(`Unsupported MCP transport "${normalized}".`, {
+    code: 'INVALID_MCP_TRANSPORT',
+    statusCode: 400,
+  });
+};
+
+const parseMcpUpsertPayload = (payload: unknown): UpsertProviderMcpServerInput => {
+  if (!payload || typeof payload !== 'object') {
+    throw new AppError('Request body must be an object.', {
+      code: 'INVALID_REQUEST_BODY',
+      statusCode: 400,
+    });
+  }
+
+  const body = payload as Record<string, unknown>;
+  const name = readOptionalQueryString(body.name);
+  if (!name) {
+    throw new AppError('name is required.', {
+      code: 'MCP_NAME_REQUIRED',
+      statusCode: 400,
+    });
+  }
+
+  const transport = parseMcpTransport(body.transport);
+  const scope = parseMcpScope(body.scope);
+  const workspacePath = readOptionalQueryString(body.workspacePath);
+
+  return {
+    name,
+    transport,
+    scope,
+    workspacePath,
+    command: readOptionalQueryString(body.command),
+    args: Array.isArray(body.args) ? body.args.filter((entry): entry is string => typeof entry === 'string') : undefined,
+    env: typeof body.env === 'object' && body.env !== null
+      ? Object.fromEntries(
+          Object.entries(body.env as Record<string, unknown>).filter(
+            (entry): entry is [string, string] => typeof entry[1] === 'string',
+          ),
+        )
+      : undefined,
+    cwd: readOptionalQueryString(body.cwd),
+    url: readOptionalQueryString(body.url),
+    headers: typeof body.headers === 'object' && body.headers !== null
+      ? Object.fromEntries(
+          Object.entries(body.headers as Record<string, unknown>).filter(
+            (entry): entry is [string, string] => typeof entry[1] === 'string',
+          ),
+        )
+      : undefined,
+    envVars: Array.isArray(body.envVars)
+      ? body.envVars.filter((entry): entry is string => typeof entry === 'string')
+      : undefined,
+    bearerTokenEnvVar: readOptionalQueryString(body.bearerTokenEnvVar),
+    envHttpHeaders: typeof body.envHttpHeaders === 'object' && body.envHttpHeaders !== null
+      ? Object.fromEntries(
+          Object.entries(body.envHttpHeaders as Record<string, unknown>).filter(
+            (entry): entry is [string, string] => typeof entry[1] === 'string',
+          ),
+        )
+      : undefined,
+  };
+};
+
+const parseProvider = (value: unknown): LLMProvider => {
+  const normalized = normalizeProviderParam(value);
+  if (normalized === 'claude' || normalized === 'codex' || normalized === 'cursor' || normalized === 'gemini') {
+    return normalized;
+  }
+
+  throw new AppError(`Unsupported provider "${normalized}".`, {
+    code: 'UNSUPPORTED_PROVIDER',
+    statusCode: 400,
+  });
+};
+
+router.get(
+  '/:provider/auth/status',
+  asyncHandler(async (req: Request, res: Response) => {
+    const provider = parseProvider(req.params.provider);
+    const status = await providerAuthService.getProviderAuthStatus(provider);
+    res.json(status);
+  }),
+);
+
+router.get(
+  '/:provider/mcp/servers',
+  asyncHandler(async (req: Request, res: Response) => {
+    const provider = parseProvider(req.params.provider);
+    const workspacePath = readOptionalQueryString(req.query.workspacePath);
+    const scope = parseMcpScope(req.query.scope);
+
+    if (scope) {
+      const servers = await providerMcpService.listProviderMcpServersForScope(provider, scope, { workspacePath });
+      res.json(createApiSuccessResponse({ provider, scope, servers }));
+      return;
+    }
+
+    const groupedServers = await providerMcpService.listProviderMcpServers(provider, { workspacePath });
+    res.json(createApiSuccessResponse({ provider, scopes: groupedServers }));
+  }),
+);
+
+router.post(
+  '/:provider/mcp/servers',
+  asyncHandler(async (req: Request, res: Response) => {
+    const provider = parseProvider(req.params.provider);
+    const payload = parseMcpUpsertPayload(req.body);
+    const server = await providerMcpService.upsertProviderMcpServer(provider, payload);
+    res.status(201).json(createApiSuccessResponse({ server }));
+  }),
+);
+
+router.delete(
+  '/:provider/mcp/servers/:name',
+  asyncHandler(async (req: Request, res: Response) => {
+    const provider = parseProvider(req.params.provider);
+    const scope = parseMcpScope(req.query.scope);
+    const workspacePath = readOptionalQueryString(req.query.workspacePath);
+    const result = await providerMcpService.removeProviderMcpServer(provider, {
+      name: readPathParam(req.params.name, 'name'),
+      scope,
+      workspacePath,
+    });
+    res.json(createApiSuccessResponse(result));
+  }),
+);
+
+router.post(
+  '/mcp/servers/global',
+  asyncHandler(async (req: Request, res: Response) => {
+    const payload = parseMcpUpsertPayload(req.body);
+    if (payload.scope === 'local') {
+      throw new AppError('Global MCP add supports only "user" or "project" scopes.', {
+        code: 'INVALID_GLOBAL_MCP_SCOPE',
+        statusCode: 400,
+      });
+    }
+
+    const results = await providerMcpService.addMcpServerToAllProviders({
+      ...payload,
+      scope: payload.scope === 'user' ? 'user' : 'project',
+    });
+    res.status(201).json(createApiSuccessResponse({ results }));
+  }),
+);
+
+export default router;

server/modules/providers/services/mcp.service.ts

@@ -0,0 +1,94 @@
+import os from 'node:os';
+
+import { providerRegistry } from '@/modules/providers/provider.registry.js';
+import type { LLMProvider, McpScope, ProviderMcpServer, UpsertProviderMcpServerInput } from '@/shared/types.js';
+import { AppError } from '@/shared/utils.js';
+
+/** Cursor MCP is not supported on Windows hosts (no Cursor CLI integration). */
+function includeProviderInGlobalMcp(providerId: LLMProvider): boolean {
+  if (providerId === 'cursor' && os.platform() === 'win32') {
+    return false;
+  }
+
+  return true;
+}
+
+
+export const providerMcpService = {
+  /**
+   * Lists MCP servers for one provider grouped by supported scopes.
+   */
+  async listProviderMcpServers(
+    providerName: string,
+    options?: { workspacePath?: string },
+  ): Promise<Record<McpScope, ProviderMcpServer[]>> {
+    const provider = providerRegistry.resolveProvider(providerName);
+    return provider.mcp.listServers(options);
+  },
+
+  /**
+   * Lists MCP servers for one provider scope.
+   */
+  async listProviderMcpServersForScope(
+    providerName: string,
+    scope: McpScope,
+    options?: { workspacePath?: string },
+  ): Promise<ProviderMcpServer[]> {
+    const provider = providerRegistry.resolveProvider(providerName);
+    return provider.mcp.listServersForScope(scope, options);
+  },
+
+  /**
+   * Adds or updates one provider MCP server.
+   */
+  async upsertProviderMcpServer(
+    providerName: string,
+    input: UpsertProviderMcpServerInput,
+  ): Promise<ProviderMcpServer> {
+    const provider = providerRegistry.resolveProvider(providerName);
+    return provider.mcp.upsertServer(input);
+  },
+
+  /**
+   * Removes one provider MCP server.
+   */
+  async removeProviderMcpServer(
+    providerName: string,
+    input: { name: string; scope?: McpScope; workspacePath?: string },
+  ): Promise<{ removed: boolean; provider: LLMProvider; name: string; scope: McpScope }> {
+    const provider = providerRegistry.resolveProvider(providerName);
+    return provider.mcp.removeServer(input);
+  },
+
+  /**
+   * Adds one HTTP/stdio MCP server to every provider.
+   */
+  async addMcpServerToAllProviders(
+    input: Omit<UpsertProviderMcpServerInput, 'scope'> & { scope?: Exclude<McpScope, 'local'> },
+  ): Promise<Array<{ provider: LLMProvider; created: boolean; error?: string }>> {
+    if (input.transport !== 'stdio' && input.transport !== 'http') {
+      throw new AppError('Global MCP add supports only "stdio" and "http".', {
+        code: 'INVALID_GLOBAL_MCP_TRANSPORT',
+        statusCode: 400,
+      });
+    }
+
+    const scope = input.scope ?? 'project';
+    const results: Array<{ provider: LLMProvider; created: boolean; error?: string }> = [];
+    const providers = providerRegistry.listProviders().filter((p) => includeProviderInGlobalMcp(p.id));
+    for (const provider of providers) {
+      try {
+        await provider.mcp.upsertServer({ ...input, scope });
+        results.push({ provider: provider.id, created: true });
+      } catch (error) {
+        results.push({
+          provider: provider.id,
+          created: false,
+          error: error instanceof Error ? error.message : 'Unknown error',
+        });
+      }
+    }
+
+    return results;
+  },
+};

server/modules/providers/services/provider-auth.service.ts

@@ -0,0 +1,12 @@
+import { providerRegistry } from '@/modules/providers/provider.registry.js';
+import type { ProviderAuthStatus } from '@/shared/types.js';
+
+export const providerAuthService = {
+  /**
+   * Resolves a provider and returns its installation/authentication status.
+   */
+  async getProviderAuthStatus(providerName: string): Promise<ProviderAuthStatus> {
+    const provider = providerRegistry.resolveProvider(providerName);
+    return provider.auth.getStatus();
+  },
+};

server/modules/providers/services/sessions.service.ts

@@ -0,0 +1,45 @@
+import { providerRegistry } from '@/modules/providers/provider.registry.js';
+import type {
+  FetchHistoryOptions,
+  FetchHistoryResult,
+  LLMProvider,
+  NormalizedMessage,
+} from '@/shared/types.js';
+
+/**
+ * Application service for provider-backed session message operations.
+ *
+ * Callers pass a provider id and this service resolves the concrete provider
+ * class, keeping normalization/history call sites decoupled from implementation
+ * file layout.
+ */
+export const sessionsService = {
+  /**
+   * Lists provider ids that can load session history and normalize live messages.
+   */
+  listProviderIds(): LLMProvider[] {
+    return providerRegistry.listProviders().map((provider) => provider.id);
+  },
+
+  /**
+   * Normalizes one provider-native event into frontend session message events.
+   */
+  normalizeMessage(
+    providerName: string,
+    raw: unknown,
+    sessionId: string | null,
+  ): NormalizedMessage[] {
+    return providerRegistry.resolveProvider(providerName).normalizeMessage(raw, sessionId);
+  },
+
+  /**
+   * Fetches normalized persisted session history for one provider/session pair.
+   */
+  fetchHistory(
+    providerName: string,
+    sessionId: string,
+    options?: FetchHistoryOptions,
+  ): Promise<FetchHistoryResult> {
+    return providerRegistry.resolveProvider(providerName).fetchHistory(sessionId, options);
+  },
+};

server/modules/providers/shared/base/abstract.provider.ts

@@ -0,0 +1,31 @@
+import type { IProvider, IProviderAuth, IProviderMcp } from '@/shared/interfaces.js';
+import type {
+  FetchHistoryOptions,
+  FetchHistoryResult,
+  LLMProvider,
+  NormalizedMessage,
+} from '@/shared/types.js';
+
+/**
+ * Shared provider base.
+ *
+ * Concrete providers must expose auth/MCP handlers and implement message
+ * normalization/history loading because those behaviors depend on native
+ * SDK/CLI formats.
+ */
+export abstract class AbstractProvider implements IProvider {
+  readonly id: LLMProvider;
+  abstract readonly mcp: IProviderMcp;
+  abstract readonly auth: IProviderAuth;
+
+  protected constructor(id: LLMProvider) {
+    this.id = id;
+  }
+
+  abstract normalizeMessage(raw: unknown, sessionId: string | null): NormalizedMessage[];
+
+  abstract fetchHistory(
+    sessionId: string,
+    options?: FetchHistoryOptions,
+  ): Promise<FetchHistoryResult>;
+}

server/modules/providers/shared/mcp/mcp.provider.ts

@@ -0,0 +1,151 @@
+import path from 'node:path';
+
+import type { IProviderMcp } from '@/shared/interfaces.js';
+import type { LLMProvider, McpScope, McpTransport, ProviderMcpServer, UpsertProviderMcpServerInput } from '@/shared/types.js';
+import { AppError } from '@/shared/utils.js';
+
+const resolveWorkspacePath = (workspacePath?: string): string =>
+  path.resolve(workspacePath ?? process.cwd());
+
+const normalizeServerName = (name: string): string => {
+  const normalized = name.trim();
+  if (!normalized) {
+    throw new AppError('MCP server name is required.', {
+      code: 'MCP_SERVER_NAME_REQUIRED',
+      statusCode: 400,
+    });
+  }
+
+  return normalized;
+};
+
+/**
+ * Shared MCP provider for provider-specific config readers/writers.
+ */
+export abstract class McpProvider implements IProviderMcp {
+  protected readonly provider: LLMProvider;
+  protected readonly supportedScopes: McpScope[];
+  protected readonly supportedTransports: McpTransport[];
+
+  protected constructor(
+    provider: LLMProvider,
+    supportedScopes: McpScope[],
+    supportedTransports: McpTransport[],
+  ) {
+    this.provider = provider;
+    this.supportedScopes = supportedScopes;
+    this.supportedTransports = supportedTransports;
+  }
+
+  async listServers(options?: { workspacePath?: string }): Promise<Record<McpScope, ProviderMcpServer[]>> {
+    const grouped: Record<McpScope, ProviderMcpServer[]> = {
+      user: [],
+      local: [],
+      project: [],
+    };
+
+    for (const scope of this.supportedScopes) {
+      grouped[scope] = await this.listServersForScope(scope, options);
+    }
+
+    return grouped;
+  }
+
+  async listServersForScope(
+    scope: McpScope,
+    options?: { workspacePath?: string },
+  ): Promise<ProviderMcpServer[]> {
+    if (!this.supportedScopes.includes(scope)) {
+      return [];
+    }
+
+    const workspacePath = resolveWorkspacePath(options?.workspacePath);
+    const scopedServers = await this.readScopedServers(scope, workspacePath);
+    return Object.entries(scopedServers)
+      .map(([name, rawConfig]) => this.normalizeServerConfig(scope, name, rawConfig))
+      .filter((entry): entry is ProviderMcpServer => entry !== null);
+  }
+
+  async upsertServer(input: UpsertProviderMcpServerInput): Promise<ProviderMcpServer> {
+    const scope = input.scope ?? 'project';
+    this.assertScopeAndTransport(scope, input.transport);
+
+    const workspacePath = resolveWorkspacePath(input.workspacePath);
+    const normalizedName = normalizeServerName(input.name);
+    const scopedServers = await this.readScopedServers(scope, workspacePath);
+    scopedServers[normalizedName] = this.buildServerConfig(input);
+    await this.writeScopedServers(scope, workspacePath, scopedServers);
+
+    return {
+      provider: this.provider,
+      name: normalizedName,
+      scope,
+      transport: input.transport,
+      command: input.command,
+      args: input.args,
+      env: input.env,
+      cwd: input.cwd,
+      url: input.url,
+      headers: input.headers,
+      envVars: input.envVars,
+      bearerTokenEnvVar: input.bearerTokenEnvVar,
+      envHttpHeaders: input.envHttpHeaders,
+    };
+  }
+
+  async removeServer(
+    input: { name: string; scope?: McpScope; workspacePath?: string },
+  ): Promise<{ removed: boolean; provider: LLMProvider; name: string; scope: McpScope }> {
+    const scope = input.scope ?? 'project';
+    this.assertScope(scope);
+
+    const workspacePath = resolveWorkspacePath(input.workspacePath);
+    const normalizedName = normalizeServerName(input.name);
+    const scopedServers = await this.readScopedServers(scope, workspacePath);
+    const removed = Object.prototype.hasOwnProperty.call(scopedServers, normalizedName);
+    if (removed) {
+      delete scopedServers[normalizedName];
+      await this.writeScopedServers(scope, workspacePath, scopedServers);
+    }
+
+    return { removed, provider: this.provider, name: normalizedName, scope };
+  }
+
+  protected abstract readScopedServers(
+    scope: McpScope,
+    workspacePath: string,
+  ): Promise<Record<string, unknown>>;
+
+  protected abstract writeScopedServers(
+    scope: McpScope,
+    workspacePath: string,
+    servers: Record<string, unknown>,
+  ): Promise<void>;
+
+  protected abstract buildServerConfig(input: UpsertProviderMcpServerInput): Record<string, unknown>;
+
+  protected abstract normalizeServerConfig(
+    scope: McpScope,
+    name: string,
+    rawConfig: unknown,
+  ): ProviderMcpServer | null;
+
+  protected assertScope(scope: McpScope): void {
+    if (!this.supportedScopes.includes(scope)) {
+      throw new AppError(`Provider "${this.provider}" does not support "${scope}" MCP scope.`, {
+        code: 'MCP_SCOPE_NOT_SUPPORTED',
+        statusCode: 400,
+      });
+    }
+  }
+
+  protected assertScopeAndTransport(scope: McpScope, transport: McpTransport): void {
+    this.assertScope(scope);
+    if (!this.supportedTransports.includes(transport)) {
+      throw new AppError(`Provider "${this.provider}" does not support "${transport}" MCP transport.`, {
+        code: 'MCP_TRANSPORT_NOT_SUPPORTED',
+        statusCode: 400,
+      });
+    }
+  }
+}

server/modules/providers/tests/mcp.test.ts

@@ -0,0 +1,293 @@
+import assert from 'node:assert/strict';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import test from 'node:test';
+
+import TOML from '@iarna/toml';
+
+import { providerMcpService } from '@/modules/providers/services/mcp.service.js';
+import { AppError } from '@/shared/utils.js';
+
+const patchHomeDir = (nextHomeDir: string) => {
+  const original = os.homedir;
+  (os as any).homedir = () => nextHomeDir;
+  return () => {
+    (os as any).homedir = original;
+  };
+};
+
+const readJson = async (filePath: string): Promise<Record<string, unknown>> => {
+  const content = await fs.readFile(filePath, 'utf8');
+  return JSON.parse(content) as Record<string, unknown>;
+};
+
+/**
+ * This test covers Claude MCP support for all scopes (user/local/project) and all transports (stdio/http/sse),
+ * including add, update/list, and remove operations.
+ */
+test('providerMcpService handles claude MCP scopes/transports with file-backed persistence', { concurrency: false }, async () => {
+  const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'llm-mcp-claude-'));
+  const workspacePath = path.join(tempRoot, 'workspace');
+  await fs.mkdir(workspacePath, { recursive: true });
+
+  const restoreHomeDir = patchHomeDir(tempRoot);
+  try {
+    await providerMcpService.upsertProviderMcpServer('claude', {
+      name: 'claude-user-stdio',
+      scope: 'user',
+      transport: 'stdio',
+      command: 'npx',
+      args: ['-y', 'my-server'],
+      env: { API_KEY: 'secret' },
+    });
+
+    await providerMcpService.upsertProviderMcpServer('claude', {
+      name: 'claude-local-http',
+      scope: 'local',
+      transport: 'http',
+      url: 'https://example.com/mcp',
+      headers: { Authorization: 'Bearer token' },
+      workspacePath,
+    });
+
+    await providerMcpService.upsertProviderMcpServer('claude', {
+      name: 'claude-project-sse',
+      scope: 'project',
+      transport: 'sse',
+      url: 'https://example.com/sse',
+      headers: { 'X-API-Key': 'abc' },
+      workspacePath,
+    });
+
+    const grouped = await providerMcpService.listProviderMcpServers('claude', { workspacePath });
+    assert.ok(grouped.user.some((server) => server.name === 'claude-user-stdio' && server.transport === 'stdio'));
+    assert.ok(grouped.local.some((server) => server.name === 'claude-local-http' && server.transport === 'http'));
+    assert.ok(grouped.project.some((server) => server.name === 'claude-project-sse' && server.transport === 'sse'));
+
+    // update behavior is the same upsert route with same name
+    await providerMcpService.upsertProviderMcpServer('claude', {
+      name: 'claude-project-sse',
+      scope: 'project',
+      transport: 'sse',
+      url: 'https://example.com/sse-updated',
+      headers: { 'X-API-Key': 'updated' },
+      workspacePath,
+    });
+
+    const projectConfig = await readJson(path.join(workspacePath, '.mcp.json'));
+    const projectServers = projectConfig.mcpServers as Record<string, unknown>;
+    const projectServer = projectServers['claude-project-sse'] as Record<string, unknown>;
+    assert.equal(projectServer.url, 'https://example.com/sse-updated');
+
+    const removeResult = await providerMcpService.removeProviderMcpServer('claude', {
+      name: 'claude-local-http',
+      scope: 'local',
+      workspacePath,
+    });
+    assert.equal(removeResult.removed, true);
+  } finally {
+    restoreHomeDir();
+    await fs.rm(tempRoot, { recursive: true, force: true });
+  }
+});
+
+/**
+ * This test covers Codex MCP support for user/project scopes, stdio/http formats,
+ * and validation for unsupported scope/transport combinations.
+ */
+test('providerMcpService handles codex MCP TOML config and capability validation', { concurrency: false }, async () => {
+  const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'llm-mcp-codex-'));
+  const workspacePath = path.join(tempRoot, 'workspace');
+  await fs.mkdir(workspacePath, { recursive: true });
+
+  const restoreHomeDir = patchHomeDir(tempRoot);
+  try {
+    await providerMcpService.upsertProviderMcpServer('codex', {
+      name: 'codex-user-stdio',
+      scope: 'user',
+      transport: 'stdio',
+      command: 'python',
+      args: ['server.py'],
+      env: { API_KEY: 'x' },
+      envVars: ['API_KEY'],
+      cwd: '/tmp',
+    });
+
+    await providerMcpService.upsertProviderMcpServer('codex', {
+      name: 'codex-project-http',
+      scope: 'project',
+      transport: 'http',
+      url: 'https://codex.example.com/mcp',
+      headers: { 'X-Custom-Header': 'value' },
+      envHttpHeaders: { 'X-API-Key': 'MY_API_KEY_ENV' },
+      bearerTokenEnvVar: 'MY_API_TOKEN',
+      workspacePath,
+    });
+
+    const userTomlPath = path.join(tempRoot, '.codex', 'config.toml');
+    const userConfig = TOML.parse(await fs.readFile(userTomlPath, 'utf8')) as Record<string, unknown>;
+    const userServers = userConfig.mcp_servers as Record<string, unknown>;
+    const userStdio = userServers['codex-user-stdio'] as Record<string, unknown>;
+    assert.equal(userStdio.command, 'python');
+
+    const projectTomlPath = path.join(workspacePath, '.codex', 'config.toml');
+    const projectConfig = TOML.parse(await fs.readFile(projectTomlPath, 'utf8')) as Record<string, unknown>;
+    const projectServers = projectConfig.mcp_servers as Record<string, unknown>;
+    const projectHttp = projectServers['codex-project-http'] as Record<string, unknown>;
+    assert.equal(projectHttp.url, 'https://codex.example.com/mcp');
+
+    await assert.rejects(
+      providerMcpService.upsertProviderMcpServer('codex', {
+        name: 'codex-local',
+        scope: 'local',
+        transport: 'stdio',
+        command: 'node',
+      }),
+      (error: unknown) =>
+        error instanceof AppError &&
+        error.code === 'MCP_SCOPE_NOT_SUPPORTED' &&
+        error.statusCode === 400,
+    );
+
+    await assert.rejects(
+      providerMcpService.upsertProviderMcpServer('codex', {
+        name: 'codex-sse',
+        scope: 'project',
+        transport: 'sse',
+        url: 'https://example.com/sse',
+        workspacePath,
+      }),
+      (error: unknown) =>
+        error instanceof AppError &&
+        error.code === 'MCP_TRANSPORT_NOT_SUPPORTED' &&
+        error.statusCode === 400,
+    );
+  } finally {
+    restoreHomeDir();
+    await fs.rm(tempRoot, { recursive: true, force: true });
+  }
+});
+
+/**
+ * This test covers Gemini/Cursor MCP JSON formats and user/project scope persistence.
+ */
+test('providerMcpService handles gemini and cursor MCP JSON config formats', { concurrency: false }, async () => {
+  const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'llm-mcp-gc-'));
+  const workspacePath = path.join(tempRoot, 'workspace');
+  await fs.mkdir(workspacePath, { recursive: true });
+
+  const restoreHomeDir = patchHomeDir(tempRoot);
+  try {
+    await providerMcpService.upsertProviderMcpServer('gemini', {
+      name: 'gemini-stdio',
+      scope: 'user',
+      transport: 'stdio',
+      command: 'node',
+      args: ['server.js'],
+      env: { TOKEN: '$TOKEN' },
+      cwd: './server',
+    });
+
+    await providerMcpService.upsertProviderMcpServer('gemini', {
+      name: 'gemini-http',
+      scope: 'project',
+      transport: 'http',
+      url: 'https://gemini.example.com/mcp',
+      headers: { Authorization: 'Bearer token' },
+      workspacePath,
+    });
+
+    await providerMcpService.upsertProviderMcpServer('cursor', {
+      name: 'cursor-stdio',
+      scope: 'project',
+      transport: 'stdio',
+      command: 'npx',
+      args: ['-y', 'mcp-server'],
+      env: { API_KEY: 'value' },
+      workspacePath,
+    });
+
+    await providerMcpService.upsertProviderMcpServer('cursor', {
+      name: 'cursor-http',
+      scope: 'user',
+      transport: 'http',
+      url: 'http://localhost:3333/mcp',
+      headers: { API_KEY: 'value' },
+    });
+
+    const geminiUserConfig = await readJson(path.join(tempRoot, '.gemini', 'settings.json'));
+    const geminiUserServer = (geminiUserConfig.mcpServers as Record<string, unknown>)['gemini-stdio'] as Record<string, unknown>;
+    assert.equal(geminiUserServer.command, 'node');
+    assert.equal(geminiUserServer.type, undefined);
+
+    const geminiProjectConfig = await readJson(path.join(workspacePath, '.gemini', 'settings.json'));
+    const geminiProjectServer = (geminiProjectConfig.mcpServers as Record<string, unknown>)['gemini-http'] as Record<string, unknown>;
+    assert.equal(geminiProjectServer.type, 'http');
+
+    const cursorUserConfig = await readJson(path.join(tempRoot, '.cursor', 'mcp.json'));
+    const cursorHttpServer = (cursorUserConfig.mcpServers as Record<string, unknown>)['cursor-http'] as Record<string, unknown>;
+    assert.equal(cursorHttpServer.url, 'http://localhost:3333/mcp');
+    assert.equal(cursorHttpServer.type, undefined);
+  } finally {
+    restoreHomeDir();
+    await fs.rm(tempRoot, { recursive: true, force: true });
+  }
+});
+
+/**
+ * This test covers the global MCP adder requirement: only http/stdio are allowed and
+ * one payload is written to all providers.
+ */
+test('providerMcpService global adder writes to all providers and rejects unsupported transports', { concurrency: false }, async () => {
+  const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'llm-mcp-global-'));
+  const workspacePath = path.join(tempRoot, 'workspace');
+  await fs.mkdir(workspacePath, { recursive: true });
+
+  const restoreHomeDir = patchHomeDir(tempRoot);
+  try {
+    const globalResult = await providerMcpService.addMcpServerToAllProviders({
+      name: 'global-http',
+      scope: 'project',
+      transport: 'http',
+      url: 'https://global.example.com/mcp',
+      workspacePath,
+    });
+
+    const expectCursorGlobal = process.platform !== 'win32';
+    assert.equal(globalResult.length, expectCursorGlobal ? 4 : 3);
+    assert.ok(globalResult.every((entry) => entry.created === true));
+
+    const claudeProject = await readJson(path.join(workspacePath, '.mcp.json'));
+    assert.ok((claudeProject.mcpServers as Record<string, unknown>)['global-http']);
+
+    const codexProject = TOML.parse(await fs.readFile(path.join(workspacePath, '.codex', 'config.toml'), 'utf8')) as Record<string, unknown>;
+    assert.ok((codexProject.mcp_servers as Record<string, unknown>)['global-http']);
+
+    const geminiProject = await readJson(path.join(workspacePath, '.gemini', 'settings.json'));
+    assert.ok((geminiProject.mcpServers as Record<string, unknown>)['global-http']);
+
+    if (expectCursorGlobal) {
+      const cursorProject = await readJson(path.join(workspacePath, '.cursor', 'mcp.json'));
+      assert.ok((cursorProject.mcpServers as Record<string, unknown>)['global-http']);
+    }
+
+    await assert.rejects(
+      providerMcpService.addMcpServerToAllProviders({
+        name: 'global-sse',
+        scope: 'project',
+        transport: 'sse',
+        url: 'https://example.com/sse',
+        workspacePath,
+      }),
+      (error: unknown) =>
+        error instanceof AppError &&
+        error.code === 'INVALID_GLOBAL_MCP_TRANSPORT' &&
+        error.statusCode === 400,
+    );
+  } finally {
+    restoreHomeDir();
+    await fs.rm(tempRoot, { recursive: true, force: true });
+  }
+});
+

server/openai-codex.js

@@ -14,6 +14,9 @@
  */
 
 import { Codex } from '@openai/codex-sdk';
+import { notifyRunFailed, notifyRunStopped } from './services/notification-orchestrator.js';
+import { sessionsService } from './modules/providers/services/sessions.service.js';
+import { createNormalizedMessage } from './shared/utils.js';
 
 // Track active sessions
 const activeCodexSessions = new Map();
@@ -191,6 +194,7 @@ function mapPermissionModeToCodexOptions(permissionMode) {
 export async function queryCodex(command, options = {}, ws) {
   const {
     sessionId,
+    sessionSummary,
     cwd,
     projectPath,
     model,
@@ -203,6 +207,7 @@ export async function queryCodex(command, options = {}, ws) {
   let codex;
   let thread;
   let currentSessionId = sessionId;
+  let terminalFailure = null;
   const abortController = new AbortController();
 
   try {
@@ -238,11 +243,7 @@ export async function queryCodex(command, options = {}, ws) {
     });
 
     // Send session created event
-    sendMessage(ws, {
-      type: 'session-created',
-      sessionId: currentSessionId,
-      provider: 'codex'
-    });
+    sendMessage(ws, createNormalizedMessage({ kind: 'session_created', newSessionId: currentSessionId, sessionId: currentSessionId, provider: 'codex' }));
 
     // Execute with streaming
     const streamedTurn = await thread.runStreamed(command, {
@@ -262,32 +263,41 @@ export async function queryCodex(command, options = {}, ws) {
 
       const transformed = transformCodexEvent(event);
 
-      sendMessage(ws, {
-        type: 'codex-response',
-        data: transformed,
-        sessionId: currentSessionId
-      });
+      // Normalize the transformed event into NormalizedMessage(s) via adapter
+      const normalizedMsgs = sessionsService.normalizeMessage('codex', transformed, currentSessionId);
+      for (const msg of normalizedMsgs) {
+        sendMessage(ws, msg);
+      }
+
+      if (event.type === 'turn.failed' && !terminalFailure) {
+        terminalFailure = event.error || new Error('Turn failed');
+        notifyRunFailed({
+          userId: ws?.userId || null,
+          provider: 'codex',
+          sessionId: currentSessionId,
+          sessionName: sessionSummary,
+          error: terminalFailure
+        });
+      }
 
       // Extract and send token usage if available (normalized to match Claude format)
       if (event.type === 'turn.completed' && event.usage) {
         const totalTokens = (event.usage.input_tokens || 0) + (event.usage.output_tokens || 0);
-        sendMessage(ws, {
-          type: 'token-budget',
-          data: {
-            used: totalTokens,
-            total: 200000 // Default context window for Codex models
-          },
-          sessionId: currentSessionId
-        });
+        sendMessage(ws, createNormalizedMessage({ kind: 'status', text: 'token_budget', tokenBudget: { used: totalTokens, total: 200000 }, sessionId: currentSessionId, provider: 'codex' }));
       }
     }
 
     // Send completion event
-    sendMessage(ws, {
-      type: 'codex-complete',
-      sessionId: currentSessionId,
-      actualSessionId: thread.id
-    });
+    if (!terminalFailure) {
+      sendMessage(ws, createNormalizedMessage({ kind: 'complete', actualSessionId: thread.id, sessionId: currentSessionId, provider: 'codex' }));
+      notifyRunStopped({
+        userId: ws?.userId || null,
+        provider: 'codex',
+        sessionId: currentSessionId,
+        sessionName: sessionSummary,
+        stopReason: 'completed'
+      });
+    }
 
   } catch (error) {
     const session = currentSessionId ? activeCodexSessions.get(currentSessionId) : null;
@@ -298,11 +308,16 @@ export async function queryCodex(command, options = {}, ws) {
 
     if (!wasAborted) {
       console.error('[Codex] Error:', error);
-      sendMessage(ws, {
-        type: 'codex-error',
-        error: error.message,
-        sessionId: currentSessionId
-      });
+      sendMessage(ws, createNormalizedMessage({ kind: 'error', content: error.message, sessionId: currentSessionId, provider: 'codex' }));
+      if (!terminalFailure) {
+        notifyRunFailed({
+          userId: ws?.userId || null,
+          provider: 'codex',
+          sessionId: currentSessionId,
+          sessionName: sessionSummary,
+          error
+        });
+      }
     }
 
   } finally {

server/projects.js

@@ -1014,7 +1014,7 @@ async function getSessionMessages(projectName, sessionId, limit = null, offset =
               messages.push(entry);
             }
           } catch (parseError) {
-            console.warn('Error parsing line:', parseError.message);
+            // Silently skip malformed JSONL lines (common with concurrent writes)
           }
         }
       }

server/routes/agent.js

@@ -450,9 +450,10 @@ async function cleanupProject(projectPath, sessionId = null) {
  * SSE Stream Writer - Adapts SDK/CLI output to Server-Sent Events
  */
 class SSEStreamWriter {
-  constructor(res) {
+  constructor(res, userId = null) {
     this.res = res;
     this.sessionId = null;
+    this.userId = userId;
     this.isSSEStreamWriter = true;  // Marker for transport detection
   }
 
@@ -474,6 +475,7 @@ class SSEStreamWriter {
 
   setSessionId(sessionId) {
     this.sessionId = sessionId;
+    this.send({ type: 'session-id', sessionId });
   }
 
   getSessionId() {
@@ -485,9 +487,10 @@ class SSEStreamWriter {
  * Non-streaming response collector
  */
 class ResponseCollector {
-  constructor() {
+  constructor(userId = null) {
     this.messages = [];
     this.sessionId = null;
+    this.userId = userId;
   }
 
   send(data) {
@@ -837,7 +840,7 @@ class ResponseCollector {
  *   }
  */
 router.post('/', validateExternalApiKey, async (req, res) => {
-  const { githubUrl, projectPath, message, provider = 'claude', model, githubToken, branchName } = req.body;
+  const { githubUrl, projectPath, message, provider = 'claude', model, githubToken, branchName, sessionId } = req.body;
 
   // Parse stream and cleanup as booleans (handle string "true"/"false" from curl)
   const stream = req.body.stream === undefined ? true : (req.body.stream === true || req.body.stream === 'true');
@@ -920,7 +923,7 @@ router.post('/', validateExternalApiKey, async (req, res) => {
       res.setHeader('Connection', 'keep-alive');
       res.setHeader('X-Accel-Buffering', 'no'); // Disable nginx buffering
 
-      writer = new SSEStreamWriter(res);
+      writer = new SSEStreamWriter(res, req.user.id);
 
       // Send initial status
       writer.send({
@@ -930,7 +933,7 @@ router.post('/', validateExternalApiKey, async (req, res) => {
       });
     } else {
       // Non-streaming mode: collect messages
-      writer = new ResponseCollector();
+      writer = new ResponseCollector(req.user.id);
 
       // Collect initial status message
       writer.send({
@@ -947,7 +950,7 @@ router.post('/', validateExternalApiKey, async (req, res) => {
       await queryClaudeSDK(message.trim(), {
         projectPath: finalProjectPath,
         cwd: finalProjectPath,
-        sessionId: null, // New session
+        sessionId: sessionId || null,
         model: model,
         permissionMode: 'bypassPermissions' // Bypass all permissions for API calls
       }, writer);
@@ -958,7 +961,7 @@ router.post('/', validateExternalApiKey, async (req, res) => {
       await spawnCursor(message.trim(), {
         projectPath: finalProjectPath,
         cwd: finalProjectPath,
-        sessionId: null, // New session
+        sessionId: sessionId || null,
         model: model || undefined,
         skipPermissions: true // Bypass permissions for Cursor
       }, writer);
@@ -968,7 +971,7 @@ router.post('/', validateExternalApiKey, async (req, res) => {
       await queryCodex(message.trim(), {
         projectPath: finalProjectPath,
         cwd: finalProjectPath,
-        sessionId: null,
+        sessionId: sessionId || null,
         model: model || CODEX_MODELS.DEFAULT,
         permissionMode: 'bypassPermissions'
       }, writer);
@@ -978,7 +981,7 @@ router.post('/', validateExternalApiKey, async (req, res) => {
       await spawnGemini(message.trim(), {
         projectPath: finalProjectPath,
         cwd: finalProjectPath,
-        sessionId: null,
+        sessionId: sessionId || null,
         model: model,
         skipPermissions: true // CLI mode bypasses permissions
       }, writer);
@@ -1122,7 +1125,7 @@ router.post('/', validateExternalApiKey, async (req, res) => {
           } else {
             prBody += `Agent task: ${message}`;
           }
-          prBody += '\n\n---\n*This pull request was automatically created by Claude Code UI Agent.*';
+          prBody += '\n\n---\n*This pull request was automatically created by CloudCLI.ai Agent.*';
 
           console.log(`📝 PR Title: ${prTitle}`);
 
@@ -1219,7 +1222,7 @@ router.post('/', validateExternalApiKey, async (req, res) => {
         res.setHeader('Cache-Control', 'no-cache');
         res.setHeader('Connection', 'keep-alive');
         res.setHeader('X-Accel-Buffering', 'no');
-        writer = new SSEStreamWriter(res);
+        writer = new SSEStreamWriter(res, req.user.id);
       }
 
       if (!res.writableEnded) {

server/routes/cli-auth.js

@@ -1,396 +0,0 @@
-import express from 'express';
-import { spawn } from 'child_process';
-import fs from 'fs/promises';
-import path from 'path';
-import os from 'os';
-
-const router = express.Router();
-
-router.get('/claude/status', async (req, res) => {
-  try {
-    const credentialsResult = await checkClaudeCredentials();
-
-    if (credentialsResult.authenticated) {
-      return res.json({
-        authenticated: true,
-        email: credentialsResult.email || 'Authenticated',
-        method: credentialsResult.method  // 'api_key' or 'credentials_file'
-      });
-    }
-
-    return res.json({
-      authenticated: false,
-      email: null,
-      method: null,
-      error: credentialsResult.error || 'Not authenticated'
-    });
-
-  } catch (error) {
-    console.error('Error checking Claude auth status:', error);
-    res.status(500).json({
-      authenticated: false,
-      email: null,
-      method: null,
-      error: error.message
-    });
-  }
-});
-
-router.get('/cursor/status', async (req, res) => {
-  try {
-    const result = await checkCursorStatus();
-
-    res.json({
-      authenticated: result.authenticated,
-      email: result.email,
-      error: result.error
-    });
-
-  } catch (error) {
-    console.error('Error checking Cursor auth status:', error);
-    res.status(500).json({
-      authenticated: false,
-      email: null,
-      error: error.message
-    });
-  }
-});
-
-router.get('/codex/status', async (req, res) => {
-  try {
-    const result = await checkCodexCredentials();
-
-    res.json({
-      authenticated: result.authenticated,
-      email: result.email,
-      error: result.error
-    });
-
-  } catch (error) {
-    console.error('Error checking Codex auth status:', error);
-    res.status(500).json({
-      authenticated: false,
-      email: null,
-      error: error.message
-    });
-  }
-});
-
-router.get('/gemini/status', async (req, res) => {
-  try {
-    const result = await checkGeminiCredentials();
-
-    res.json({
-      authenticated: result.authenticated,
-      email: result.email,
-      error: result.error
-    });
-
-  } catch (error) {
-    console.error('Error checking Gemini auth status:', error);
-    res.status(500).json({
-      authenticated: false,
-      email: null,
-      error: error.message
-    });
-  }
-});
-
-/**
- * Checks Claude authentication credentials using two methods with priority order:
- *
- * Priority 1: ANTHROPIC_API_KEY environment variable
- * Priority 2: ~/.claude/.credentials.json OAuth tokens
- *
- * The Claude Agent SDK prioritizes environment variables over authenticated subscriptions.
- * This matching behavior ensures consistency with how the SDK authenticates.
- *
- * References:
- * - https://support.claude.com/en/articles/12304248-managing-api-key-environment-variables-in-claude-code
- *   "Claude Code prioritizes environment variable API keys over authenticated subscriptions"
- * - https://platform.claude.com/docs/en/agent-sdk/overview
- *   SDK authentication documentation
- *
- * @returns {Promise<Object>} Authentication status with { authenticated, email, method }
- *   - authenticated: boolean indicating if valid credentials exist
- *   - email: user email or auth method identifier
- *   - method: 'api_key' for env var, 'credentials_file' for OAuth tokens
- */
-async function checkClaudeCredentials() {
-  // Priority 1: Check for ANTHROPIC_API_KEY environment variable
-  // The SDK checks this first and uses it if present, even if OAuth tokens exist.
-  // When set, API calls are charged via pay-as-you-go rates instead of subscription.
-  if (process.env.ANTHROPIC_API_KEY && process.env.ANTHROPIC_API_KEY.trim()) {
-    return {
-      authenticated: true,
-      email: 'API Key Auth',
-      method: 'api_key'
-    };
-  }
-
-  // Priority 2: Check ~/.claude/.credentials.json for OAuth tokens
-  // This is the standard authentication method used by Claude CLI after running
-  // 'claude /login' or 'claude setup-token' commands.
-  try {
-    const credPath = path.join(os.homedir(), '.claude', '.credentials.json');
-    const content = await fs.readFile(credPath, 'utf8');
-    const creds = JSON.parse(content);
-
-    const oauth = creds.claudeAiOauth;
-    if (oauth && oauth.accessToken) {
-      const isExpired = oauth.expiresAt && Date.now() >= oauth.expiresAt;
-
-      if (!isExpired) {
-        return {
-          authenticated: true,
-          email: creds.email || creds.user || null,
-          method: 'credentials_file'
-        };
-      }
-    }
-
-    return {
-      authenticated: false,
-      email: null,
-      method: null
-    };
-  } catch (error) {
-    return {
-      authenticated: false,
-      email: null,
-      method: null
-    };
-  }
-}
-
-function checkCursorStatus() {
-  return new Promise((resolve) => {
-    let processCompleted = false;
-
-    const timeout = setTimeout(() => {
-      if (!processCompleted) {
-        processCompleted = true;
-        if (childProcess) {
-          childProcess.kill();
-        }
-        resolve({
-          authenticated: false,
-          email: null,
-          error: 'Command timeout'
-        });
-      }
-    }, 5000);
-
-    let childProcess;
-    try {
-      childProcess = spawn('cursor-agent', ['status']);
-    } catch (err) {
-      clearTimeout(timeout);
-      processCompleted = true;
-      resolve({
-        authenticated: false,
-        email: null,
-        error: 'Cursor CLI not found or not installed'
-      });
-      return;
-    }
-
-    let stdout = '';
-    let stderr = '';
-
-    childProcess.stdout.on('data', (data) => {
-      stdout += data.toString();
-    });
-
-    childProcess.stderr.on('data', (data) => {
-      stderr += data.toString();
-    });
-
-    childProcess.on('close', (code) => {
-      if (processCompleted) return;
-      processCompleted = true;
-      clearTimeout(timeout);
-
-      if (code === 0) {
-        const emailMatch = stdout.match(/Logged in as ([a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,})/i);
-
-        if (emailMatch) {
-          resolve({
-            authenticated: true,
-            email: emailMatch[1],
-            output: stdout
-          });
-        } else if (stdout.includes('Logged in')) {
-          resolve({
-            authenticated: true,
-            email: 'Logged in',
-            output: stdout
-          });
-        } else {
-          resolve({
-            authenticated: false,
-            email: null,
-            error: 'Not logged in'
-          });
-        }
-      } else {
-        resolve({
-          authenticated: false,
-          email: null,
-          error: stderr || 'Not logged in'
-        });
-      }
-    });
-
-    childProcess.on('error', (err) => {
-      if (processCompleted) return;
-      processCompleted = true;
-      clearTimeout(timeout);
-
-      resolve({
-        authenticated: false,
-        email: null,
-        error: 'Cursor CLI not found or not installed'
-      });
-    });
-  });
-}
-
-async function checkCodexCredentials() {
-  try {
-    const authPath = path.join(os.homedir(), '.codex', 'auth.json');
-    const content = await fs.readFile(authPath, 'utf8');
-    const auth = JSON.parse(content);
-
-    // Tokens are nested under 'tokens' key
-    const tokens = auth.tokens || {};
-
-    // Check for valid tokens (id_token or access_token)
-    if (tokens.id_token || tokens.access_token) {
-      // Try to extract email from id_token JWT payload
-      let email = 'Authenticated';
-      if (tokens.id_token) {
-        try {
-          // JWT is base64url encoded: header.payload.signature
-          const parts = tokens.id_token.split('.');
-          if (parts.length >= 2) {
-            // Decode the payload (second part)
-            const payload = JSON.parse(Buffer.from(parts[1], 'base64url').toString('utf8'));
-            email = payload.email || payload.user || 'Authenticated';
-          }
-        } catch {
-          // If JWT decoding fails, use fallback
-          email = 'Authenticated';
-        }
-      }
-
-      return {
-        authenticated: true,
-        email
-      };
-    }
-
-    // Also check for OPENAI_API_KEY as fallback auth method
-    if (auth.OPENAI_API_KEY) {
-      return {
-        authenticated: true,
-        email: 'API Key Auth'
-      };
-    }
-
-    return {
-      authenticated: false,
-      email: null,
-      error: 'No valid tokens found'
-    };
-  } catch (error) {
-    if (error.code === 'ENOENT') {
-      return {
-        authenticated: false,
-        email: null,
-        error: 'Codex not configured'
-      };
-    }
-    return {
-      authenticated: false,
-      email: null,
-      error: error.message
-    };
-  }
-}
-
-async function checkGeminiCredentials() {
-  if (process.env.GEMINI_API_KEY && process.env.GEMINI_API_KEY.trim()) {
-    return {
-      authenticated: true,
-      email: 'API Key Auth'
-    };
-  }
-
-  try {
-    const credsPath = path.join(os.homedir(), '.gemini', 'oauth_creds.json');
-    const content = await fs.readFile(credsPath, 'utf8');
-    const creds = JSON.parse(content);
-
-    if (creds.access_token) {
-      let email = 'OAuth Session';
-
-      try {
-        // Validate token against Google API
-        const tokenRes = await fetch(`https://oauth2.googleapis.com/tokeninfo?access_token=${creds.access_token}`);
-        if (tokenRes.ok) {
-          const tokenInfo = await tokenRes.json();
-          if (tokenInfo.email) {
-            email = tokenInfo.email;
-          }
-        } else if (!creds.refresh_token) {
-          // Token invalid and no refresh token available
-          return {
-            authenticated: false,
-            email: null,
-            error: 'Access token invalid and no refresh token found'
-          };
-        } else {
-          // Token might be expired but we have a refresh token, so CLI will refresh it
-          try {
-            const accPath = path.join(os.homedir(), '.gemini', 'google_accounts.json');
-            const accContent = await fs.readFile(accPath, 'utf8');
-            const accounts = JSON.parse(accContent);
-            if (accounts.active) {
-              email = accounts.active;
-            }
-          } catch (e) { }
-        }
-      } catch (e) {
-        // Network error, fallback to checking local accounts file
-        try {
-          const accPath = path.join(os.homedir(), '.gemini', 'google_accounts.json');
-          const accContent = await fs.readFile(accPath, 'utf8');
-          const accounts = JSON.parse(accContent);
-          if (accounts.active) {
-            email = accounts.active;
-          }
-        } catch (err) { }
-      }
-
-      return {
-        authenticated: true,
-        email: email
-      };
-    }
-
-    return {
-      authenticated: false,
-      email: null,
-      error: 'No valid tokens found in oauth_creds'
-    };
-  } catch (error) {
-    return {
-      authenticated: false,
-      email: null,
-      error: 'Gemini CLI not configured'
-    };
-  }
-}
-
-export default router;

server/routes/codex.js

@@ -1,91 +1,9 @@
 import express from 'express';
-import { spawn } from 'child_process';
-import { promises as fs } from 'fs';
-import path from 'path';
-import os from 'os';
-import TOML from '@iarna/toml';
-import { getCodexSessions, getCodexSessionMessages, deleteCodexSession } from '../projects.js';
-import { applyCustomSessionNames, sessionNamesDb } from '../database/db.js';
+import { deleteCodexSession } from '../projects.js';
+import { sessionNamesDb } from '../database/db.js';
 
 const router = express.Router();
 
-function createCliResponder(res) {
-  let responded = false;
-  return (status, payload) => {
-    if (responded || res.headersSent) {
-      return;
-    }
-    responded = true;
-    res.status(status).json(payload);
-  };
-}
-
-router.get('/config', async (req, res) => {
-  try {
-    const configPath = path.join(os.homedir(), '.codex', 'config.toml');
-    const content = await fs.readFile(configPath, 'utf8');
-    const config = TOML.parse(content);
-
-    res.json({
-      success: true,
-      config: {
-        model: config.model || null,
-        mcpServers: config.mcp_servers || {},
-        approvalMode: config.approval_mode || 'suggest'
-      }
-    });
-  } catch (error) {
-    if (error.code === 'ENOENT') {
-      res.json({
-        success: true,
-        config: {
-          model: null,
-          mcpServers: {},
-          approvalMode: 'suggest'
-        }
-      });
-    } else {
-      console.error('Error reading Codex config:', error);
-      res.status(500).json({ success: false, error: error.message });
-    }
-  }
-});
-
-router.get('/sessions', async (req, res) => {
-  try {
-    const { projectPath } = req.query;
-
-    if (!projectPath) {
-      return res.status(400).json({ success: false, error: 'projectPath query parameter required' });
-    }
-
-    const sessions = await getCodexSessions(projectPath);
-    applyCustomSessionNames(sessions, 'codex');
-    res.json({ success: true, sessions });
-  } catch (error) {
-    console.error('Error fetching Codex sessions:', error);
-    res.status(500).json({ success: false, error: error.message });
-  }
-});
-
-router.get('/sessions/:sessionId/messages', async (req, res) => {
-  try {
-    const { sessionId } = req.params;
-    const { limit, offset } = req.query;
-
-    const result = await getCodexSessionMessages(
-      sessionId,
-      limit ? parseInt(limit, 10) : null,
-      offset ? parseInt(offset, 10) : 0
-    );
-
-    res.json({ success: true, ...result });
-  } catch (error) {
-    console.error('Error fetching Codex session messages:', error);
-    res.status(500).json({ success: false, error: error.message });
-  }
-});
-
 router.delete('/sessions/:sessionId', async (req, res) => {
   try {
     const { sessionId } = req.params;
@@ -98,250 +16,4 @@ router.delete('/sessions/:sessionId', async (req, res) => {
   }
 });
 
-// MCP Server Management Routes
-
-router.get('/mcp/cli/list', async (req, res) => {
-  try {
-    const respond = createCliResponder(res);
-    const proc = spawn('codex', ['mcp', 'list'], { stdio: ['pipe', 'pipe', 'pipe'] });
-
-    let stdout = '';
-    let stderr = '';
-
-    proc.stdout?.on('data', (data) => { stdout += data.toString(); });
-    proc.stderr?.on('data', (data) => { stderr += data.toString(); });
-
-    proc.on('close', (code) => {
-      if (code === 0) {
-        respond(200, { success: true, output: stdout, servers: parseCodexListOutput(stdout) });
-      } else {
-        respond(500, { error: 'Codex CLI command failed', details: stderr || `Exited with code ${code}` });
-      }
-    });
-
-    proc.on('error', (error) => {
-      const isMissing = error?.code === 'ENOENT';
-      respond(isMissing ? 503 : 500, {
-        error: isMissing ? 'Codex CLI not installed' : 'Failed to run Codex CLI',
-        details: error.message,
-        code: error.code
-      });
-    });
-  } catch (error) {
-    res.status(500).json({ error: 'Failed to list MCP servers', details: error.message });
-  }
-});
-
-router.post('/mcp/cli/add', async (req, res) => {
-  try {
-    const { name, command, args = [], env = {} } = req.body;
-
-    if (!name || !command) {
-      return res.status(400).json({ error: 'name and command are required' });
-    }
-
-    // Build: codex mcp add <name> [-e KEY=VAL]... -- <command> [args...]
-    let cliArgs = ['mcp', 'add', name];
-
-    Object.entries(env).forEach(([key, value]) => {
-      cliArgs.push('-e', `${key}=${value}`);
-    });
-
-    cliArgs.push('--', command);
-
-    if (args && args.length > 0) {
-      cliArgs.push(...args);
-    }
-
-    const respond = createCliResponder(res);
-    const proc = spawn('codex', cliArgs, { stdio: ['pipe', 'pipe', 'pipe'] });
-
-    let stdout = '';
-    let stderr = '';
-
-    proc.stdout?.on('data', (data) => { stdout += data.toString(); });
-    proc.stderr?.on('data', (data) => { stderr += data.toString(); });
-
-    proc.on('close', (code) => {
-      if (code === 0) {
-        respond(200, { success: true, output: stdout, message: `MCP server "${name}" added successfully` });
-      } else {
-        respond(400, { error: 'Codex CLI command failed', details: stderr || `Exited with code ${code}` });
-      }
-    });
-
-    proc.on('error', (error) => {
-      const isMissing = error?.code === 'ENOENT';
-      respond(isMissing ? 503 : 500, {
-        error: isMissing ? 'Codex CLI not installed' : 'Failed to run Codex CLI',
-        details: error.message,
-        code: error.code
-      });
-    });
-  } catch (error) {
-    res.status(500).json({ error: 'Failed to add MCP server', details: error.message });
-  }
-});
-
-router.delete('/mcp/cli/remove/:name', async (req, res) => {
-  try {
-    const { name } = req.params;
-
-    const respond = createCliResponder(res);
-    const proc = spawn('codex', ['mcp', 'remove', name], { stdio: ['pipe', 'pipe', 'pipe'] });
-
-    let stdout = '';
-    let stderr = '';
-
-    proc.stdout?.on('data', (data) => { stdout += data.toString(); });
-    proc.stderr?.on('data', (data) => { stderr += data.toString(); });
-
-    proc.on('close', (code) => {
-      if (code === 0) {
-        respond(200, { success: true, output: stdout, message: `MCP server "${name}" removed successfully` });
-      } else {
-        respond(400, { error: 'Codex CLI command failed', details: stderr || `Exited with code ${code}` });
-      }
-    });
-
-    proc.on('error', (error) => {
-      const isMissing = error?.code === 'ENOENT';
-      respond(isMissing ? 503 : 500, {
-        error: isMissing ? 'Codex CLI not installed' : 'Failed to run Codex CLI',
-        details: error.message,
-        code: error.code
-      });
-    });
-  } catch (error) {
-    res.status(500).json({ error: 'Failed to remove MCP server', details: error.message });
-  }
-});
-
-router.get('/mcp/cli/get/:name', async (req, res) => {
-  try {
-    const { name } = req.params;
-
-    const respond = createCliResponder(res);
-    const proc = spawn('codex', ['mcp', 'get', name], { stdio: ['pipe', 'pipe', 'pipe'] });
-
-    let stdout = '';
-    let stderr = '';
-
-    proc.stdout?.on('data', (data) => { stdout += data.toString(); });
-    proc.stderr?.on('data', (data) => { stderr += data.toString(); });
-
-    proc.on('close', (code) => {
-      if (code === 0) {
-        respond(200, { success: true, output: stdout, server: parseCodexGetOutput(stdout) });
-      } else {
-        respond(404, { error: 'Codex CLI command failed', details: stderr || `Exited with code ${code}` });
-      }
-    });
-
-    proc.on('error', (error) => {
-      const isMissing = error?.code === 'ENOENT';
-      respond(isMissing ? 503 : 500, {
-        error: isMissing ? 'Codex CLI not installed' : 'Failed to run Codex CLI',
-        details: error.message,
-        code: error.code
-      });
-    });
-  } catch (error) {
-    res.status(500).json({ error: 'Failed to get MCP server details', details: error.message });
-  }
-});
-
-router.get('/mcp/config/read', async (req, res) => {
-  try {
-    const configPath = path.join(os.homedir(), '.codex', 'config.toml');
-
-    let configData = null;
-
-    try {
-      const fileContent = await fs.readFile(configPath, 'utf8');
-      configData = TOML.parse(fileContent);
-    } catch (error) {
-      // Config file doesn't exist
-    }
-
-    if (!configData) {
-      return res.json({ success: true, configPath, servers: [] });    }
-
-    const servers = [];
-
-    if (configData.mcp_servers && typeof configData.mcp_servers === 'object') {
-      for (const [name, config] of Object.entries(configData.mcp_servers)) {
-        servers.push({
-          id: name,
-          name: name,
-          type: 'stdio',
-          scope: 'user',
-          config: {
-            command: config.command || '',
-            args: config.args || [],
-            env: config.env || {}
-          },
-          raw: config
-        });
-      }
-    }
-
-    res.json({ success: true, configPath, servers });
-  } catch (error) {
-    res.status(500).json({ error: 'Failed to read Codex configuration', details: error.message });
-  }
-});
-
-function parseCodexListOutput(output) {
-  const servers = [];
-  const lines = output.split('\n').filter(line => line.trim());
-
-  for (const line of lines) {
-    if (line.includes(':')) {
-      const colonIndex = line.indexOf(':');
-      const name = line.substring(0, colonIndex).trim();
-
-      if (!name) continue;
-
-      const rest = line.substring(colonIndex + 1).trim();
-      let description = rest;
-      let status = 'unknown';
-
-      if (rest.includes('✓') || rest.includes('✗')) {
-        const statusMatch = rest.match(/(.*?)\s*-\s*([✓✗].*)$/);
-        if (statusMatch) {
-          description = statusMatch[1].trim();
-          status = statusMatch[2].includes('✓') ? 'connected' : 'failed';
-        }
-      }
-
-      servers.push({ name, type: 'stdio', status, description });
-    }
-  }
-
-  return servers;
-}
-
-function parseCodexGetOutput(output) {
-  try {
-    const jsonMatch = output.match(/\{[\s\S]*\}/);
-    if (jsonMatch) {
-      return JSON.parse(jsonMatch[0]);
-    }
-
-    const server = { raw_output: output };
-    const lines = output.split('\n');
-
-    for (const line of lines) {
-      if (line.includes('Name:')) server.name = line.split(':')[1]?.trim();
-      else if (line.includes('Type:')) server.type = line.split(':')[1]?.trim();
-      else if (line.includes('Command:')) server.command = line.split(':')[1]?.trim();
-    }
-
-    return server;
-  } catch (error) {
-    return { raw_output: output, parse_error: error.message };
-  }
-}
-
 export default router;

server/routes/commands.js

@@ -1,13 +1,15 @@
 import express from 'express';
 import { promises as fs } from 'fs';
 import path from 'path';
-import { fileURLToPath } from 'url';
 import os from 'os';
 import { CLAUDE_MODELS, CURSOR_MODELS, CODEX_MODELS } from '../../shared/modelConstants.js';
 import { parseFrontmatter } from '../utils/frontmatter.js';
+import { findAppRoot, getModuleDir } from '../utils/runtime-paths.js';
 
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = path.dirname(__filename);
+const __dirname = getModuleDir(import.meta.url);
+// This route reads the top-level package.json for the status command, so it needs the real
+// app root even after compilation moves the route file under dist-server/server/routes.
+const APP_ROOT = findAppRoot(__dirname);
 
 const router = express.Router();
 
@@ -291,7 +293,7 @@ Custom commands can be created in:
 
   '/status': async (args, context) => {
     // Read version from package.json
-    const packageJsonPath = path.join(path.dirname(__dirname), '..', 'package.json');
+    const packageJsonPath = path.join(APP_ROOT, 'package.json');
     let version = 'unknown';
     let packageName = 'claude-code-ui';
 
@@ -449,55 +451,6 @@ router.post('/list', async (req, res) => {
   }
 });
 
-/**
- * POST /api/commands/load
- * Load a specific command file and return its content and metadata
- */
-router.post('/load', async (req, res) => {
-  try {
-    const { commandPath } = req.body;
-
-    if (!commandPath) {
-      return res.status(400).json({
-        error: 'Command path is required'
-      });
-    }
-
-    // Security: Prevent path traversal
-    const resolvedPath = path.resolve(commandPath);
-    if (!resolvedPath.startsWith(path.resolve(os.homedir())) &&
-        !resolvedPath.includes('.claude/commands')) {
-      return res.status(403).json({
-        error: 'Access denied',
-        message: 'Command must be in .claude/commands directory'
-      });
-    }
-
-    // Read and parse the command file
-    const content = await fs.readFile(commandPath, 'utf8');
-    const { data: metadata, content: commandContent } = parseFrontmatter(content);
-
-    res.json({
-      path: commandPath,
-      metadata,
-      content: commandContent
-    });
-  } catch (error) {
-    if (error.code === 'ENOENT') {
-      return res.status(404).json({
-        error: 'Command not found',
-        message: `Command file not found: ${req.body.commandPath}`
-      });
-    }
-
-    console.error('Error loading command:', error);
-    res.status(500).json({
-      error: 'Failed to load command',
-      message: error.message
-    });
-  }
-});
-
 /**
  * POST /api/commands/execute
  * Execute a command with argument replacement

server/routes/cursor.js

@@ -2,12 +2,7 @@ import express from 'express';
 import { promises as fs } from 'fs';
 import path from 'path';
 import os from 'os';
-import { spawn } from 'child_process';
-import sqlite3 from 'sqlite3';
-import { open } from 'sqlite';
-import crypto from 'crypto';
 import { CURSOR_MODELS } from '../../shared/modelConstants.js';
-import { applyCustomSessionNames } from '../database/db.js';
 
 const router = express.Router();
 
@@ -15,20 +10,20 @@ const router = express.Router();
 router.get('/config', async (req, res) => {
   try {
     const configPath = path.join(os.homedir(), '.cursor', 'cli-config.json');
-    
+
     try {
       const configContent = await fs.readFile(configPath, 'utf8');
       const config = JSON.parse(configContent);
-      
+
       res.json({
         success: true,
-        config: config,
-        path: configPath
+        config,
+        path: configPath,
       });
     } catch (error) {
       // Config doesn't exist or is invalid
       console.log('Cursor config not found or invalid:', error.message);
-      
+
       // Return default config
       res.json({
         success: true,
@@ -36,763 +31,23 @@ router.get('/config', async (req, res) => {
           version: 1,
           model: {
             modelId: CURSOR_MODELS.DEFAULT,
-            displayName: "GPT-5"
+            displayName: 'GPT-5',
           },
           permissions: {
             allow: [],
-            deny: []
-          }
+            deny: [],
+          },
         },
-        isDefault: true
+        isDefault: true,
       });
     }
   } catch (error) {
     console.error('Error reading Cursor config:', error);
-    res.status(500).json({ 
-      error: 'Failed to read Cursor configuration', 
-      details: error.message 
+    res.status(500).json({
+      error: 'Failed to read Cursor configuration',
+      details: error.message,
     });
   }
 });
 
-// POST /api/cursor/config - Update Cursor CLI configuration
-router.post('/config', async (req, res) => {
-  try {
-    const { permissions, model } = req.body;
-    const configPath = path.join(os.homedir(), '.cursor', 'cli-config.json');
-    
-    // Read existing config or create default
-    let config = {
-      version: 1,
-      editor: {
-        vimMode: false
-      },
-      hasChangedDefaultModel: false,
-      privacyCache: {
-        ghostMode: false,
-        privacyMode: 3,
-        updatedAt: Date.now()
-      }
-    };
-    
-    try {
-      const existing = await fs.readFile(configPath, 'utf8');
-      config = JSON.parse(existing);
-    } catch (error) {
-      // Config doesn't exist, use defaults
-      console.log('Creating new Cursor config');
-    }
-    
-    // Update permissions if provided
-    if (permissions) {
-      config.permissions = {
-        allow: permissions.allow || [],
-        deny: permissions.deny || []
-      };
-    }
-    
-    // Update model if provided
-    if (model) {
-      config.model = model;
-      config.hasChangedDefaultModel = true;
-    }
-    
-    // Ensure directory exists
-    const configDir = path.dirname(configPath);
-    await fs.mkdir(configDir, { recursive: true });
-    
-    // Write updated config
-    await fs.writeFile(configPath, JSON.stringify(config, null, 2));
-    
-    res.json({
-      success: true,
-      config: config,
-      message: 'Cursor configuration updated successfully'
-    });
-  } catch (error) {
-    console.error('Error updating Cursor config:', error);
-    res.status(500).json({ 
-      error: 'Failed to update Cursor configuration', 
-      details: error.message 
-    });
-  }
-});
-
-// GET /api/cursor/mcp - Read Cursor MCP servers configuration
-router.get('/mcp', async (req, res) => {
-  try {
-    const mcpPath = path.join(os.homedir(), '.cursor', 'mcp.json');
-    
-    try {
-      const mcpContent = await fs.readFile(mcpPath, 'utf8');
-      const mcpConfig = JSON.parse(mcpContent);
-      
-      // Convert to UI-friendly format
-      const servers = [];
-      if (mcpConfig.mcpServers && typeof mcpConfig.mcpServers === 'object') {
-        for (const [name, config] of Object.entries(mcpConfig.mcpServers)) {
-          const server = {
-            id: name,
-            name: name,
-            type: 'stdio',
-            scope: 'cursor',
-            config: {},
-            raw: config
-          };
-          
-          // Determine transport type and extract config
-          if (config.command) {
-            server.type = 'stdio';
-            server.config.command = config.command;
-            server.config.args = config.args || [];
-            server.config.env = config.env || {};
-          } else if (config.url) {
-            server.type = config.transport || 'http';
-            server.config.url = config.url;
-            server.config.headers = config.headers || {};
-          }
-          
-          servers.push(server);
-        }
-      }
-      
-      res.json({
-        success: true,
-        servers: servers,
-        path: mcpPath
-      });
-    } catch (error) {
-      // MCP config doesn't exist
-      console.log('Cursor MCP config not found:', error.message);
-      res.json({
-        success: true,
-        servers: [],
-        isDefault: true
-      });
-    }
-  } catch (error) {
-    console.error('Error reading Cursor MCP config:', error);
-    res.status(500).json({ 
-      error: 'Failed to read Cursor MCP configuration', 
-      details: error.message 
-    });
-  }
-});
-
-// POST /api/cursor/mcp/add - Add MCP server to Cursor configuration
-router.post('/mcp/add', async (req, res) => {
-  try {
-    const { name, type = 'stdio', command, args = [], url, headers = {}, env = {} } = req.body;
-    const mcpPath = path.join(os.homedir(), '.cursor', 'mcp.json');
-    
-    console.log(`➕ Adding MCP server to Cursor config: ${name}`);
-    
-    // Read existing config or create new
-    let mcpConfig = { mcpServers: {} };
-    
-    try {
-      const existing = await fs.readFile(mcpPath, 'utf8');
-      mcpConfig = JSON.parse(existing);
-      if (!mcpConfig.mcpServers) {
-        mcpConfig.mcpServers = {};
-      }
-    } catch (error) {
-      console.log('Creating new Cursor MCP config');
-    }
-    
-    // Build server config based on type
-    let serverConfig = {};
-    
-    if (type === 'stdio') {
-      serverConfig = {
-        command: command,
-        args: args,
-        env: env
-      };
-    } else if (type === 'http' || type === 'sse') {
-      serverConfig = {
-        url: url,
-        transport: type,
-        headers: headers
-      };
-    }
-    
-    // Add server to config
-    mcpConfig.mcpServers[name] = serverConfig;
-    
-    // Ensure directory exists
-    const mcpDir = path.dirname(mcpPath);
-    await fs.mkdir(mcpDir, { recursive: true });
-    
-    // Write updated config
-    await fs.writeFile(mcpPath, JSON.stringify(mcpConfig, null, 2));
-    
-    res.json({
-      success: true,
-      message: `MCP server "${name}" added to Cursor configuration`,
-      config: mcpConfig
-    });
-  } catch (error) {
-    console.error('Error adding MCP server to Cursor:', error);
-    res.status(500).json({ 
-      error: 'Failed to add MCP server', 
-      details: error.message 
-    });
-  }
-});
-
-// DELETE /api/cursor/mcp/:name - Remove MCP server from Cursor configuration
-router.delete('/mcp/:name', async (req, res) => {
-  try {
-    const { name } = req.params;
-    const mcpPath = path.join(os.homedir(), '.cursor', 'mcp.json');
-    
-    console.log(`🗑️ Removing MCP server from Cursor config: ${name}`);
-    
-    // Read existing config
-    let mcpConfig = { mcpServers: {} };
-    
-    try {
-      const existing = await fs.readFile(mcpPath, 'utf8');
-      mcpConfig = JSON.parse(existing);
-    } catch (error) {
-      return res.status(404).json({ 
-        error: 'Cursor MCP configuration not found' 
-      });
-    }
-    
-    // Check if server exists
-    if (!mcpConfig.mcpServers || !mcpConfig.mcpServers[name]) {
-      return res.status(404).json({ 
-        error: `MCP server "${name}" not found in Cursor configuration` 
-      });
-    }
-    
-    // Remove server from config
-    delete mcpConfig.mcpServers[name];
-    
-    // Write updated config
-    await fs.writeFile(mcpPath, JSON.stringify(mcpConfig, null, 2));
-    
-    res.json({
-      success: true,
-      message: `MCP server "${name}" removed from Cursor configuration`,
-      config: mcpConfig
-    });
-  } catch (error) {
-    console.error('Error removing MCP server from Cursor:', error);
-    res.status(500).json({ 
-      error: 'Failed to remove MCP server', 
-      details: error.message 
-    });
-  }
-});
-
-// POST /api/cursor/mcp/add-json - Add MCP server using JSON format
-router.post('/mcp/add-json', async (req, res) => {
-  try {
-    const { name, jsonConfig } = req.body;
-    const mcpPath = path.join(os.homedir(), '.cursor', 'mcp.json');
-    
-    console.log(`➕ Adding MCP server to Cursor config via JSON: ${name}`);
-    
-    // Validate and parse JSON config
-    let parsedConfig;
-    try {
-      parsedConfig = typeof jsonConfig === 'string' ? JSON.parse(jsonConfig) : jsonConfig;
-    } catch (parseError) {
-      return res.status(400).json({ 
-        error: 'Invalid JSON configuration', 
-        details: parseError.message 
-      });
-    }
-    
-    // Read existing config or create new
-    let mcpConfig = { mcpServers: {} };
-    
-    try {
-      const existing = await fs.readFile(mcpPath, 'utf8');
-      mcpConfig = JSON.parse(existing);
-      if (!mcpConfig.mcpServers) {
-        mcpConfig.mcpServers = {};
-      }
-    } catch (error) {
-      console.log('Creating new Cursor MCP config');
-    }
-    
-    // Add server to config
-    mcpConfig.mcpServers[name] = parsedConfig;
-    
-    // Ensure directory exists
-    const mcpDir = path.dirname(mcpPath);
-    await fs.mkdir(mcpDir, { recursive: true });
-    
-    // Write updated config
-    await fs.writeFile(mcpPath, JSON.stringify(mcpConfig, null, 2));
-    
-    res.json({
-      success: true,
-      message: `MCP server "${name}" added to Cursor configuration via JSON`,
-      config: mcpConfig
-    });
-  } catch (error) {
-    console.error('Error adding MCP server to Cursor via JSON:', error);
-    res.status(500).json({ 
-      error: 'Failed to add MCP server', 
-      details: error.message 
-    });
-  }
-});
-
-// GET /api/cursor/sessions - Get Cursor sessions from SQLite database
-router.get('/sessions', async (req, res) => {
-  try {
-    const { projectPath } = req.query;
-    
-    // Calculate cwdID hash for the project path (Cursor uses MD5 hash)
-    const cwdId = crypto.createHash('md5').update(projectPath || process.cwd()).digest('hex');
-    const cursorChatsPath = path.join(os.homedir(), '.cursor', 'chats', cwdId);
-    
-    
-    // Check if the directory exists
-    try {
-      await fs.access(cursorChatsPath);
-    } catch (error) {
-      // No sessions for this project
-      return res.json({ 
-        success: true, 
-        sessions: [],
-        cwdId: cwdId,
-        path: cursorChatsPath
-      });
-    }
-    
-    // List all session directories
-    const sessionDirs = await fs.readdir(cursorChatsPath);
-    const sessions = [];
-    
-    for (const sessionId of sessionDirs) {
-      const sessionPath = path.join(cursorChatsPath, sessionId);
-      const storeDbPath = path.join(sessionPath, 'store.db');
-      let dbStatMtimeMs = null;
-      
-      try {
-        // Check if store.db exists
-        await fs.access(storeDbPath);
-        
-        // Capture store.db mtime as a reliable fallback timestamp (last activity)
-        try {
-          const stat = await fs.stat(storeDbPath);
-          dbStatMtimeMs = stat.mtimeMs;
-        } catch (_) {}
-
-        // Open SQLite database
-        const db = await open({
-          filename: storeDbPath,
-          driver: sqlite3.Database,
-          mode: sqlite3.OPEN_READONLY
-        });
-        
-        // Get metadata from meta table
-        const metaRows = await db.all(`
-          SELECT key, value FROM meta
-        `);
-        
-        let sessionData = {
-          id: sessionId,
-          name: 'Untitled Session',
-          createdAt: null,
-          mode: null,
-          projectPath: projectPath,
-          lastMessage: null,
-          messageCount: 0
-        };
-        
-        // Parse meta table entries
-        for (const row of metaRows) {
-          if (row.value) {
-            try {
-              // Try to decode as hex-encoded JSON
-              const hexMatch = row.value.toString().match(/^[0-9a-fA-F]+$/);
-              if (hexMatch) {
-                const jsonStr = Buffer.from(row.value, 'hex').toString('utf8');
-                const data = JSON.parse(jsonStr);
-                
-                if (row.key === 'agent') {
-                  sessionData.name = data.name || sessionData.name;
-                  // Normalize createdAt to ISO string in milliseconds
-                  let createdAt = data.createdAt;
-                  if (typeof createdAt === 'number') {
-                    if (createdAt < 1e12) {
-                      createdAt = createdAt * 1000; // seconds -> ms
-                    }
-                    sessionData.createdAt = new Date(createdAt).toISOString();
-                  } else if (typeof createdAt === 'string') {
-                    const n = Number(createdAt);
-                    if (!Number.isNaN(n)) {
-                      const ms = n < 1e12 ? n * 1000 : n;
-                      sessionData.createdAt = new Date(ms).toISOString();
-                    } else {
-                      // Assume it's already an ISO/date string
-                      const d = new Date(createdAt);
-                      sessionData.createdAt = isNaN(d.getTime()) ? null : d.toISOString();
-                    }
-                  } else {
-                    sessionData.createdAt = sessionData.createdAt || null;
-                  }
-                  sessionData.mode = data.mode;
-                  sessionData.agentId = data.agentId;
-                  sessionData.latestRootBlobId = data.latestRootBlobId;
-                }
-              } else {
-                // If not hex, use raw value for simple keys
-                if (row.key === 'name') {
-                  sessionData.name = row.value.toString();
-                }
-              }
-            } catch (e) {
-              console.log(`Could not parse meta value for key ${row.key}:`, e.message);
-            }
-          }
-        }
-        
-        // Get message count from JSON blobs only (actual messages, not DAG structure)
-        try {
-          const blobCount = await db.get(`
-            SELECT COUNT(*) as count 
-            FROM blobs 
-            WHERE substr(data, 1, 1) = X'7B'
-          `);
-          sessionData.messageCount = blobCount.count;
-          
-          // Get the most recent JSON blob for preview (actual message, not DAG structure)
-          const lastBlob = await db.get(`
-            SELECT data FROM blobs 
-            WHERE substr(data, 1, 1) = X'7B'
-            ORDER BY rowid DESC 
-            LIMIT 1
-          `);
-          
-          if (lastBlob && lastBlob.data) {
-            try {
-              // Try to extract readable preview from blob (may contain binary with embedded JSON)
-              const raw = lastBlob.data.toString('utf8');
-              let preview = '';
-              // Attempt direct JSON parse
-              try {
-                const parsed = JSON.parse(raw);
-                if (parsed?.content) {
-                  if (Array.isArray(parsed.content)) {
-                    const firstText = parsed.content.find(p => p?.type === 'text' && p.text)?.text || '';
-                    preview = firstText;
-                  } else if (typeof parsed.content === 'string') {
-                    preview = parsed.content;
-                  }
-                }
-              } catch (_) {}
-              if (!preview) {
-                // Strip non-printable and try to find JSON chunk
-                const cleaned = raw.replace(/[^\x09\x0A\x0D\x20-\x7E]/g, '');
-                const s = cleaned;
-                const start = s.indexOf('{');
-                const end = s.lastIndexOf('}');
-                if (start !== -1 && end > start) {
-                  const jsonStr = s.slice(start, end + 1);
-                  try {
-                    const parsed = JSON.parse(jsonStr);
-                    if (parsed?.content) {
-                      if (Array.isArray(parsed.content)) {
-                        const firstText = parsed.content.find(p => p?.type === 'text' && p.text)?.text || '';
-                        preview = firstText;
-                      } else if (typeof parsed.content === 'string') {
-                        preview = parsed.content;
-                      }
-                    }
-                  } catch (_) {
-                    preview = s;
-                  }
-                } else {
-                  preview = s;
-                }
-              }
-              if (preview && preview.length > 0) {
-                sessionData.lastMessage = preview.substring(0, 100) + (preview.length > 100 ? '...' : '');
-              }
-            } catch (e) {
-              console.log('Could not parse blob data:', e.message);
-            }
-          }
-        } catch (e) {
-          console.log('Could not read blobs:', e.message);
-        }
-        
-        await db.close();
-
-        // Finalize createdAt: use parsed meta value when valid, else fall back to store.db mtime
-        if (!sessionData.createdAt) {
-          if (dbStatMtimeMs && Number.isFinite(dbStatMtimeMs)) {
-            sessionData.createdAt = new Date(dbStatMtimeMs).toISOString();
-          }
-        }
-        
-        sessions.push(sessionData);
-        
-      } catch (error) {
-        console.log(`Could not read session ${sessionId}:`, error.message);
-      }
-    }
-    
-    // Fallback: ensure createdAt is a valid ISO string (use session directory mtime as last resort)
-    for (const s of sessions) {
-      if (!s.createdAt) {
-        try {
-          const sessionDir = path.join(cursorChatsPath, s.id);
-          const st = await fs.stat(sessionDir);
-          s.createdAt = new Date(st.mtimeMs).toISOString();
-        } catch {
-          s.createdAt = new Date().toISOString();
-        }
-      }
-    }
-    // Sort sessions by creation date (newest first)
-    sessions.sort((a, b) => {
-      if (!a.createdAt) return 1;
-      if (!b.createdAt) return -1;
-      return new Date(b.createdAt) - new Date(a.createdAt);
-    });
-    
-    applyCustomSessionNames(sessions, 'cursor');
-
-    res.json({
-      success: true,
-      sessions: sessions,
-      cwdId: cwdId,
-      path: cursorChatsPath
-    });
-    
-  } catch (error) {
-    console.error('Error reading Cursor sessions:', error);
-    res.status(500).json({ 
-      error: 'Failed to read Cursor sessions', 
-      details: error.message 
-    });
-  }
-});
-
-// GET /api/cursor/sessions/:sessionId - Get specific Cursor session from SQLite
-router.get('/sessions/:sessionId', async (req, res) => {
-  try {
-    const { sessionId } = req.params;
-    const { projectPath } = req.query;
-    
-    // Calculate cwdID hash for the project path
-    const cwdId = crypto.createHash('md5').update(projectPath || process.cwd()).digest('hex');
-    const storeDbPath = path.join(os.homedir(), '.cursor', 'chats', cwdId, sessionId, 'store.db');
-    
-    
-    // Open SQLite database
-    const db = await open({
-      filename: storeDbPath,
-      driver: sqlite3.Database,
-      mode: sqlite3.OPEN_READONLY
-    });
-    
-    // Get all blobs to build the DAG structure
-    const allBlobs = await db.all(`
-      SELECT rowid, id, data FROM blobs
-    `);
-    
-    // Build the DAG structure from parent-child relationships
-    const blobMap = new Map(); // id -> blob data
-    const parentRefs = new Map(); // blob id -> [parent blob ids]
-    const childRefs = new Map(); // blob id -> [child blob ids]
-    const jsonBlobs = []; // Clean JSON messages
-    
-    for (const blob of allBlobs) {
-      blobMap.set(blob.id, blob);
-      
-      // Check if this is a JSON blob (actual message) or protobuf (DAG structure)
-      if (blob.data && blob.data[0] === 0x7B) { // Starts with '{' - JSON blob
-        try {
-          const parsed = JSON.parse(blob.data.toString('utf8'));
-          jsonBlobs.push({ ...blob, parsed });
-        } catch (e) {
-          console.log('Failed to parse JSON blob:', blob.rowid);
-        }
-      } else if (blob.data) { // Protobuf blob - extract parent references
-        const parents = [];
-        let i = 0;
-        
-        // Scan for parent references (0x0A 0x20 followed by 32-byte hash)
-        while (i < blob.data.length - 33) {
-          if (blob.data[i] === 0x0A && blob.data[i+1] === 0x20) {
-            const parentHash = blob.data.slice(i+2, i+34).toString('hex');
-            if (blobMap.has(parentHash)) {
-              parents.push(parentHash);
-            }
-            i += 34;
-          } else {
-            i++;
-          }
-        }
-        
-        if (parents.length > 0) {
-          parentRefs.set(blob.id, parents);
-          // Update child references
-          for (const parentId of parents) {
-            if (!childRefs.has(parentId)) {
-              childRefs.set(parentId, []);
-            }
-            childRefs.get(parentId).push(blob.id);
-          }
-        }
-      }
-    }
-    
-    // Perform topological sort to get chronological order
-    const visited = new Set();
-    const sorted = [];
-    
-    // DFS-based topological sort
-    function visit(nodeId) {
-      if (visited.has(nodeId)) return;
-      visited.add(nodeId);
-      
-      // Visit all parents first (dependencies)
-      const parents = parentRefs.get(nodeId) || [];
-      for (const parentId of parents) {
-        visit(parentId);
-      }
-      
-      // Add this node after all its parents
-      const blob = blobMap.get(nodeId);
-      if (blob) {
-        sorted.push(blob);
-      }
-    }
-    
-    // Start with nodes that have no parents (roots)
-    for (const blob of allBlobs) {
-      if (!parentRefs.has(blob.id)) {
-        visit(blob.id);
-      }
-    }
-    
-    // Visit any remaining nodes (disconnected components)
-    for (const blob of allBlobs) {
-      visit(blob.id);
-    }
-    
-    // Now extract JSON messages in the order they appear in the sorted DAG
-    const messageOrder = new Map(); // JSON blob id -> order index
-    let orderIndex = 0;
-    
-    for (const blob of sorted) {
-      // Check if this blob references any JSON messages
-      if (blob.data && blob.data[0] !== 0x7B) { // Protobuf blob
-        // Look for JSON blob references
-        for (const jsonBlob of jsonBlobs) {
-          try {
-            const jsonIdBytes = Buffer.from(jsonBlob.id, 'hex');
-            if (blob.data.includes(jsonIdBytes)) {
-              if (!messageOrder.has(jsonBlob.id)) {
-                messageOrder.set(jsonBlob.id, orderIndex++);
-              }
-            }
-          } catch (e) {
-            // Skip if can't convert ID
-          }
-        }
-      }
-    }
-    
-    // Sort JSON blobs by their appearance order in the DAG
-    const sortedJsonBlobs = jsonBlobs.sort((a, b) => {
-      const orderA = messageOrder.get(a.id) ?? Number.MAX_SAFE_INTEGER;
-      const orderB = messageOrder.get(b.id) ?? Number.MAX_SAFE_INTEGER;
-      if (orderA !== orderB) return orderA - orderB;
-      // Fallback to rowid if not in order map
-      return a.rowid - b.rowid;
-    });
-    
-    // Use sorted JSON blobs
-    const blobs = sortedJsonBlobs.map((blob, idx) => ({
-      ...blob,
-      sequence_num: idx + 1,
-      original_rowid: blob.rowid
-    }));
-    
-    // Get metadata from meta table
-    const metaRows = await db.all(`
-      SELECT key, value FROM meta
-    `);
-    
-    // Parse metadata
-    let metadata = {};
-    for (const row of metaRows) {
-      if (row.value) {
-        try {
-          // Try to decode as hex-encoded JSON
-          const hexMatch = row.value.toString().match(/^[0-9a-fA-F]+$/);
-          if (hexMatch) {
-            const jsonStr = Buffer.from(row.value, 'hex').toString('utf8');
-            metadata[row.key] = JSON.parse(jsonStr);
-          } else {
-            metadata[row.key] = row.value.toString();
-          }
-        } catch (e) {
-          metadata[row.key] = row.value.toString();
-        }
-      }
-    }
-    
-    // Extract messages from sorted JSON blobs
-    const messages = [];
-    for (const blob of blobs) {
-      try {
-        // We already parsed JSON blobs earlier
-        const parsed = blob.parsed;
-        
-        if (parsed) {
-          // Filter out ONLY system messages at the server level
-          // Check both direct role and nested message.role
-          const role = parsed?.role || parsed?.message?.role;
-          if (role === 'system') {
-            continue; // Skip only system messages
-          }
-          messages.push({ 
-            id: blob.id, 
-            sequence: blob.sequence_num,
-            rowid: blob.original_rowid, 
-            content: parsed 
-          });
-        }
-      } catch (e) {
-        // Skip blobs that cause errors
-        console.log(`Skipping blob ${blob.id}: ${e.message}`);
-      }
-    }
-    
-    await db.close();
-    
-    res.json({ 
-      success: true, 
-      session: {
-        id: sessionId,
-        projectPath: projectPath,
-        messages: messages,
-        metadata: metadata,
-        cwdId: cwdId
-      }
-    });
-    
-  } catch (error) {
-    console.error('Error reading Cursor session:', error);
-    res.status(500).json({ 
-      error: 'Failed to read Cursor session', 
-      details: error.message 
-    });
-  }
-});
-
-export default router;
+export default router;

server/routes/gemini.js

@@ -1,39 +1,9 @@
 import express from 'express';
 import sessionManager from '../sessionManager.js';
 import { sessionNamesDb } from '../database/db.js';
-import { getGeminiCliSessionMessages } from '../projects.js';
 
 const router = express.Router();
 
-router.get('/sessions/:sessionId/messages', async (req, res) => {
-    try {
-        const { sessionId } = req.params;
-
-        if (!sessionId || typeof sessionId !== 'string' || !/^[a-zA-Z0-9_.-]{1,100}$/.test(sessionId)) {
-            return res.status(400).json({ success: false, error: 'Invalid session ID format' });
-        }
-
-        let messages = sessionManager.getSessionMessages(sessionId);
-
-        // Fallback to Gemini CLI sessions on disk
-        if (messages.length === 0) {
-            messages = await getGeminiCliSessionMessages(sessionId);
-        }
-
-        res.json({
-            success: true,
-            messages: messages,
-            total: messages.length,
-            hasMore: false,
-            offset: 0,
-            limit: messages.length
-        });
-    } catch (error) {
-        console.error('Error fetching Gemini session messages:', error);
-        res.status(500).json({ success: false, error: error.message });
-    }
-});
-
 router.delete('/sessions/:sessionId', async (req, res) => {
     try {
         const { sessionId } = req.params;

server/routes/git.js

@@ -651,26 +651,28 @@ router.get('/branches', async (req, res) => {
     
     // Get all branches
     const { stdout } = await spawnAsync('git', ['branch', '-a'], { cwd: projectPath });
-    
-    // Parse branches
-    const branches = stdout
+
+    const rawLines = stdout
       .split('\n')
-      .map(branch => branch.trim())
-      .filter(branch => branch && !branch.includes('->')) // Remove empty lines and HEAD pointer
-      .map(branch => {
-        // Remove asterisk from current branch
-        if (branch.startsWith('* ')) {
-          return branch.substring(2);
-        }
-        // Remove remotes/ prefix
-        if (branch.startsWith('remotes/origin/')) {
-          return branch.substring(15);
-        }
-        return branch;
-      })
-      .filter((branch, index, self) => self.indexOf(branch) === index); // Remove duplicates
-    
-    res.json({ branches });
+      .map(b => b.trim())
+      .filter(b => b && !b.includes('->'));
+
+    // Local branches (may start with '* ' for current)
+    const localBranches = rawLines
+      .filter(b => !b.startsWith('remotes/'))
+      .map(b => (b.startsWith('* ') ? b.substring(2) : b));
+
+    // Remote branches — strip 'remotes/<remote>/' prefix
+    const remoteBranches = rawLines
+      .filter(b => b.startsWith('remotes/'))
+      .map(b => b.replace(/^remotes\/[^/]+\//, ''))
+      .filter(name => !localBranches.includes(name)); // skip if already a local branch
+
+    // Backward-compat flat list (local + unique remotes, deduplicated)
+    const branches = [...localBranches, ...remoteBranches]
+      .filter((b, i, arr) => arr.indexOf(b) === i);
+
+    res.json({ branches, localBranches, remoteBranches });
   } catch (error) {
     console.error('Git branches error:', error);
     res.json({ error: error.message });
@@ -721,6 +723,32 @@ router.post('/create-branch', async (req, res) => {
   }
 });
 
+// Delete a local branch
+router.post('/delete-branch', async (req, res) => {
+  const { project, branch } = req.body;
+
+  if (!project || !branch) {
+    return res.status(400).json({ error: 'Project name and branch name are required' });
+  }
+
+  try {
+    const projectPath = await getActualProjectPath(project);
+    await validateGitRepository(projectPath);
+
+    // Safety: cannot delete the currently checked-out branch
+    const { stdout: currentBranch } = await spawnAsync('git', ['branch', '--show-current'], { cwd: projectPath });
+    if (currentBranch.trim() === branch) {
+      return res.status(400).json({ error: 'Cannot delete the currently checked-out branch' });
+    }
+
+    const { stdout } = await spawnAsync('git', ['branch', '-d', branch], { cwd: projectPath });
+    res.json({ success: true, output: stdout });
+  } catch (error) {
+    console.error('Git delete branch error:', error);
+    res.status(500).json({ error: error.message });
+  }
+});
+
 // Get recent commits
 router.get('/commits', async (req, res) => {
   const { project, limit = 10 } = req.query;
@@ -740,7 +768,7 @@ router.get('/commits', async (req, res) => {
     // Get commit log with stats
     const { stdout } = await spawnAsync(
       'git',
-      ['log', '--pretty=format:%H|%an|%ae|%ad|%s', '--date=relative', '-n', String(safeLimit)],
+      ['log', '--pretty=format:%H|%an|%ae|%ad|%s', '--date=iso-strict', '-n', String(safeLimit)],
       { cwd: projectPath },
     );
     

server/routes/mcp-utils.js

@@ -7,7 +7,7 @@
  */
 
 import express from 'express';
-import { detectTaskMasterMCPServer, getAllMCPServers } from '../utils/mcp-detector.js';
+import { detectTaskMasterMCPServer } from '../utils/mcp-detector.js';
 
 const router = express.Router();
 
@@ -28,21 +28,4 @@ router.get('/taskmaster-server', async (req, res) => {
     }
 });
 
-/**
- * GET /api/mcp-utils/all-servers
- * Get all configured MCP servers
- */
-router.get('/all-servers', async (req, res) => {
-    try {
-        const result = await getAllMCPServers();
-        res.json(result);
-    } catch (error) {
-        console.error('MCP servers detection error:', error);
-        res.status(500).json({
-            error: 'Failed to get MCP servers',
-            message: error.message
-        });
-    }
-});
-
-export default router;
+export default router;

server/routes/mcp.js

@@ -1,552 +0,0 @@
-import express from 'express';
-import { promises as fs } from 'fs';
-import path from 'path';
-import os from 'os';
-import { fileURLToPath } from 'url';
-import { dirname } from 'path';
-import { spawn } from 'child_process';
-
-const router = express.Router();
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
-
-// Claude CLI command routes
-
-// GET /api/mcp/cli/list - List MCP servers using Claude CLI
-router.get('/cli/list', async (req, res) => {
-  try {
-    console.log('📋 Listing MCP servers using Claude CLI');
-    
-    const { spawn } = await import('child_process');
-    const { promisify } = await import('util');
-    const exec = promisify(spawn);
-    
-    const process = spawn('claude', ['mcp', 'list'], {
-      stdio: ['pipe', 'pipe', 'pipe']
-    });
-    
-    let stdout = '';
-    let stderr = '';
-    
-    process.stdout.on('data', (data) => {
-      stdout += data.toString();
-    });
-    
-    process.stderr.on('data', (data) => {
-      stderr += data.toString();
-    });
-    
-    process.on('close', (code) => {
-      if (code === 0) {
-        res.json({ success: true, output: stdout, servers: parseClaudeListOutput(stdout) });
-      } else {
-        console.error('Claude CLI error:', stderr);
-        res.status(500).json({ error: 'Claude CLI command failed', details: stderr });
-      }
-    });
-    
-    process.on('error', (error) => {
-      console.error('Error running Claude CLI:', error);
-      res.status(500).json({ error: 'Failed to run Claude CLI', details: error.message });
-    });
-  } catch (error) {
-    console.error('Error listing MCP servers via CLI:', error);
-    res.status(500).json({ error: 'Failed to list MCP servers', details: error.message });
-  }
-});
-
-// POST /api/mcp/cli/add - Add MCP server using Claude CLI
-router.post('/cli/add', async (req, res) => {
-  try {
-    const { name, type = 'stdio', command, args = [], url, headers = {}, env = {}, scope = 'user', projectPath } = req.body;
-    
-    console.log(`➕ Adding MCP server using Claude CLI (${scope} scope):`, name);
-    
-    const { spawn } = await import('child_process');
-    
-    let cliArgs = ['mcp', 'add'];
-    
-    // Add scope flag
-    cliArgs.push('--scope', scope);
-    
-    if (type === 'http') {
-      cliArgs.push('--transport', 'http', name, url);
-      // Add headers if provided
-      Object.entries(headers).forEach(([key, value]) => {
-        cliArgs.push('--header', `${key}: ${value}`);
-      });
-    } else if (type === 'sse') {
-      cliArgs.push('--transport', 'sse', name, url);
-      // Add headers if provided
-      Object.entries(headers).forEach(([key, value]) => {
-        cliArgs.push('--header', `${key}: ${value}`);
-      });
-    } else {
-      // stdio (default): claude mcp add --scope user <name> <command> [args...]
-      cliArgs.push(name);
-      // Add environment variables
-      Object.entries(env).forEach(([key, value]) => {
-        cliArgs.push('-e', `${key}=${value}`);
-      });
-      cliArgs.push(command);
-      if (args && args.length > 0) {
-        cliArgs.push(...args);
-      }
-    }
-    
-    console.log('🔧 Running Claude CLI command:', 'claude', cliArgs.join(' '));
-    
-    // For local scope, we need to run the command in the project directory
-    const spawnOptions = {
-      stdio: ['pipe', 'pipe', 'pipe']
-    };
-    
-    if (scope === 'local' && projectPath) {
-      spawnOptions.cwd = projectPath;
-      console.log('📁 Running in project directory:', projectPath);
-    }
-    
-    const process = spawn('claude', cliArgs, spawnOptions);
-    
-    let stdout = '';
-    let stderr = '';
-    
-    process.stdout.on('data', (data) => {
-      stdout += data.toString();
-    });
-    
-    process.stderr.on('data', (data) => {
-      stderr += data.toString();
-    });
-    
-    process.on('close', (code) => {
-      if (code === 0) {
-        res.json({ success: true, output: stdout, message: `MCP server "${name}" added successfully` });
-      } else {
-        console.error('Claude CLI error:', stderr);
-        res.status(400).json({ error: 'Claude CLI command failed', details: stderr });
-      }
-    });
-    
-    process.on('error', (error) => {
-      console.error('Error running Claude CLI:', error);
-      res.status(500).json({ error: 'Failed to run Claude CLI', details: error.message });
-    });
-  } catch (error) {
-    console.error('Error adding MCP server via CLI:', error);
-    res.status(500).json({ error: 'Failed to add MCP server', details: error.message });
-  }
-});
-
-// POST /api/mcp/cli/add-json - Add MCP server using JSON format
-router.post('/cli/add-json', async (req, res) => {
-  try {
-    const { name, jsonConfig, scope = 'user', projectPath } = req.body;
-    
-    console.log('➕ Adding MCP server using JSON format:', name);
-    
-    // Validate and parse JSON config
-    let parsedConfig;
-    try {
-      parsedConfig = typeof jsonConfig === 'string' ? JSON.parse(jsonConfig) : jsonConfig;
-    } catch (parseError) {
-      return res.status(400).json({ 
-        error: 'Invalid JSON configuration', 
-        details: parseError.message 
-      });
-    }
-    
-    // Validate required fields
-    if (!parsedConfig.type) {
-      return res.status(400).json({ 
-        error: 'Invalid configuration', 
-        details: 'Missing required field: type' 
-      });
-    }
-    
-    if (parsedConfig.type === 'stdio' && !parsedConfig.command) {
-      return res.status(400).json({ 
-        error: 'Invalid configuration', 
-        details: 'stdio type requires a command field' 
-      });
-    }
-    
-    if ((parsedConfig.type === 'http' || parsedConfig.type === 'sse') && !parsedConfig.url) {
-      return res.status(400).json({ 
-        error: 'Invalid configuration', 
-        details: `${parsedConfig.type} type requires a url field` 
-      });
-    }
-    
-    const { spawn } = await import('child_process');
-    
-    // Build the command: claude mcp add-json --scope <scope> <name> '<json>'
-    const cliArgs = ['mcp', 'add-json', '--scope', scope, name];
-    
-    // Add the JSON config as a properly formatted string
-    const jsonString = JSON.stringify(parsedConfig);
-    cliArgs.push(jsonString);
-    
-    console.log('🔧 Running Claude CLI command:', 'claude', cliArgs[0], cliArgs[1], cliArgs[2], cliArgs[3], cliArgs[4], jsonString);
-    
-    // For local scope, we need to run the command in the project directory
-    const spawnOptions = {
-      stdio: ['pipe', 'pipe', 'pipe']
-    };
-    
-    if (scope === 'local' && projectPath) {
-      spawnOptions.cwd = projectPath;
-      console.log('📁 Running in project directory:', projectPath);
-    }
-    
-    const process = spawn('claude', cliArgs, spawnOptions);
-    
-    let stdout = '';
-    let stderr = '';
-    
-    process.stdout.on('data', (data) => {
-      stdout += data.toString();
-    });
-    
-    process.stderr.on('data', (data) => {
-      stderr += data.toString();
-    });
-    
-    process.on('close', (code) => {
-      if (code === 0) {
-        res.json({ success: true, output: stdout, message: `MCP server "${name}" added successfully via JSON` });
-      } else {
-        console.error('Claude CLI error:', stderr);
-        res.status(400).json({ error: 'Claude CLI command failed', details: stderr });
-      }
-    });
-    
-    process.on('error', (error) => {
-      console.error('Error running Claude CLI:', error);
-      res.status(500).json({ error: 'Failed to run Claude CLI', details: error.message });
-    });
-  } catch (error) {
-    console.error('Error adding MCP server via JSON:', error);
-    res.status(500).json({ error: 'Failed to add MCP server', details: error.message });
-  }
-});
-
-// DELETE /api/mcp/cli/remove/:name - Remove MCP server using Claude CLI
-router.delete('/cli/remove/:name', async (req, res) => {
-  try {
-    const { name } = req.params;
-    const { scope } = req.query; // Get scope from query params
-    
-    // Handle the ID format (remove scope prefix if present)
-    let actualName = name;
-    let actualScope = scope;
-    
-    // If the name includes a scope prefix like "local:test", extract it
-    if (name.includes(':')) {
-      const [prefix, serverName] = name.split(':');
-      actualName = serverName;
-      actualScope = actualScope || prefix; // Use prefix as scope if not provided in query
-    }
-    
-    console.log('🗑️ Removing MCP server using Claude CLI:', actualName, 'scope:', actualScope);
-    
-    const { spawn } = await import('child_process');
-    
-    // Build command args based on scope
-    let cliArgs = ['mcp', 'remove'];
-    
-    // Add scope flag if it's local scope
-    if (actualScope === 'local') {
-      cliArgs.push('--scope', 'local');
-    } else if (actualScope === 'user' || !actualScope) {
-      // User scope is default, but we can be explicit
-      cliArgs.push('--scope', 'user');
-    }
-    
-    cliArgs.push(actualName);
-    
-    console.log('🔧 Running Claude CLI command:', 'claude', cliArgs.join(' '));
-    
-    const process = spawn('claude', cliArgs, {
-      stdio: ['pipe', 'pipe', 'pipe']
-    });
-    
-    let stdout = '';
-    let stderr = '';
-    
-    process.stdout.on('data', (data) => {
-      stdout += data.toString();
-    });
-    
-    process.stderr.on('data', (data) => {
-      stderr += data.toString();
-    });
-    
-    process.on('close', (code) => {
-      if (code === 0) {
-        res.json({ success: true, output: stdout, message: `MCP server "${name}" removed successfully` });
-      } else {
-        console.error('Claude CLI error:', stderr);
-        res.status(400).json({ error: 'Claude CLI command failed', details: stderr });
-      }
-    });
-    
-    process.on('error', (error) => {
-      console.error('Error running Claude CLI:', error);
-      res.status(500).json({ error: 'Failed to run Claude CLI', details: error.message });
-    });
-  } catch (error) {
-    console.error('Error removing MCP server via CLI:', error);
-    res.status(500).json({ error: 'Failed to remove MCP server', details: error.message });
-  }
-});
-
-// GET /api/mcp/cli/get/:name - Get MCP server details using Claude CLI
-router.get('/cli/get/:name', async (req, res) => {
-  try {
-    const { name } = req.params;
-    
-    console.log('📄 Getting MCP server details using Claude CLI:', name);
-    
-    const { spawn } = await import('child_process');
-    
-    const process = spawn('claude', ['mcp', 'get', name], {
-      stdio: ['pipe', 'pipe', 'pipe']
-    });
-    
-    let stdout = '';
-    let stderr = '';
-    
-    process.stdout.on('data', (data) => {
-      stdout += data.toString();
-    });
-    
-    process.stderr.on('data', (data) => {
-      stderr += data.toString();
-    });
-    
-    process.on('close', (code) => {
-      if (code === 0) {
-        res.json({ success: true, output: stdout, server: parseClaudeGetOutput(stdout) });
-      } else {
-        console.error('Claude CLI error:', stderr);
-        res.status(404).json({ error: 'Claude CLI command failed', details: stderr });
-      }
-    });
-    
-    process.on('error', (error) => {
-      console.error('Error running Claude CLI:', error);
-      res.status(500).json({ error: 'Failed to run Claude CLI', details: error.message });
-    });
-  } catch (error) {
-    console.error('Error getting MCP server details via CLI:', error);
-    res.status(500).json({ error: 'Failed to get MCP server details', details: error.message });
-  }
-});
-
-// GET /api/mcp/config/read - Read MCP servers directly from Claude config files
-router.get('/config/read', async (req, res) => {
-  try {
-    console.log('📖 Reading MCP servers from Claude config files');
-    
-    const homeDir = os.homedir();
-    const configPaths = [
-      path.join(homeDir, '.claude.json'),
-      path.join(homeDir, '.claude', 'settings.json')
-    ];
-    
-    let configData = null;
-    let configPath = null;
-    
-    // Try to read from either config file
-    for (const filepath of configPaths) {
-      try {
-        const fileContent = await fs.readFile(filepath, 'utf8');
-        configData = JSON.parse(fileContent);
-        configPath = filepath;
-        console.log(`✅ Found Claude config at: ${filepath}`);
-        break;
-      } catch (error) {
-        // File doesn't exist or is not valid JSON, try next
-        console.log(`ℹ️ Config not found or invalid at: ${filepath}`);
-      }
-    }
-    
-    if (!configData) {
-      return res.json({ 
-        success: false, 
-        message: 'No Claude configuration file found',
-        servers: [] 
-      });
-    }
-    
-    // Extract MCP servers from the config
-    const servers = [];
-    
-    // Check for user-scoped MCP servers (at root level)
-    if (configData.mcpServers && typeof configData.mcpServers === 'object' && Object.keys(configData.mcpServers).length > 0) {
-      console.log('🔍 Found user-scoped MCP servers:', Object.keys(configData.mcpServers));
-      for (const [name, config] of Object.entries(configData.mcpServers)) {
-        const server = {
-          id: name,
-          name: name,
-          type: 'stdio', // Default type
-          scope: 'user',  // User scope - available across all projects
-          config: {},
-          raw: config // Include raw config for full details
-        };
-        
-        // Determine transport type and extract config
-        if (config.command) {
-          server.type = 'stdio';
-          server.config.command = config.command;
-          server.config.args = config.args || [];
-          server.config.env = config.env || {};
-        } else if (config.url) {
-          server.type = config.transport || 'http';
-          server.config.url = config.url;
-          server.config.headers = config.headers || {};
-        }
-        
-        servers.push(server);
-      }
-    }
-    
-    // Check for local-scoped MCP servers (project-specific)
-    const currentProjectPath = process.cwd();
-    
-    // Check under 'projects' key
-    if (configData.projects && configData.projects[currentProjectPath]) {
-      const projectConfig = configData.projects[currentProjectPath];
-      if (projectConfig.mcpServers && typeof projectConfig.mcpServers === 'object' && Object.keys(projectConfig.mcpServers).length > 0) {
-        console.log(`🔍 Found local-scoped MCP servers for ${currentProjectPath}:`, Object.keys(projectConfig.mcpServers));
-        for (const [name, config] of Object.entries(projectConfig.mcpServers)) {
-          const server = {
-            id: `local:${name}`,  // Prefix with scope for uniqueness
-            name: name,           // Keep original name
-            type: 'stdio', // Default type
-            scope: 'local',  // Local scope - only for this project
-            projectPath: currentProjectPath,
-            config: {},
-            raw: config // Include raw config for full details
-          };
-          
-          // Determine transport type and extract config
-          if (config.command) {
-            server.type = 'stdio';
-            server.config.command = config.command;
-            server.config.args = config.args || [];
-            server.config.env = config.env || {};
-          } else if (config.url) {
-            server.type = config.transport || 'http';
-            server.config.url = config.url;
-            server.config.headers = config.headers || {};
-          }
-          
-          servers.push(server);
-        }
-      }
-    }
-    
-    console.log(`📋 Found ${servers.length} MCP servers in config`);
-    
-    res.json({ 
-      success: true, 
-      configPath: configPath,
-      servers: servers 
-    });
-  } catch (error) {
-    console.error('Error reading Claude config:', error);
-    res.status(500).json({ 
-      error: 'Failed to read Claude configuration', 
-      details: error.message 
-    });
-  }
-});
-
-// Helper functions to parse Claude CLI output
-function parseClaudeListOutput(output) {
-  const servers = [];
-  const lines = output.split('\n').filter(line => line.trim());
-  
-  for (const line of lines) {
-    // Skip the header line
-    if (line.includes('Checking MCP server health')) continue;
-    
-    // Parse lines like "test: test test - ✗ Failed to connect"
-    // or "server-name: command or description - ✓ Connected"
-    if (line.includes(':')) {
-      const colonIndex = line.indexOf(':');
-      const name = line.substring(0, colonIndex).trim();
-      
-      // Skip empty names
-      if (!name) continue;
-      
-      // Extract the rest after the name
-      const rest = line.substring(colonIndex + 1).trim();
-      
-      // Try to extract description and status
-      let description = rest;
-      let status = 'unknown';
-      let type = 'stdio'; // default type
-      
-      // Check for status indicators
-      if (rest.includes('✓') || rest.includes('✗')) {
-        const statusMatch = rest.match(/(.*?)\s*-\s*([✓✗].*)$/);
-        if (statusMatch) {
-          description = statusMatch[1].trim();
-          status = statusMatch[2].includes('✓') ? 'connected' : 'failed';
-        }
-      }
-      
-      // Try to determine type from description
-      if (description.startsWith('http://') || description.startsWith('https://')) {
-        type = 'http';
-      }
-      
-      servers.push({
-        name,
-        type,
-        status: status || 'active',
-        description
-      });
-    }
-  }
-  
-  console.log('🔍 Parsed Claude CLI servers:', servers);
-  return servers;
-}
-
-function parseClaudeGetOutput(output) {
-  // Parse the output from 'claude mcp get <name>' command
-  // This is a simple parser - might need adjustment based on actual output format
-  try {
-    // Try to extract JSON if present
-    const jsonMatch = output.match(/\{[\s\S]*\}/);
-    if (jsonMatch) {
-      return JSON.parse(jsonMatch[0]);
-    }
-    
-    // Otherwise, parse as text
-    const server = { raw_output: output };
-    const lines = output.split('\n');
-    
-    for (const line of lines) {
-      if (line.includes('Name:')) {
-        server.name = line.split(':')[1]?.trim();
-      } else if (line.includes('Type:')) {
-        server.type = line.split(':')[1]?.trim();
-      } else if (line.includes('Command:')) {
-        server.command = line.split(':')[1]?.trim();
-      } else if (line.includes('URL:')) {
-        server.url = line.split(':')[1]?.trim();
-      }
-    }
-    
-    return server;
-  } catch (error) {
-    return { raw_output: output, parse_error: error.message };
-  }
-}
-
-export default router;

server/routes/messages.js

@@ -0,0 +1,61 @@
+/**
+ * Unified messages endpoint.
+ *
+ * GET /api/sessions/:sessionId/messages?provider=claude&projectName=foo&limit=50&offset=0
+ *
+ * Replaces the four provider-specific session message endpoints with a single route
+ * that delegates to the appropriate adapter via the provider registry.
+ *
+ * @module routes/messages
+ */
+
+import express from 'express';
+import { sessionsService } from '../modules/providers/services/sessions.service.js';
+
+const router = express.Router();
+
+/**
+ * GET /api/sessions/:sessionId/messages
+ *
+ * Auth: authenticateToken applied at mount level in index.js
+ *
+ * Query params:
+ *   provider    - 'claude' | 'cursor' | 'codex' | 'gemini' (default: 'claude')
+ *   projectName - required for claude provider
+ *   projectPath - required for cursor provider (absolute path used for cwdId hash)
+ *   limit       - page size (omit or null for all)
+ *   offset      - pagination offset (default: 0)
+ */
+router.get('/:sessionId/messages', async (req, res) => {
+  try {
+    const { sessionId } = req.params;
+    const provider = String(req.query.provider || 'claude').trim().toLowerCase();
+    const projectName = req.query.projectName || '';
+    const projectPath = req.query.projectPath || '';
+    const limitParam = req.query.limit;
+    const limit = limitParam !== undefined && limitParam !== null && limitParam !== ''
+      ? parseInt(limitParam, 10)
+      : null;
+    const offset = parseInt(req.query.offset || '0', 10);
+
+    const availableProviders = sessionsService.listProviderIds();
+    if (!availableProviders.includes(provider)) {
+      const available = availableProviders.join(', ');
+      return res.status(400).json({ error: `Unknown provider: ${provider}. Available: ${available}` });
+    }
+
+    const result = await sessionsService.fetchHistory(provider, sessionId, {
+      projectName,
+      projectPath,
+      limit,
+      offset,
+    });
+
+    return res.json(result);
+  } catch (error) {
+    console.error('Error fetching unified messages:', error);
+    return res.status(500).json({ error: 'Failed to fetch messages' });
+  }
+});
+
+export default router;

server/routes/plugins.js

@@ -81,6 +81,10 @@ router.get('/:name/assets/*', (req, res) => {
 
   const contentType = mime.lookup(resolvedPath) || 'application/octet-stream';
   res.setHeader('Content-Type', contentType);
+  // Prevent CDN/proxy caching of plugin assets so updates take effect immediately
+  res.setHeader('Cache-Control', 'no-store, no-cache, must-revalidate');
+  res.setHeader('Pragma', 'no-cache');
+  res.setHeader('Expires', '0');
   const stream = fs.createReadStream(resolvedPath);
   stream.on('error', () => {
     if (!res.headersSent) {
@@ -236,7 +240,7 @@ router.all('/:name/rpc/*', async (req, res) => {
     'content-type': req.headers['content-type'] || 'application/json',
   };
 
-  // Add per-plugin secrets as X-Plugin-Secret-* headers
+  // Add per-plugin user-configured secrets as X-Plugin-Secret-* headers
   for (const [key, value] of Object.entries(secrets)) {
     headers[`x-plugin-secret-${key.toLowerCase()}`] = String(value);
   }

server/routes/settings.js

@@ -1,5 +1,7 @@
 import express from 'express';
-import { apiKeysDb, credentialsDb } from '../database/db.js';
+import { apiKeysDb, credentialsDb, notificationPreferencesDb, pushSubscriptionsDb } from '../database/db.js';
+import { getPublicKey } from '../services/vapid-keys.js';
+import { createNotificationEvent, notifyUserIfEnabled } from '../services/notification-orchestrator.js';
 
 const router = express.Router();
 
@@ -175,4 +177,110 @@ router.patch('/credentials/:credentialId/toggle', async (req, res) => {
   }
 });
 
+// ===============================
+// Notification Preferences
+// ===============================
+
+router.get('/notification-preferences', async (req, res) => {
+  try {
+    const preferences = notificationPreferencesDb.getPreferences(req.user.id);
+    res.json({ success: true, preferences });
+  } catch (error) {
+    console.error('Error fetching notification preferences:', error);
+    res.status(500).json({ error: 'Failed to fetch notification preferences' });
+  }
+});
+
+router.put('/notification-preferences', async (req, res) => {
+  try {
+    const preferences = notificationPreferencesDb.updatePreferences(req.user.id, req.body || {});
+    res.json({ success: true, preferences });
+  } catch (error) {
+    console.error('Error saving notification preferences:', error);
+    res.status(500).json({ error: 'Failed to save notification preferences' });
+  }
+});
+
+// ===============================
+// Push Subscription Management
+// ===============================
+
+router.get('/push/vapid-public-key', async (req, res) => {
+  try {
+    const publicKey = getPublicKey();
+    res.json({ publicKey });
+  } catch (error) {
+    console.error('Error fetching VAPID public key:', error);
+    res.status(500).json({ error: 'Failed to fetch VAPID public key' });
+  }
+});
+
+router.post('/push/subscribe', async (req, res) => {
+  try {
+    const { endpoint, keys } = req.body;
+    if (!endpoint || !keys?.p256dh || !keys?.auth) {
+      return res.status(400).json({ error: 'Missing subscription fields' });
+    }
+    pushSubscriptionsDb.saveSubscription(req.user.id, endpoint, keys.p256dh, keys.auth);
+
+    // Enable webPush in preferences so the confirmation goes through the full pipeline
+    const currentPrefs = notificationPreferencesDb.getPreferences(req.user.id);
+    if (!currentPrefs?.channels?.webPush) {
+      notificationPreferencesDb.updatePreferences(req.user.id, {
+        ...currentPrefs,
+        channels: { ...currentPrefs?.channels, webPush: true },
+      });
+    }
+
+    res.json({ success: true });
+
+    // Send a confirmation push through the full notification pipeline
+    const event = createNotificationEvent({
+      provider: 'system',
+      kind: 'info',
+      code: 'push.enabled',
+      meta: { message: 'Push notifications are now enabled!' },
+      severity: 'info'
+    });
+    notifyUserIfEnabled({ userId: req.user.id, event });
+  } catch (error) {
+    console.error('Error saving push subscription:', error);
+    res.status(500).json({ error: 'Failed to save push subscription' });
+  }
+});
+
+router.post('/push/unsubscribe', async (req, res) => {
+  try {
+    const { endpoint } = req.body;
+    if (!endpoint) {
+      return res.status(400).json({ error: 'Missing endpoint' });
+    }
+    pushSubscriptionsDb.removeSubscription(endpoint);
+
+    // Disable webPush in preferences to match subscription state
+    const currentPrefs = notificationPreferencesDb.getPreferences(req.user.id);
+    if (currentPrefs?.channels?.webPush) {
+      notificationPreferencesDb.updatePreferences(req.user.id, {
+        ...currentPrefs,
+        channels: { ...currentPrefs.channels, webPush: false },
+      });
+    }
+
+    res.json({ success: true });
+  } catch (error) {
+    console.error('Error removing push subscription:', error);
+    res.status(500).json({ error: 'Failed to remove push subscription' });
+  }
+});
+
+// Host OS for UI (e.g. hide Cursor agent when the backend runs on Windows).
+router.get('/server-env', async (req, res) => {
+  try {
+    res.json({ platform: process.platform });
+  } catch (error) {
+    console.error('Error reading server environment:', error);
+    res.status(500).json({ error: 'Failed to read server environment' });
+  }
+});
+
 export default router;

server/routes/taskmaster.js

@@ -13,16 +13,10 @@ import fs from 'fs';
 import path from 'path';
 import { promises as fsPromises } from 'fs';
 import { spawn } from 'child_process';
-import { fileURLToPath } from 'url';
-import { dirname } from 'path';
-import os from 'os';
 import { extractProjectDirectory } from '../projects.js';
 import { detectTaskMasterMCPServer } from '../utils/mcp-detector.js';
 import { broadcastTaskMasterProjectUpdate, broadcastTaskMasterTasksUpdate } from '../utils/taskmaster-websocket.js';
 
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
-
 const router = express.Router();
 
 /**
@@ -100,140 +94,6 @@ async function checkTaskMasterInstallation() {
     });
 }
 
-/**
- * Detect .taskmaster folder presence in a given project directory
- * @param {string} projectPath - Absolute path to project directory
- * @returns {Promise<Object>} Detection result with status and metadata
- */
-async function detectTaskMasterFolder(projectPath) {
-    try {
-        const taskMasterPath = path.join(projectPath, '.taskmaster');
-        
-        // Check if .taskmaster directory exists
-        try {
-            const stats = await fsPromises.stat(taskMasterPath);
-            if (!stats.isDirectory()) {
-                return {
-                    hasTaskmaster: false,
-                    reason: '.taskmaster exists but is not a directory'
-                };
-            }
-        } catch (error) {
-            if (error.code === 'ENOENT') {
-                return {
-                    hasTaskmaster: false,
-                    reason: '.taskmaster directory not found'
-                };
-            }
-            throw error;
-        }
-
-        // Check for key TaskMaster files
-        const keyFiles = [
-            'tasks/tasks.json',
-            'config.json'
-        ];
-        
-        const fileStatus = {};
-        let hasEssentialFiles = true;
-
-        for (const file of keyFiles) {
-            const filePath = path.join(taskMasterPath, file);
-            try {
-                await fsPromises.access(filePath, fs.constants.R_OK);
-                fileStatus[file] = true;
-            } catch (error) {
-                fileStatus[file] = false;
-                if (file === 'tasks/tasks.json') {
-                    hasEssentialFiles = false;
-                }
-            }
-        }
-
-        // Parse tasks.json if it exists for metadata
-        let taskMetadata = null;
-        if (fileStatus['tasks/tasks.json']) {
-            try {
-                const tasksPath = path.join(taskMasterPath, 'tasks/tasks.json');
-                const tasksContent = await fsPromises.readFile(tasksPath, 'utf8');
-                const tasksData = JSON.parse(tasksContent);
-                
-                // Handle both tagged and legacy formats
-                let tasks = [];
-                if (tasksData.tasks) {
-                    // Legacy format
-                    tasks = tasksData.tasks;
-                } else {
-                    // Tagged format - get tasks from all tags
-                    Object.values(tasksData).forEach(tagData => {
-                        if (tagData.tasks) {
-                            tasks = tasks.concat(tagData.tasks);
-                        }
-                    });
-                }
-
-                // Calculate task statistics
-                const stats = tasks.reduce((acc, task) => {
-                    acc.total++;
-                    acc[task.status] = (acc[task.status] || 0) + 1;
-                    
-                    // Count subtasks
-                    if (task.subtasks) {
-                        task.subtasks.forEach(subtask => {
-                            acc.subtotalTasks++;
-                            acc.subtasks = acc.subtasks || {};
-                            acc.subtasks[subtask.status] = (acc.subtasks[subtask.status] || 0) + 1;
-                        });
-                    }
-                    
-                    return acc;
-                }, { 
-                    total: 0, 
-                    subtotalTasks: 0,
-                    pending: 0, 
-                    'in-progress': 0, 
-                    done: 0, 
-                    review: 0,
-                    deferred: 0,
-                    cancelled: 0,
-                    subtasks: {}
-                });
-
-                taskMetadata = {
-                    taskCount: stats.total,
-                    subtaskCount: stats.subtotalTasks,
-                    completed: stats.done || 0,
-                    pending: stats.pending || 0,
-                    inProgress: stats['in-progress'] || 0,
-                    review: stats.review || 0,
-                    completionPercentage: stats.total > 0 ? Math.round((stats.done / stats.total) * 100) : 0,
-                    lastModified: (await fsPromises.stat(tasksPath)).mtime.toISOString()
-                };
-            } catch (parseError) {
-                console.warn('Failed to parse tasks.json:', parseError.message);
-                taskMetadata = { error: 'Failed to parse tasks.json' };
-            }
-        }
-
-        return {
-            hasTaskmaster: true,
-            hasEssentialFiles,
-            files: fileStatus,
-            metadata: taskMetadata,
-            path: taskMasterPath
-        };
-
-    } catch (error) {
-        console.error('Error detecting TaskMaster folder:', error);
-        return {
-            hasTaskmaster: false,
-            reason: `Error checking directory: ${error.message}`
-        };
-    }
-}
-
-// MCP detection is now handled by the centralized utility
-
 // API Routes
 
 /**
@@ -271,298 +131,6 @@ router.get('/installation-status', async (req, res) => {
     }
 });
 
-/**
- * GET /api/taskmaster/detect/:projectName
- * Detect TaskMaster configuration for a specific project
- */
-router.get('/detect/:projectName', async (req, res) => {
-    try {
-        const { projectName } = req.params;
-        
-        // Use the existing extractProjectDirectory function to get actual project path
-        let projectPath;
-        try {
-            projectPath = await extractProjectDirectory(projectName);
-        } catch (error) {
-            console.error('Error extracting project directory:', error);
-            return res.status(404).json({
-                error: 'Project path not found',
-                projectName,
-                message: error.message
-            });
-        }
-        
-        // Verify the project path exists
-        try {
-            await fsPromises.access(projectPath, fs.constants.R_OK);
-        } catch (error) {
-            return res.status(404).json({
-                error: 'Project path not accessible',
-                projectPath,
-                projectName,
-                message: error.message
-            });
-        }
-
-        // Run detection in parallel
-        const [taskMasterResult, mcpResult] = await Promise.all([
-            detectTaskMasterFolder(projectPath),
-            detectTaskMasterMCPServer()
-        ]);
-
-        // Determine overall status
-        let status = 'not-configured';
-        if (taskMasterResult.hasTaskmaster && taskMasterResult.hasEssentialFiles) {
-            if (mcpResult.hasMCPServer && mcpResult.isConfigured) {
-                status = 'fully-configured';
-            } else {
-                status = 'taskmaster-only';
-            }
-        } else if (mcpResult.hasMCPServer && mcpResult.isConfigured) {
-            status = 'mcp-only';
-        }
-
-        const responseData = {
-            projectName,
-            projectPath,
-            status,
-            taskmaster: taskMasterResult,
-            mcp: mcpResult,
-            timestamp: new Date().toISOString()
-        };
-
-        res.json(responseData);
-
-    } catch (error) {
-        console.error('TaskMaster detection error:', error);
-        res.status(500).json({
-            error: 'Failed to detect TaskMaster configuration',
-            message: error.message
-        });
-    }
-});
-
-/**
- * GET /api/taskmaster/detect-all
- * Detect TaskMaster configuration for all known projects
- * This endpoint works with the existing projects system
- */
-router.get('/detect-all', async (req, res) => {
-    try {
-        // Import getProjects from the projects module
-        const { getProjects } = await import('../projects.js');
-        const projects = await getProjects();
-
-        // Run detection for all projects in parallel
-        const detectionPromises = projects.map(async (project) => {
-            try {
-                // Use the project's fullPath if available, otherwise extract the directory
-                let projectPath;
-                if (project.fullPath) {
-                    projectPath = project.fullPath;
-                } else {
-                    try {
-                        projectPath = await extractProjectDirectory(project.name);
-                    } catch (error) {
-                        throw new Error(`Failed to extract project directory: ${error.message}`);
-                    }
-                }
-                
-                const [taskMasterResult, mcpResult] = await Promise.all([
-                    detectTaskMasterFolder(projectPath),
-                    detectTaskMasterMCPServer()
-                ]);
-
-                // Determine status
-                let status = 'not-configured';
-                if (taskMasterResult.hasTaskmaster && taskMasterResult.hasEssentialFiles) {
-                    if (mcpResult.hasMCPServer && mcpResult.isConfigured) {
-                        status = 'fully-configured';
-                    } else {
-                        status = 'taskmaster-only';
-                    }
-                } else if (mcpResult.hasMCPServer && mcpResult.isConfigured) {
-                    status = 'mcp-only';
-                }
-
-                return {
-                    projectName: project.name,
-                    displayName: project.displayName,
-                    projectPath,
-                    status,
-                    taskmaster: taskMasterResult,
-                    mcp: mcpResult
-                };
-            } catch (error) {
-                return {
-                    projectName: project.name,
-                    displayName: project.displayName,
-                    status: 'error',
-                    error: error.message
-                };
-            }
-        });
-
-        const results = await Promise.all(detectionPromises);
-
-        res.json({
-            projects: results,
-            summary: {
-                total: results.length,
-                fullyConfigured: results.filter(p => p.status === 'fully-configured').length,
-                taskmasterOnly: results.filter(p => p.status === 'taskmaster-only').length,
-                mcpOnly: results.filter(p => p.status === 'mcp-only').length,
-                notConfigured: results.filter(p => p.status === 'not-configured').length,
-                errors: results.filter(p => p.status === 'error').length
-            },
-            timestamp: new Date().toISOString()
-        });
-
-    } catch (error) {
-        console.error('Bulk TaskMaster detection error:', error);
-        res.status(500).json({
-            error: 'Failed to detect TaskMaster configuration for projects',
-            message: error.message
-        });
-    }
-});
-
-/**
- * POST /api/taskmaster/initialize/:projectName
- * Initialize TaskMaster in a project (placeholder for future CLI integration)
- */
-router.post('/initialize/:projectName', async (req, res) => {
-    try {
-        const { projectName } = req.params;
-        const { rules } = req.body; // Optional rule profiles
-        
-        // This will be implemented in a later subtask with CLI integration
-        res.status(501).json({
-            error: 'TaskMaster initialization not yet implemented',
-            message: 'This endpoint will execute task-master init via CLI in a future update',
-            projectName,
-            rules
-        });
-        
-    } catch (error) {
-        console.error('TaskMaster initialization error:', error);
-        res.status(500).json({
-            error: 'Failed to initialize TaskMaster',
-            message: error.message
-        });
-    }
-});
-
-/**
- * GET /api/taskmaster/next/:projectName
- * Get the next recommended task using task-master CLI
- */
-router.get('/next/:projectName', async (req, res) => {
-    try {
-        const { projectName } = req.params;
-        
-        // Get project path
-        let projectPath;
-        try {
-            projectPath = await extractProjectDirectory(projectName);
-        } catch (error) {
-            return res.status(404).json({
-                error: 'Project not found',
-                message: `Project "${projectName}" does not exist`
-            });
-        }
-
-        // Try to execute task-master next command
-        try {
-            const { spawn } = await import('child_process');
-            
-            const nextTaskCommand = spawn('task-master', ['next'], {
-                cwd: projectPath,
-                stdio: ['pipe', 'pipe', 'pipe']
-            });
-
-            let stdout = '';
-            let stderr = '';
-
-            nextTaskCommand.stdout.on('data', (data) => {
-                stdout += data.toString();
-            });
-
-            nextTaskCommand.stderr.on('data', (data) => {
-                stderr += data.toString();
-            });
-
-            await new Promise((resolve, reject) => {
-                nextTaskCommand.on('close', (code) => {
-                    if (code === 0) {
-                        resolve();
-                    } else {
-                        reject(new Error(`task-master next failed with code ${code}: ${stderr}`));
-                    }
-                });
-
-                nextTaskCommand.on('error', (error) => {
-                    reject(error);
-                });
-            });
-
-            // Parse the output - task-master next usually returns JSON
-            let nextTaskData = null;
-            if (stdout.trim()) {
-                try {
-                    nextTaskData = JSON.parse(stdout);
-                } catch (parseError) {
-                    // If not JSON, treat as plain text
-                    nextTaskData = { message: stdout.trim() };
-                }
-            }
-
-            res.json({
-                projectName,
-                projectPath,
-                nextTask: nextTaskData,
-                timestamp: new Date().toISOString()
-            });
-
-        } catch (cliError) {
-            console.warn('Failed to execute task-master CLI:', cliError.message);
-            
-            // Fallback to loading tasks and finding next one locally
-            // Use localhost to bypass proxy for internal server-to-server calls
-            const tasksResponse = await fetch(`http://localhost:${process.env.PORT || 3001}/api/taskmaster/tasks/${encodeURIComponent(projectName)}`, {
-                headers: {
-                    'Authorization': req.headers.authorization
-                }
-            });
-
-            if (tasksResponse.ok) {
-                const tasksData = await tasksResponse.json();
-                const nextTask = tasksData.tasks?.find(task => 
-                    task.status === 'pending' || task.status === 'in-progress'
-                ) || null;
-
-                res.json({
-                    projectName,
-                    projectPath,
-                    nextTask,
-                    fallback: true,
-                    message: 'Used fallback method (CLI not available)',
-                    timestamp: new Date().toISOString()
-                });
-            } else {
-                throw new Error('Failed to load tasks via fallback method');
-            }
-        }
-
-    } catch (error) {
-        console.error('TaskMaster next task error:', error);
-        res.status(500).json({
-            error: 'Failed to get next task',
-            message: error.message
-        });
-    }
-});
-
 /**
  * GET /api/taskmaster/tasks/:projectName
  * Load actual tasks from .taskmaster/tasks/tasks.json
@@ -904,66 +472,6 @@ router.get('/prd/:projectName/:fileName', async (req, res) => {
     }
 });
 
-/**
- * DELETE /api/taskmaster/prd/:projectName/:fileName
- * Delete a specific PRD file
- */
-router.delete('/prd/:projectName/:fileName', async (req, res) => {
-    try {
-        const { projectName, fileName } = req.params;
-        
-        // Get project path
-        let projectPath;
-        try {
-            projectPath = await extractProjectDirectory(projectName);
-        } catch (error) {
-            return res.status(404).json({
-                error: 'Project not found',
-                message: `Project "${projectName}" does not exist`
-            });
-        }
-
-        const filePath = path.join(projectPath, '.taskmaster', 'docs', fileName);
-        
-        // Check if file exists
-        try {
-            await fsPromises.access(filePath, fs.constants.F_OK);
-        } catch (error) {
-            return res.status(404).json({
-                error: 'PRD file not found',
-                message: `File "${fileName}" does not exist`
-            });
-        }
-
-        // Delete the file
-        try {
-            await fsPromises.unlink(filePath);
-
-            res.json({
-                projectName,
-                projectPath,
-                fileName,
-                message: 'PRD file deleted successfully',
-                timestamp: new Date().toISOString()
-            });
-
-        } catch (deleteError) {
-            console.error('Failed to delete PRD file:', deleteError);
-            return res.status(500).json({
-                error: 'Failed to delete PRD file',
-                message: deleteError.message
-            });
-        }
-
-    } catch (error) {
-        console.error('PRD delete error:', error);
-        res.status(500).json({
-            error: 'Failed to delete PRD file',
-            message: error.message
-        });
-    }
-});
-
 /**
  * POST /api/taskmaster/init/:projectName
  * Initialize TaskMaster in a project
@@ -1960,4 +1468,4 @@ Brief description of what this web application will do and why it's needed.
     ];
 }
 
-export default router;
+export default router;

server/services/notification-orchestrator.js

@@ -0,0 +1,227 @@
+import webPush from 'web-push';
+import { notificationPreferencesDb, pushSubscriptionsDb, sessionNamesDb } from '../database/db.js';
+
+const KIND_TO_PREF_KEY = {
+  action_required: 'actionRequired',
+  stop: 'stop',
+  error: 'error'
+};
+
+const PROVIDER_LABELS = {
+  claude: 'Claude',
+  cursor: 'Cursor',
+  codex: 'Codex',
+  gemini: 'Gemini',
+  system: 'System'
+};
+
+const recentEventKeys = new Map();
+const DEDUPE_WINDOW_MS = 20000;
+
+const cleanupOldEventKeys = () => {
+  const now = Date.now();
+  for (const [key, timestamp] of recentEventKeys.entries()) {
+    if (now - timestamp > DEDUPE_WINDOW_MS) {
+      recentEventKeys.delete(key);
+    }
+  }
+};
+
+function shouldSendPush(preferences, event) {
+  const webPushEnabled = Boolean(preferences?.channels?.webPush);
+  const prefEventKey = KIND_TO_PREF_KEY[event.kind];
+  const eventEnabled = prefEventKey ? Boolean(preferences?.events?.[prefEventKey]) : true;
+
+  return webPushEnabled && eventEnabled;
+}
+
+function isDuplicate(event) {
+  cleanupOldEventKeys();
+  const key = event.dedupeKey || `${event.provider}:${event.kind || 'info'}:${event.code || 'generic'}:${event.sessionId || 'none'}`;
+  if (recentEventKeys.has(key)) {
+    return true;
+  }
+  recentEventKeys.set(key, Date.now());
+  return false;
+}
+
+function createNotificationEvent({
+  provider,
+  sessionId = null,
+  kind = 'info',
+  code = 'generic.info',
+  meta = {},
+  severity = 'info',
+  dedupeKey = null,
+  requiresUserAction = false
+}) {
+  return {
+    provider,
+    sessionId,
+    kind,
+    code,
+    meta,
+    severity,
+    requiresUserAction,
+    dedupeKey,
+    createdAt: new Date().toISOString()
+  };
+}
+
+function normalizeErrorMessage(error) {
+  if (typeof error === 'string') {
+    return error;
+  }
+
+  if (error && typeof error.message === 'string') {
+    return error.message;
+  }
+
+  if (error == null) {
+    return 'Unknown error';
+  }
+
+  return String(error);
+}
+
+function normalizeSessionName(sessionName) {
+  if (typeof sessionName !== 'string') {
+    return null;
+  }
+
+  const normalized = sessionName.replace(/\s+/g, ' ').trim();
+  if (!normalized) {
+    return null;
+  }
+
+  return normalized.length > 80 ? `${normalized.slice(0, 77)}...` : normalized;
+}
+
+function resolveSessionName(event) {
+  const explicitSessionName = normalizeSessionName(event.meta?.sessionName);
+  if (explicitSessionName) {
+    return explicitSessionName;
+  }
+
+  if (!event.sessionId || !event.provider) {
+    return null;
+  }
+
+  return normalizeSessionName(sessionNamesDb.getName(event.sessionId, event.provider));
+}
+
+function buildPushBody(event) {
+  const CODE_MAP = {
+    'permission.required': event.meta?.toolName
+      ? `Action Required: Tool "${event.meta.toolName}" needs approval`
+      : 'Action Required: A tool needs your approval',
+    'run.stopped': event.meta?.stopReason || 'Run Stopped: The run has stopped',
+    'run.failed': event.meta?.error ? `Run Failed: ${event.meta.error}` : 'Run Failed: The run encountered an error',
+    'agent.notification': event.meta?.message ? String(event.meta.message) : 'You have a new notification',
+    'push.enabled': 'Push notifications are now enabled!'
+  };
+  const providerLabel = PROVIDER_LABELS[event.provider] || 'Assistant';
+  const sessionName = resolveSessionName(event);
+  const message = CODE_MAP[event.code] || 'You have a new notification';
+
+  return {
+    title: sessionName || 'CloudCLI',
+    body: `${providerLabel}: ${message}`,
+    data: {
+      sessionId: event.sessionId || null,
+      code: event.code,
+      provider: event.provider || null,
+      sessionName,
+      tag: `${event.provider || 'assistant'}:${event.sessionId || 'none'}:${event.code}`
+    }
+  };
+}
+
+async function sendWebPush(userId, event) {
+  const subscriptions = pushSubscriptionsDb.getSubscriptions(userId);
+  if (!subscriptions.length) return;
+
+  const payload = JSON.stringify(buildPushBody(event));
+
+  const results = await Promise.allSettled(
+    subscriptions.map((sub) =>
+      webPush.sendNotification(
+        {
+          endpoint: sub.endpoint,
+          keys: {
+            p256dh: sub.keys_p256dh,
+            auth: sub.keys_auth
+          }
+        },
+        payload
+      )
+    )
+  );
+
+  // Clean up gone subscriptions (410 Gone or 404)
+  results.forEach((result, index) => {
+    if (result.status === 'rejected') {
+      const statusCode = result.reason?.statusCode;
+      if (statusCode === 410 || statusCode === 404) {
+        pushSubscriptionsDb.removeSubscription(subscriptions[index].endpoint);
+      }
+    }
+  });
+}
+
+function notifyUserIfEnabled({ userId, event }) {
+  if (!userId || !event) {
+    return;
+  }
+
+  const preferences = notificationPreferencesDb.getPreferences(userId);
+  if (!shouldSendPush(preferences, event)) {
+    return;
+  }
+  if (isDuplicate(event)) {
+    return;
+  }
+
+  sendWebPush(userId, event).catch((err) => {
+    console.error('Web push send error:', err);
+  });
+}
+
+function notifyRunStopped({ userId, provider, sessionId = null, stopReason = 'completed', sessionName = null }) {
+  notifyUserIfEnabled({
+    userId,
+    event: createNotificationEvent({
+      provider,
+      sessionId,
+      kind: 'stop',
+      code: 'run.stopped',
+      meta: { stopReason, sessionName },
+      severity: 'info',
+      dedupeKey: `${provider}:run:stop:${sessionId || 'none'}:${stopReason}`
+    })
+  });
+}
+
+function notifyRunFailed({ userId, provider, sessionId = null, error, sessionName = null }) {
+  const errorMessage = normalizeErrorMessage(error);
+
+  notifyUserIfEnabled({
+    userId,
+    event: createNotificationEvent({
+      provider,
+      sessionId,
+      kind: 'error',
+      code: 'run.failed',
+      meta: { error: errorMessage, sessionName },
+      severity: 'error',
+      dedupeKey: `${provider}:run:error:${sessionId || 'none'}:${errorMessage}`
+    })
+  });
+}
+
+export {
+  createNotificationEvent,
+  notifyUserIfEnabled,
+  notifyRunStopped,
+  notifyRunFailed
+};

server/services/vapid-keys.js

@@ -0,0 +1,35 @@
+import webPush from 'web-push';
+import { db } from '../database/db.js';
+
+let cachedKeys = null;
+
+function ensureVapidKeys() {
+  if (cachedKeys) return cachedKeys;
+
+  const row = db.prepare('SELECT public_key, private_key FROM vapid_keys ORDER BY id DESC LIMIT 1').get();
+  if (row) {
+    cachedKeys = { publicKey: row.public_key, privateKey: row.private_key };
+    return cachedKeys;
+  }
+
+  const keys = webPush.generateVAPIDKeys();
+  db.prepare('INSERT INTO vapid_keys (public_key, private_key) VALUES (?, ?)').run(keys.publicKey, keys.privateKey);
+  cachedKeys = keys;
+  return cachedKeys;
+}
+
+function getPublicKey() {
+  return ensureVapidKeys().publicKey;
+}
+
+function configureWebPush() {
+  const keys = ensureVapidKeys();
+  webPush.setVapidDetails(
+    'mailto:noreply@claudecodeui.local',
+    keys.publicKey,
+    keys.privateKey
+  );
+  console.log('Web Push notifications configured');
+}
+
+export { ensureVapidKeys, getPublicKey, configureWebPush };

server/shared/interfaces.ts

@@ -0,0 +1,48 @@
+import type {
+  FetchHistoryOptions,
+  FetchHistoryResult,
+  LLMProvider,
+  McpScope,
+  NormalizedMessage,
+  ProviderAuthStatus,
+  ProviderMcpServer,
+  UpsertProviderMcpServerInput,
+} from '@/shared/types.js';
+
+/**
+ * Main provider contract for CLI and SDK integrations.
+ *
+ * Each concrete provider owns its MCP/auth handlers plus the provider-specific
+ * logic for converting native events/history into the app's normalized shape.
+ */
+export interface IProvider {
+  readonly id: LLMProvider;
+  readonly mcp: IProviderMcp;
+  readonly auth: IProviderAuth;
+
+  normalizeMessage(raw: unknown, sessionId: string | null): NormalizedMessage[];
+  fetchHistory(sessionId: string, options?: FetchHistoryOptions): Promise<FetchHistoryResult>;
+}
+
+
+/**
+ * Auth contract for one provider.
+ */
+export interface IProviderAuth {
+  /**
+   * Checks whether the provider is installed and has usable credentials.
+   */
+  getStatus(): Promise<ProviderAuthStatus>;
+}
+
+/**
+ * MCP contract for one provider.
+ */
+export interface IProviderMcp {
+  listServers(options?: { workspacePath?: string }): Promise<Record<McpScope, ProviderMcpServer[]>>;
+  listServersForScope(scope: McpScope, options?: { workspacePath?: string }): Promise<ProviderMcpServer[]>;
+  upsertServer(input: UpsertProviderMcpServerInput): Promise<ProviderMcpServer>;
+  removeServer(
+    input: { name: string; scope?: McpScope; workspacePath?: string },
+  ): Promise<{ removed: boolean; provider: LLMProvider; name: string; scope: McpScope }>;
+}

server/shared/types.ts

@@ -0,0 +1,179 @@
+// -------------- HTTP API response shapes for the server, shared across modules --------------
+
+export type ApiSuccessShape<TData = unknown> = {
+  success: true;
+  data: TData;
+};
+
+export type ApiErrorShape = {
+  success: false;
+  error: {
+    code: string;
+    message: string;
+    details?: unknown;
+  };
+};
+
+// ---------------------------------------------------------------------------------------------
+
+export type LLMProvider = 'claude' | 'codex' | 'gemini' | 'cursor';
+
+// ---------------------------------------------------------------------------------------------
+
+export type MessageKind =
+  | 'text'
+  | 'tool_use'
+  | 'tool_result'
+  | 'thinking'
+  | 'stream_delta'
+  | 'stream_end'
+  | 'error'
+  | 'complete'
+  | 'status'
+  | 'permission_request'
+  | 'permission_cancelled'
+  | 'session_created'
+  | 'interactive_prompt'
+  | 'task_notification';
+
+/**
+ * Provider-neutral message event emitted over REST and realtime transports.
+ *
+ * Providers all produce their own native SDK/CLI event shapes, so this type keeps
+ * the common envelope strict while allowing provider-specific details to ride
+ * along as optional properties.
+ */
+export type NormalizedMessage = {
+  id: string;
+  sessionId: string;
+  timestamp: string;
+  provider: LLMProvider;
+  kind: MessageKind;
+  role?: 'user' | 'assistant';
+  content?: string;
+  images?: unknown;
+  toolName?: string;
+  toolInput?: unknown;
+  toolId?: string;
+  toolResult?: {
+    content?: string;
+    isError?: boolean;
+    toolUseResult?: unknown;
+  };
+  isError?: boolean;
+  text?: string;
+  tokens?: number;
+  canInterrupt?: boolean;
+  requestId?: string;
+  input?: unknown;
+  context?: unknown;
+  reason?: string;
+  newSessionId?: string;
+  status?: string;
+  summary?: string;
+  tokenBudget?: unknown;
+  subagentTools?: unknown;
+  toolUseResult?: unknown;
+  sequence?: number;
+  rowid?: number;
+  [key: string]: unknown;
+};
+
+/**
+ * Pagination and provider lookup options for reading persisted session history.
+ */
+export type FetchHistoryOptions = {
+  /** Claude project folder name. Required by Claude history lookup. */
+  projectName?: string;
+  /** Absolute workspace path. Required by Cursor to compute its chat hash. */
+  projectPath?: string;
+  /** Page size. `null` means all messages. */
+  limit?: number | null;
+  /** Pagination offset from the newest messages. */
+  offset?: number;
+};
+
+/**
+ * Provider-neutral history result returned by the unified messages endpoint.
+ */
+export type FetchHistoryResult = {
+  messages: NormalizedMessage[];
+  total: number;
+  hasMore: boolean;
+  offset: number;
+  limit: number | null;
+  tokenUsage?: unknown;
+};
+
+// ---------------------------------------------------------------------------------------------
+
+export type AppErrorOptions = {
+  code?: string;
+  statusCode?: number;
+  details?: unknown;
+};
+
+// -------------------- MCP related shared types --------------------
+export type McpScope = 'user' | 'local' | 'project';
+
+export type McpTransport = 'stdio' | 'http' | 'sse';
+
+/**
+ * Provider MCP server descriptor normalized for frontend consumption.
+ */
+export type ProviderMcpServer = {
+  provider: LLMProvider;
+  name: string;
+  scope: McpScope;
+  transport: McpTransport;
+  command?: string;
+  args?: string[];
+  env?: Record<string, string>;
+  cwd?: string;
+  url?: string;
+  headers?: Record<string, string>;
+  envVars?: string[];
+  bearerTokenEnvVar?: string;
+  envHttpHeaders?: Record<string, string>;
+};
+
+/**
+ * Shared payload shape for MCP server create/update operations.
+ */
+export type UpsertProviderMcpServerInput = {
+  name: string;
+  scope?: McpScope;
+  transport: McpTransport;
+  workspacePath?: string;
+  command?: string;
+  args?: string[];
+  env?: Record<string, string>;
+  cwd?: string;
+  url?: string;
+  headers?: Record<string, string>;
+  envVars?: string[];
+  bearerTokenEnvVar?: string;
+  envHttpHeaders?: Record<string, string>;
+};
+
+// ---------------------------------------------------------------------------------------------
+
+// -------------------- Provider auth status types --------------------
+/**
+ * Result of a provider status check (installation + authentication).
+ *
+ * installed - Whether the provider's CLI/SDK is available
+ * provider - Provider id the status belongs to
+ * authenticated - Whether valid credentials exist
+ * email - User email or auth method identifier
+ * method - Auth method (e.g. 'api_key', 'credentials_file')
+ * [error] - Error message if not installed or not authenticated
+ */
+export type ProviderAuthStatus = {
+  installed: boolean;
+  provider: LLMProvider;
+  authenticated: boolean;
+  email: string | null;
+  method: string | null;
+  error?: string;
+};

server/shared/utils.ts

@@ -0,0 +1,208 @@
+
+import { randomUUID } from 'node:crypto';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+
+import type { NextFunction, Request, RequestHandler, Response } from 'express';
+
+import type {
+  ApiErrorShape,
+  ApiSuccessShape,
+  AppErrorOptions,
+  NormalizedMessage,
+} from '@/shared/types.js';
+
+type NormalizedMessageInput =
+  {
+    kind: NormalizedMessage['kind'];
+    provider: NormalizedMessage['provider'];
+    id?: string | null;
+    sessionId?: string | null;
+    timestamp?: string | null;
+  } & Record<string, unknown>;
+
+export function createApiSuccessResponse<TData>(
+  data: TData,
+): ApiSuccessShape<TData> {
+  return {
+    success: true,
+    data,
+  };
+}
+
+export function createApiErrorResponse(
+  code: string,
+  message: string,
+  details?: unknown
+): ApiErrorShape {
+  return {
+    success: false,
+    error: {
+      code,
+      message,
+      details,
+    }
+  };
+}
+
+export function asyncHandler(
+  handler: (req: Request, res: Response, next: NextFunction) => Promise<unknown>
+): RequestHandler {
+  return (req, res, next) => {
+    void Promise.resolve(handler(req, res, next)).catch(next);
+  };
+}
+
+// --------- Global app error class for consistent error handling across the server ---------
+export class AppError extends Error {
+  readonly code: string;
+  readonly statusCode: number;
+  readonly details?: unknown;
+
+  constructor(message: string, options: AppErrorOptions = {}) {
+    super(message);
+    this.name = 'AppError';
+    this.code = options.code ?? 'INTERNAL_ERROR';
+    this.statusCode = options.statusCode ?? 500;
+    this.details = options.details;
+  }
+}
+
+// -------------------------------------------------------------------------------------------
+
+// ------------------------ Normalized provider message helpers ------------------------
+/**
+ * Generates a stable unique id for normalized provider messages.
+ */
+export function generateMessageId(prefix = 'msg'): string {
+  return `${prefix}_${randomUUID()}`;
+}
+
+/**
+ * Creates a normalized provider message and fills the shared envelope fields.
+ *
+ * Provider adapters and live SDK handlers pass through provider-specific fields,
+ * while this helper guarantees every emitted event has an id, session id,
+ * timestamp, and provider marker.
+ */
+export function createNormalizedMessage(fields: NormalizedMessageInput): NormalizedMessage {
+  return {
+    ...fields,
+    id: fields.id || generateMessageId(fields.kind),
+    sessionId: fields.sessionId || '',
+    timestamp: fields.timestamp || new Date().toISOString(),
+    provider: fields.provider,
+  };
+}
+
+// -------------------------------------------------------------------------------------------
+
+// ------------------------ The following are mainly for provider MCP runtimes ------------------------
+/**
+ * Safely narrows an unknown value to a plain object record.
+ *
+ * This deliberately rejects arrays, `null`, and primitive values so callers can
+ * treat the returned value as a JSON-style object map without repeating the same
+ * defensive shape checks at every config read site.
+ */
+export const readObjectRecord = (value: unknown): Record<string, unknown> | null => {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    return null;
+  }
+
+  return value as Record<string, unknown>;
+};
+
+/**
+ * Reads an optional string from unknown input and normalizes empty or whitespace-only
+ * values to `undefined`.
+ *
+ * This is useful when parsing config files where a field may be missing, present
+ * with the wrong type, or present as an empty string that should be treated as
+ * "not configured".
+ */
+export const readOptionalString = (value: unknown): string | undefined => {
+  if (typeof value !== 'string') {
+    return undefined;
+  }
+
+  const normalized = value.trim();
+  return normalized.length > 0 ? normalized : undefined;
+};
+
+/**
+ * Reads an optional string array from unknown input.
+ *
+ * Non-array values are ignored, and any array entries that are not strings are
+ * filtered out. This lets provider config readers consume loosely shaped JSON/TOML
+ * data without failing on incidental invalid members.
+ */
+export const readStringArray = (value: unknown): string[] | undefined => {
+  if (!Array.isArray(value)) {
+    return undefined;
+  }
+
+  return value.filter((entry): entry is string => typeof entry === 'string');
+};
+
+/**
+ * Reads an optional string-to-string map from unknown input.
+ *
+ * The function first ensures the source value is a plain object, then keeps only
+ * keys whose values are strings. If no valid entries remain, it returns `undefined`
+ * so callers can distinguish "no usable map" from an empty object that was
+ * intentionally authored downstream.
+ */
+export const readStringRecord = (value: unknown): Record<string, string> | undefined => {
+  const record = readObjectRecord(value);
+  if (!record) {
+    return undefined;
+  }
+
+  const normalized: Record<string, string> = {};
+  for (const [key, entry] of Object.entries(record)) {
+    if (typeof entry === 'string') {
+      normalized[key] = entry;
+    }
+  }
+
+  return Object.keys(normalized).length > 0 ? normalized : undefined;
+};
+
+/**
+ * Reads a JSON config file and guarantees a plain object result.
+ *
+ * Missing files are treated as an empty config object so provider-specific MCP
+ * readers can operate against first-run environments without special-case file
+ * existence checks. If the file exists but contains invalid JSON, the parse error
+ * is preserved and rethrown.
+ */
+export const readJsonConfig = async (filePath: string): Promise<Record<string, unknown>> => {
+  try {
+    const content = await readFile(filePath, 'utf8');
+    const parsed = JSON.parse(content) as Record<string, unknown>;
+    return readObjectRecord(parsed) ?? {};
+  } catch (error) {
+    const code = (error as NodeJS.ErrnoException).code;
+    if (code === 'ENOENT') {
+      return {};
+    }
+
+    throw error;
+  }
+};
+
+/**
+ * Writes a JSON config file with stable, human-readable formatting.
+ *
+ * The parent directory is created automatically so callers can persist config into
+ * provider-specific folders without pre-creating the directory tree. Output always
+ * ends with a trailing newline to keep the file diff-friendly.
+ */
+export const writeJsonConfig = async (filePath: string, data: Record<string, unknown>): Promise<void> => {
+  await mkdir(path.dirname(filePath), { recursive: true });
+  await writeFile(filePath, `${JSON.stringify(data, null, 2)}\n`, 'utf8');
+};
+
+// -------------------------------------------------------------------------------------------
+

server/tsconfig.json

@@ -0,0 +1,33 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "lib": ["ES2022"],
+    "baseUrl": ".",
+    "paths": {
+      // In the backend config, "@" maps to the /server directory itself.
+      "@/*": ["*"]
+    },
+    // The backend is still mostly JavaScript today, so allowJs lets us add a real
+    // TypeScript build without forcing a large rename before the tooling is usable.
+    "allowJs": true,
+    // Keep the migration incremental: existing JS keeps building, while any new TS files
+    // still go through the normal TypeScript pipeline and strict checks.
+    "checkJs": false,
+    "strict": true,
+    "noEmitOnError": true,
+    // The backend build emits both /server and /shared into dist-server, so rootDir must
+    // stay one level above this file even though the config itself now lives in /server.
+    "rootDir": "..",
+    "outDir": "../dist-server",
+    "sourceMap": true,
+    "resolveJsonModule": true,
+    "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true,
+    "skipLibCheck": true,
+    "types": ["node"]
+  },
+  "include": ["./**/*.js", "./**/*.ts", "../shared/**/*.js", "../shared/**/*.ts"],
+  "exclude": ["../dist", "../dist-server", "../node_modules", "../src"]
+}

server/utils/mcp-detector.js

@@ -145,54 +145,3 @@ export async function detectTaskMasterMCPServer() {
     }
 }
 
-/**
- * Get all configured MCP servers (not just TaskMaster)
- * @returns {Promise<Object>} All MCP servers configuration
- */
-export async function getAllMCPServers() {
-    try {
-        const homeDir = os.homedir();
-        const configPaths = [
-            path.join(homeDir, '.claude.json'),
-            path.join(homeDir, '.claude', 'settings.json')
-        ];
-        
-        let configData = null;
-        let configPath = null;
-        
-        // Try to read from either config file
-        for (const filepath of configPaths) {
-            try {
-                const fileContent = await fsPromises.readFile(filepath, 'utf8');
-                configData = JSON.parse(fileContent);
-                configPath = filepath;
-                break;
-            } catch (error) {
-                continue;
-            }
-        }
-        
-        if (!configData) {
-            return {
-                hasConfig: false,
-                servers: {},
-                projectServers: {}
-            };
-        }
-
-        return {
-            hasConfig: true,
-            configPath,
-            servers: configData.mcpServers || {},
-            projectServers: configData.projects || {}
-        };
-    } catch (error) {
-        console.error('Error getting all MCP servers:', error);
-        return {
-            hasConfig: false,
-            error: error.message,
-            servers: {},
-            projectServers: {}
-        };
-    }
-}

server/utils/plugin-loader.js

@@ -93,6 +93,55 @@ export function validateManifest(manifest) {
   return { valid: true };
 }
 
+const BUILD_TIMEOUT_MS = 60_000;
+
+/** Run `npm run build` if the plugin's package.json declares a build script. */
+function runBuildIfNeeded(dir, packageJsonPath, onSuccess, onError) {
+  try {
+    const pkg = JSON.parse(fs.readFileSync(packageJsonPath, 'utf-8'));
+    if (!pkg.scripts?.build) {
+      return onSuccess();
+    }
+  } catch {
+    return onSuccess(); // Unreadable package.json — skip build
+  }
+
+  const buildProcess = spawn('npm', ['run', 'build'], {
+    cwd: dir,
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+
+  let stderr = '';
+  let settled = false;
+
+  const timer = setTimeout(() => {
+    if (settled) return;
+    settled = true;
+    buildProcess.removeAllListeners();
+    buildProcess.kill();
+    onError(new Error('npm run build timed out'));
+  }, BUILD_TIMEOUT_MS);
+
+  buildProcess.stderr.on('data', (data) => { stderr += data.toString(); });
+
+  buildProcess.on('close', (code) => {
+    if (settled) return;
+    settled = true;
+    clearTimeout(timer);
+    if (code !== 0) {
+      return onError(new Error(`npm run build failed (exit code ${code}): ${stderr.trim()}`));
+    }
+    onSuccess();
+  });
+
+  buildProcess.on('error', (err) => {
+    if (settled) return;
+    settled = true;
+    clearTimeout(timer);
+    onError(new Error(`Failed to spawn build: ${err.message}`));
+  });
+}
+
 export function scanPlugins() {
   const pluginsDir = getPluginsDir();
   const config = getPluginsConfig();
@@ -289,7 +338,7 @@ export function installPluginFromGit(url) {
       // --ignore-scripts prevents postinstall hooks from executing arbitrary code.
       const packageJsonPath = path.join(tempDir, 'package.json');
       if (fs.existsSync(packageJsonPath)) {
-        const npmProcess = spawn('npm', ['install', '--production', '--ignore-scripts'], {
+        const npmProcess = spawn('npm', ['install', '--ignore-scripts'], {
           cwd: tempDir,
           stdio: ['ignore', 'pipe', 'pipe'],
         });
@@ -299,7 +348,7 @@ export function installPluginFromGit(url) {
             cleanupTemp();
             return reject(new Error(`npm install for ${repoName} failed (exit code ${npmCode})`));
           }
-          finalize(manifest);
+          runBuildIfNeeded(tempDir, packageJsonPath, () => finalize(manifest), (err) => { cleanupTemp(); reject(err); });
         });
 
         npmProcess.on('error', (err) => {
@@ -356,7 +405,7 @@ export function updatePluginFromGit(name) {
       // Re-run npm install if package.json exists
       const packageJsonPath = path.join(pluginDir, 'package.json');
       if (fs.existsSync(packageJsonPath)) {
-        const npmProcess = spawn('npm', ['install', '--production', '--ignore-scripts'], {
+        const npmProcess = spawn('npm', ['install', '--ignore-scripts'], {
           cwd: pluginDir,
           stdio: ['ignore', 'pipe', 'pipe'],
         });
@@ -364,7 +413,7 @@ export function updatePluginFromGit(name) {
           if (npmCode !== 0) {
             return reject(new Error(`npm install for ${name} failed (exit code ${npmCode})`));
           }
-          resolve(manifest);
+          runBuildIfNeeded(pluginDir, packageJsonPath, () => resolve(manifest), (err) => reject(err));
         });
         npmProcess.on('error', (err) => reject(err));
       } else {

server/utils/runtime-paths.js

@@ -0,0 +1,37 @@
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+export function getModuleDir(importMetaUrl) {
+  return path.dirname(fileURLToPath(importMetaUrl));
+}
+
+export function findServerRoot(startDir) {
+  // Source files live under /server, while compiled files live under /dist-server/server.
+  // Walking up to the nearest "server" folder gives every backend module one stable anchor
+  // that works in both layouts instead of relying on fragile "../.." assumptions.
+  let currentDir = startDir;
+
+  while (path.basename(currentDir) !== 'server') {
+    const parentDir = path.dirname(currentDir);
+
+    if (parentDir === currentDir) {
+      throw new Error(`Could not resolve the backend server root from "${startDir}".`);
+    }
+
+    currentDir = parentDir;
+  }
+
+  return currentDir;
+}
+
+export function findAppRoot(startDir) {
+  const serverRoot = findServerRoot(startDir);
+  const parentOfServerRoot = path.dirname(serverRoot);
+
+  // Source files live at <app>/server, while compiled files live at <app>/dist-server/server.
+  // When the nearest server folder sits inside dist-server we need to hop one extra level up
+  // so repo-level files still resolve from the real app root instead of the build directory.
+  return path.basename(parentOfServerRoot) === 'dist-server'
+    ? path.dirname(parentOfServerRoot)
+    : parentOfServerRoot;
+}

shared/modelConstants.js

@@ -18,9 +18,10 @@ export const CLAUDE_MODELS = {
     { value: "haiku", label: "Haiku" },
     { value: "opusplan", label: "Opus Plan" },
     { value: "sonnet[1m]", label: "Sonnet [1M]" },
+    { value: "opus[1m]", label: "Opus [1M]" },
   ],
 
-  DEFAULT: "sonnet",
+  DEFAULT: "opus",
 };
 
 /**
@@ -58,6 +59,7 @@ export const CURSOR_MODELS = {
 export const CODEX_MODELS = {
   OPTIONS: [
     { value: "gpt-5.4", label: "GPT-5.4" },
+    { value: "gpt-5.4-mini", label: "GPT-5.4 mini" },
     { value: "gpt-5.3-codex", label: "GPT-5.3 Codex" },
     { value: "gpt-5.2-codex", label: "GPT-5.2 Codex" },
     { value: "gpt-5.2", label: "GPT-5.2" },
@@ -88,5 +90,5 @@ export const GEMINI_MODELS = {
     },
   ],
 
-  DEFAULT: "gemini-2.5-flash",
+  DEFAULT: "gemini-3.1-pro-preview",
 };

shared/networkHosts.js

@@ -0,0 +1,22 @@
+export function isWildcardHost(host) {
+  return host === '0.0.0.0' || host === '::';
+}
+
+export function isLoopbackHost(host) {
+  return host === 'localhost' || host === '127.0.0.1' || host === '::1' || host === '[::1]';
+}
+
+export function normalizeLoopbackHost(host) {
+  if (!host) {
+    return host;
+  }
+  return isLoopbackHost(host) ? 'localhost' : host;
+}
+
+// Use localhost for connectable loopback and wildcard addresses in browser-facing URLs.
+export function getConnectableHost(host) {
+  if (!host) {
+    return 'localhost';
+  }
+  return isWildcardHost(host) || isLoopbackHost(host) ? 'localhost' : host;
+}

src/components/app/AppContent.tsx

@@ -7,7 +7,6 @@ import { useWebSocket } from '../../contexts/WebSocketContext';
 import { useDeviceSettings } from '../../hooks/useDeviceSettings';
 import { useSessionProtection } from '../../hooks/useSessionProtection';
 import { useProjectsState } from '../../hooks/useProjectsState';
-import MobileNav from './MobileNav';
 
 export default function AppContent() {
   const navigate = useNavigate();
@@ -33,7 +32,6 @@ export default function AppContent() {
     activeTab,
     sidebarOpen,
     isLoadingProjects,
-    isInputFocused,
     externalMessageUpdate,
     setActiveTab,
     setSidebarOpen,
@@ -72,6 +70,40 @@ export default function AppContent() {
     };
   }, [openSettings]);
 
+  useEffect(() => {
+    if (typeof navigator === 'undefined' || !('serviceWorker' in navigator)) {
+      return undefined;
+    }
+
+    const handleServiceWorkerMessage = (event: MessageEvent) => {
+      const message = event.data;
+      if (!message || message.type !== 'notification:navigate') {
+        return;
+      }
+
+      if (typeof message.provider === 'string' && message.provider.trim()) {
+        localStorage.setItem('selected-provider', message.provider);
+      }
+
+      setActiveTab('chat');
+      setSidebarOpen(false);
+      void refreshProjectsSilently();
+
+      if (typeof message.sessionId === 'string' && message.sessionId) {
+        navigate(`/session/${message.sessionId}`);
+        return;
+      }
+
+      navigate('/');
+    };
+
+    navigator.serviceWorker.addEventListener('message', handleServiceWorkerMessage);
+
+    return () => {
+      navigator.serviceWorker.removeEventListener('message', handleServiceWorkerMessage);
+    };
+  }, [navigate, refreshProjectsSilently, setActiveTab, setSidebarOpen]);
+
   // Permission recovery: query pending permissions on WebSocket reconnect or session change
   useEffect(() => {
     const isReconnect = isConnected && !wasConnectedRef.current;
@@ -125,7 +157,7 @@ export default function AppContent() {
         </div>
       )}
 
-      <div className={`flex min-w-0 flex-1 flex-col ${isMobile ? 'pb-mobile-nav' : ''}`}>
+      <div className="flex min-w-0 flex-1 flex-col">
         <MainContent
           selectedProject={selectedProject}
           selectedSession={selectedSession}
@@ -150,14 +182,6 @@ export default function AppContent() {
         />
       </div>
 
-      {isMobile && (
-        <MobileNav
-          activeTab={activeTab}
-          setActiveTab={setActiveTab}
-          isInputFocused={isInputFocused}
-        />
-      )}
-
     </div>
   );
 }

src/components/app/MobileNav.tsx

@@ -1,179 +0,0 @@
-import { useState, useRef, useEffect, type Dispatch, type SetStateAction } from 'react';
-import { useTranslation } from 'react-i18next';
-import {
-  MessageSquare,
-  Folder,
-  Terminal,
-  GitBranch,
-  ClipboardCheck,
-  Ellipsis,
-  Puzzle,
-  Box,
-  Database,
-  Globe,
-  Wrench,
-  Zap,
-  BarChart3,
-  type LucideIcon,
-} from 'lucide-react';
-import { useTasksSettings } from '../../contexts/TasksSettingsContext';
-import { usePlugins } from '../../contexts/PluginsContext';
-import { AppTab } from '../../types/app';
-
-const PLUGIN_ICON_MAP: Record<string, LucideIcon> = {
-  Puzzle, Box, Database, Globe, Terminal, Wrench, Zap, BarChart3, Folder, MessageSquare, GitBranch,
-};
-
-type CoreTabId = Exclude<AppTab, `plugin:${string}` | 'preview'>;
-type CoreNavItem = {
-  id: CoreTabId;
-  icon: LucideIcon;
-  label: string;
-};
-
-type MobileNavProps = {
-  activeTab: AppTab;
-  setActiveTab: Dispatch<SetStateAction<AppTab>>;
-  isInputFocused: boolean;
-};
-
-export default function MobileNav({ activeTab, setActiveTab, isInputFocused }: MobileNavProps) {
-  const { t } = useTranslation(['common', 'settings']);
-  const { tasksEnabled, isTaskMasterInstalled } = useTasksSettings();
-  const shouldShowTasksTab = Boolean(tasksEnabled && isTaskMasterInstalled);
-  const { plugins } = usePlugins();
-  const [moreOpen, setMoreOpen] = useState(false);
-  const moreRef = useRef<HTMLDivElement | null>(null);
-
-  const enabledPlugins = plugins.filter((p) => p.enabled);
-  const hasPlugins = enabledPlugins.length > 0;
-  const isPluginActive = activeTab.startsWith('plugin:');
-
-  // Close the menu on outside tap
-  useEffect(() => {
-    if (!moreOpen) return;
-    const handleTap = (e: PointerEvent) => {
-      const target = e.target;
-      if (moreRef.current && target instanceof Node && !moreRef.current.contains(target)) {
-        setMoreOpen(false);
-      }
-    };
-    document.addEventListener('pointerdown', handleTap);
-    return () => document.removeEventListener('pointerdown', handleTap);
-  }, [moreOpen]);
-
-  // Close menu when a plugin tab is selected
-  const selectPlugin = (name: string) => {
-    const pluginTab = `plugin:${name}` as AppTab;
-    setActiveTab(pluginTab);
-    setMoreOpen(false);
-  };
-
-  const baseCoreItems: CoreNavItem[] = [
-    { id: 'chat', icon: MessageSquare, label: 'Chat' },
-    { id: 'shell', icon: Terminal, label: 'Shell' },
-    { id: 'files', icon: Folder, label: 'Files' },
-    { id: 'git', icon: GitBranch, label: 'Git' },
-  ];
-  const coreItems: CoreNavItem[] = shouldShowTasksTab
-    ? [...baseCoreItems, { id: 'tasks', icon: ClipboardCheck, label: 'Tasks' }]
-    : baseCoreItems;
-
-  return (
-    <div
-      className={`fixed bottom-0 left-0 right-0 z-50 transform px-3 pb-[max(8px,env(safe-area-inset-bottom))] transition-transform duration-300 ease-in-out ${isInputFocused ? 'translate-y-full' : 'translate-y-0'
-        }`}
-    >
-      <div className="nav-glass mobile-nav-float rounded-2xl border border-border/30">
-        <div className="flex items-center justify-around gap-0.5 px-1 py-1.5">
-          {coreItems.map((item) => {
-            const Icon = item.icon;
-            const isActive = activeTab === item.id;
-
-            return (
-              <button
-                key={item.id}
-                onClick={() => setActiveTab(item.id)}
-                onTouchStart={(e) => {
-                  e.preventDefault();
-                  setActiveTab(item.id);
-                }}
-                className={`relative flex flex-1 touch-manipulation flex-col items-center justify-center gap-0.5 rounded-xl px-3 py-2 transition-all duration-200 active:scale-95 ${isActive
-                  ? 'text-primary'
-                  : 'text-muted-foreground hover:text-foreground'
-                  }`}
-                aria-label={item.label}
-                aria-current={isActive ? 'page' : undefined}
-              >
-                {isActive && (
-                  <div className="bg-primary/8 dark:bg-primary/12 absolute inset-0 rounded-xl" />
-                )}
-                <Icon
-                  className={`relative z-10 transition-all duration-200 ${isActive ? 'h-5 w-5' : 'h-[18px] w-[18px]'}`}
-                  strokeWidth={isActive ? 2.4 : 1.8}
-                />
-                <span className={`relative z-10 text-[10px] font-medium transition-all duration-200 ${isActive ? 'opacity-100' : 'opacity-60'}`}>
-                  {item.label}
-                </span>
-              </button>
-            );
-          })}
-
-          {/* "More" button — only shown when there are enabled plugins */}
-          {hasPlugins && (
-            <div ref={moreRef} className="relative flex-1">
-              <button
-                onClick={() => setMoreOpen((v) => !v)}
-                onTouchStart={(e) => {
-                  e.preventDefault();
-                  setMoreOpen((v) => !v);
-                }}
-                className={`relative flex w-full touch-manipulation flex-col items-center justify-center gap-0.5 rounded-xl px-3 py-2 transition-all duration-200 active:scale-95 ${isPluginActive || moreOpen
-                    ? 'text-primary'
-                    : 'text-muted-foreground hover:text-foreground'
-                  }`}
-                aria-label="More plugins"
-                aria-expanded={moreOpen}
-              >
-                {(isPluginActive && !moreOpen) && (
-                  <div className="bg-primary/8 dark:bg-primary/12 absolute inset-0 rounded-xl" />
-                )}
-                <Ellipsis
-                  className={`relative z-10 transition-all duration-200 ${isPluginActive ? 'h-5 w-5' : 'h-[18px] w-[18px]'}`}
-                  strokeWidth={isPluginActive ? 2.4 : 1.8}
-                />
-                <span className={`relative z-10 text-[10px] font-medium transition-all duration-200 ${isPluginActive || moreOpen ? 'opacity-100' : 'opacity-60'}`}>
-                  {t('settings:pluginSettings.morePlugins')}
-                </span>
-              </button>
-
-              {/* Popover menu */}
-              {moreOpen && (
-                <div className="animate-in fade-in slide-in-from-bottom-2 absolute bottom-full right-0 z-[60] mb-2 min-w-[180px] rounded-xl border border-border/40 bg-popover py-1.5 shadow-lg duration-150">
-                  {enabledPlugins.map((p) => {
-                    const Icon = PLUGIN_ICON_MAP[p.icon] || Puzzle;
-                    const isActive = activeTab === `plugin:${p.name}`;
-
-                    return (
-                      <button
-                        key={p.name}
-                        onClick={() => selectPlugin(p.name)}
-                        className={`flex w-full items-center gap-2.5 px-3.5 py-2.5 text-sm transition-colors ${isActive
-                            ? 'bg-primary/8 text-primary'
-                            : 'text-foreground hover:bg-muted/60'
-                          }`}
-                      >
-                        <Icon className="h-4 w-4 flex-shrink-0" strokeWidth={isActive ? 2.2 : 1.8} />
-                        <span className="truncate">{p.displayName}</span>
-                      </button>
-                    );
-                  })}
-                </div>
-              )}
-            </div>
-          )}
-        </div>
-      </div>
-    </div>
-  );
-}

src/components/auth/view/AuthInputField.tsx

@@ -6,8 +6,16 @@ type AuthInputFieldProps = {
   placeholder: string;
   isDisabled: boolean;
   type?: 'text' | 'password' | 'email';
+  name?: string;
+  autoComplete?: string;
 };
 
+/**
+ * A labelled input field for authentication forms.
+ * Renders a `<label>` / `<input>` pair and forwards browser autofill hints
+ * (`name`, `autoComplete`) so that password managers can identify and fill
+ * the field correctly.
+ */
 export default function AuthInputField({
   id,
   label,
@@ -16,6 +24,8 @@ export default function AuthInputField({
   placeholder,
   isDisabled,
   type = 'text',
+  name,
+  autoComplete,
 }: AuthInputFieldProps) {
   return (
     <div>
@@ -25,6 +35,8 @@ export default function AuthInputField({
       <input
         id={id}
         type={type}
+        name={name ?? id}
+        autoComplete={autoComplete}
         value={value}
         onChange={(event) => onChange(event.target.value)}
         className="w-full rounded-md border border-border bg-background px-3 py-2 text-foreground focus:border-transparent focus:outline-none focus:ring-2 focus:ring-blue-500"

src/components/auth/view/AuthLoadingScreen.tsx

@@ -12,7 +12,7 @@ export default function AuthLoadingScreen() {
           </div>
         </div>
 
-        <h1 className="mb-2 text-2xl font-bold text-foreground">Claude Code UI</h1>
+        <h1 className="mb-2 text-2xl font-bold text-foreground">CloudCLI</h1>
 
         <div className="flex items-center justify-center space-x-2">
           {loadingDotAnimationDelays.map((delay) => (

src/components/auth/view/AuthScreenLayout.tsx

@@ -1,5 +1,6 @@
 import type { ReactNode } from 'react';
 import { MessageSquare } from 'lucide-react';
+import { IS_PLATFORM } from '../../../constants/config';
 
 type AuthScreenLayoutProps = {
   title: string;
@@ -37,6 +38,22 @@ export default function AuthScreenLayout({
           <div className="text-center">
             <p className="text-sm text-muted-foreground">{footerText}</p>
           </div>
+
+          {!IS_PLATFORM && (
+            <div className="flex items-center justify-center gap-1.5 pt-2">
+              <svg className="h-3.5 w-3.5 text-muted-foreground/50" fill="currentColor" viewBox="0 0 24 24" aria-hidden="true">
+                <path d="M12 2C6.477 2 2 6.484 2 12.017c0 4.425 2.865 8.18 6.839 9.504.5.092.682-.217.682-.483 0-.237-.008-.868-.013-1.703-2.782.605-3.369-1.343-3.369-1.343-.454-1.158-1.11-1.466-1.11-1.466-.908-.62.069-.608.069-.608 1.003.07 1.531 1.032 1.531 1.032.892 1.53 2.341 1.088 2.91.832.092-.647.35-1.088.636-1.338-2.22-.253-4.555-1.113-4.555-4.951 0-1.093.39-1.988 1.029-2.688-.103-.253-.446-1.272.098-2.65 0 0 .84-.27 2.75 1.026A9.564 9.564 0 0112 6.844c.85.004 1.705.115 2.504.337 1.909-1.296 2.747-1.027 2.747-1.027.546 1.379.202 2.398.1 2.651.64.7 1.028 1.595 1.028 2.688 0 3.848-2.339 4.695-4.566 4.943.359.309.678.92.678 1.855 0 1.338-.012 2.419-.012 2.747 0 .268.18.58.688.482A10.019 10.019 0 0022 12.017C22 6.484 17.522 2 12 2z" />
+              </svg>
+              <a
+                href="https://github.com/siteboon/claudecodeui"
+                target="_blank"
+                rel="noopener noreferrer"
+                className="text-xs text-muted-foreground/50 transition-colors hover:text-muted-foreground"
+              >
+                CloudCLI is open source
+              </a>
+            </div>
+          )}
         </div>
       </div>
     </div>

src/components/auth/view/LoginForm.tsx

@@ -16,6 +16,11 @@ const initialState: LoginFormState = {
   password: '',
 };
 
+/**
+ * Login form component.
+ * Handles credential input with browser autofill support (`autocomplete`
+ * attributes) so that password managers can offer to fill saved credentials.
+ */
 export default function LoginForm() {
   const { t } = useTranslation('auth');
   const { login } = useAuth();
@@ -53,7 +58,7 @@ export default function LoginForm() {
     <AuthScreenLayout
       title={t('login.title')}
       description={t('login.description')}
-      footerText="Enter your credentials to access Claude Code UI"
+      footerText="Enter your credentials to access CloudCLI"
     >
       <form onSubmit={handleSubmit} className="space-y-4">
         <AuthInputField
@@ -63,6 +68,7 @@ export default function LoginForm() {
           onChange={(value) => updateField('username', value)}
           placeholder={t('login.placeholders.username')}
           isDisabled={isSubmitting}
+          autoComplete="username"
         />
 
         <AuthInputField
@@ -73,6 +79,7 @@ export default function LoginForm() {
           placeholder={t('login.placeholders.password')}
           isDisabled={isSubmitting}
           type="password"
+          autoComplete="current-password"
         />
 
         <AuthErrorAlert errorMessage={errorMessage} />

src/components/auth/view/SetupForm.tsx

@@ -17,6 +17,11 @@ const initialState: SetupFormState = {
   confirmPassword: '',
 };
 
+/**
+ * Validates the account-setup form state.
+ * @returns An error message string if validation fails, or `null` when the
+ *   form is valid.
+ */
 function validateSetupForm(formState: SetupFormState): string | null {
   if (!formState.username.trim() || !formState.password || !formState.confirmPassword) {
     return 'Please fill in all fields.';
@@ -37,6 +42,12 @@ function validateSetupForm(formState: SetupFormState): string | null {
   return null;
 }
 
+/**
+ * Account setup / registration form.
+ * Uses `autoComplete="new-password"` on password fields so that password
+ * managers recognise this as a registration flow and offer to save the new
+ * credentials after submission.
+ */
 export default function SetupForm() {
   const { register } = useAuth();
 
@@ -71,7 +82,7 @@ export default function SetupForm() {
 
   return (
     <AuthScreenLayout
-      title="Welcome to Claude Code UI"
+      title="Welcome to CloudCLI"
       description="Set up your account to get started"
       footerText="This is a single-user system. Only one account can be created."
       logo={<img src="/logo.svg" alt="CloudCLI" className="h-16 w-16" />}
@@ -79,31 +90,37 @@ export default function SetupForm() {
       <form onSubmit={handleSubmit} className="space-y-4">
         <AuthInputField
           id="username"
+          name="username"
           label="Username"
           value={formState.username}
           onChange={(value) => updateField('username', value)}
           placeholder="Enter your username"
           isDisabled={isSubmitting}
+          autoComplete="username"
         />
 
         <AuthInputField
           id="password"
+          name="password"
           label="Password"
           value={formState.password}
           onChange={(value) => updateField('password', value)}
           placeholder="Enter your password"
           isDisabled={isSubmitting}
           type="password"
+          autoComplete="new-password"
         />
 
         <AuthInputField
           id="confirmPassword"
+          name="confirmPassword"
           label="Confirm Password"
           value={formState.confirmPassword}
           onChange={(value) => updateField('confirmPassword', value)}
           placeholder="Confirm your password"
           isDisabled={isSubmitting}
           type="password"
+          autoComplete="new-password"
         />
 
         <AuthErrorAlert errorMessage={errorMessage} />

src/components/chat/hooks/useChatComposerState.ts

@@ -19,7 +19,7 @@ import type {
   PendingPermissionRequest,
   PermissionMode,
 } from '../types/types';
-import type { Project, ProjectSession, SessionProvider } from '../../../types/app';
+import type { Project, ProjectSession, LLMProvider } from '../../../types/app';
 import { escapeRegExp } from '../utils/chatFormatting';
 import { useFileMentions } from './useFileMentions';
 import { type SlashCommand, useSlashCommands } from './useSlashCommands';
@@ -33,7 +33,7 @@ interface UseChatComposerStateArgs {
   selectedProject: Project | null;
   selectedSession: ProjectSession | null;
   currentSessionId: string | null;
-  provider: SessionProvider;
+  provider: LLMProvider;
   permissionMode: PermissionMode | string;
   cyclePermissionMode: () => void;
   cursorModel: string;
@@ -52,8 +52,9 @@ interface UseChatComposerStateArgs {
   onShowSettings?: () => void;
   pendingViewSessionRef: { current: PendingViewSession | null };
   scrollToBottom: () => void;
-  setChatMessages: Dispatch<SetStateAction<ChatMessage[]>>;
-  setSessionMessages?: Dispatch<SetStateAction<any[]>>;
+  addMessage: (msg: ChatMessage) => void;
+  clearMessages: () => void;
+  rewindMessages: (count: number) => void;
   setIsLoading: (loading: boolean) => void;
   setCanAbortSession: (canAbort: boolean) => void;
   setClaudeStatus: (status: { text: string; tokens: number; can_interrupt: boolean } | null) => void;
@@ -82,6 +83,24 @@ const createFakeSubmitEvent = () => {
 const isTemporarySessionId = (sessionId: string | null | undefined) =>
   Boolean(sessionId && sessionId.startsWith('new-session-'));
 
+const getNotificationSessionSummary = (
+  selectedSession: ProjectSession | null,
+  fallbackInput: string,
+): string | null => {
+  const sessionSummary = selectedSession?.summary || selectedSession?.name || selectedSession?.title;
+  if (typeof sessionSummary === 'string' && sessionSummary.trim()) {
+    const normalized = sessionSummary.replace(/\s+/g, ' ').trim();
+    return normalized.length > 80 ? `${normalized.slice(0, 77)}...` : normalized;
+  }
+
+  const normalizedFallback = fallbackInput.replace(/\s+/g, ' ').trim();
+  if (!normalizedFallback) {
+    return null;
+  }
+
+  return normalizedFallback.length > 80 ? `${normalizedFallback.slice(0, 77)}...` : normalizedFallback;
+};
+
 export function useChatComposerState({
   selectedProject,
   selectedSession,
@@ -105,8 +124,9 @@ export function useChatComposerState({
   onShowSettings,
   pendingViewSessionRef,
   scrollToBottom,
-  setChatMessages,
-  setSessionMessages,
+  addMessage,
+  clearMessages,
+  rewindMessages,
   setIsLoading,
   setCanAbortSession,
   setClaudeStatus,
@@ -137,69 +157,50 @@ export function useChatComposerState({
       const { action, data } = result;
       switch (action) {
         case 'clear':
-          setChatMessages([]);
-          setSessionMessages?.([]);
+          clearMessages();
           break;
 
         case 'help':
-          setChatMessages((previous) => [
-            ...previous,
-            {
-              type: 'assistant',
-              content: data.content,
-              timestamp: Date.now(),
-            },
-          ]);
+          addMessage({
+            type: 'assistant',
+            content: data.content,
+            timestamp: Date.now(),
+          });
           break;
 
         case 'model':
-          setChatMessages((previous) => [
-            ...previous,
-            {
-              type: 'assistant',
-              content: `**Current Model**: ${data.current.model}\n\n**Available Models**:\n\nClaude: ${data.available.claude.join(', ')}\n\nCursor: ${data.available.cursor.join(', ')}`,
-              timestamp: Date.now(),
-            },
-          ]);
+          addMessage({
+            type: 'assistant',
+            content: `**Current Model**: ${data.current.model}\n\n**Available Models**:\n\nClaude: ${data.available.claude.join(', ')}\n\nCursor: ${data.available.cursor.join(', ')}`,
+            timestamp: Date.now(),
+          });
           break;
 
         case 'cost': {
           const costMessage = `**Token Usage**: ${data.tokenUsage.used.toLocaleString()} / ${data.tokenUsage.total.toLocaleString()} (${data.tokenUsage.percentage}%)\n\n**Estimated Cost**:\n- Input: $${data.cost.input}\n- Output: $${data.cost.output}\n- **Total**: $${data.cost.total}\n\n**Model**: ${data.model}`;
-          setChatMessages((previous) => [
-            ...previous,
-            { type: 'assistant', content: costMessage, timestamp: Date.now() },
-          ]);
+          addMessage({ type: 'assistant', content: costMessage, timestamp: Date.now() });
           break;
         }
 
         case 'status': {
           const statusMessage = `**System Status**\n\n- Version: ${data.version}\n- Uptime: ${data.uptime}\n- Model: ${data.model}\n- Provider: ${data.provider}\n- Node.js: ${data.nodeVersion}\n- Platform: ${data.platform}`;
-          setChatMessages((previous) => [
-            ...previous,
-            { type: 'assistant', content: statusMessage, timestamp: Date.now() },
-          ]);
+          addMessage({ type: 'assistant', content: statusMessage, timestamp: Date.now() });
           break;
         }
 
         case 'memory':
           if (data.error) {
-            setChatMessages((previous) => [
-              ...previous,
-              {
-                type: 'assistant',
-                content: `⚠️ ${data.message}`,
-                timestamp: Date.now(),
-              },
-            ]);
+            addMessage({
+              type: 'assistant',
+              content: `Warning: ${data.message}`,
+              timestamp: Date.now(),
+            });
           } else {
-            setChatMessages((previous) => [
-              ...previous,
-              {
-                type: 'assistant',
-                content: `📝 ${data.message}\n\nPath: \`${data.path}\``,
-                timestamp: Date.now(),
-              },
-            ]);
+            addMessage({
+              type: 'assistant',
+              content: `${data.message}\n\nPath: \`${data.path}\``,
+              timestamp: Date.now(),
+            });
             if (data.exists && onFileOpen) {
               onFileOpen(data.path);
             }
@@ -212,24 +213,18 @@ export function useChatComposerState({
 
         case 'rewind':
           if (data.error) {
-            setChatMessages((previous) => [
-              ...previous,
-              {
-                type: 'assistant',
-                content: `⚠️ ${data.message}`,
-                timestamp: Date.now(),
-              },
-            ]);
+            addMessage({
+              type: 'assistant',
+              content: `Warning: ${data.message}`,
+              timestamp: Date.now(),
+            });
           } else {
-            setChatMessages((previous) => previous.slice(0, -data.steps * 2));
-            setChatMessages((previous) => [
-              ...previous,
-              {
-                type: 'assistant',
-                content: `⏪ ${data.message}`,
-                timestamp: Date.now(),
-              },
-            ]);
+            rewindMessages(data.steps * 2);
+            addMessage({
+              type: 'assistant',
+              content: `Rewound ${data.steps} step(s). ${data.message}`,
+              timestamp: Date.now(),
+            });
           }
           break;
 
@@ -237,7 +232,7 @@ export function useChatComposerState({
           console.warn('Unknown built-in command action:', action);
       }
     },
-    [onFileOpen, onShowSettings, setChatMessages, setSessionMessages],
+    [onFileOpen, onShowSettings, addMessage, clearMessages, rewindMessages],
   );
 
   const handleCustomCommand = useCallback(async (result: CommandExecutionResult) => {
@@ -248,14 +243,11 @@ export function useChatComposerState({
         'This command contains bash commands that will be executed. Do you want to proceed?',
       );
       if (!confirmed) {
-        setChatMessages((previous) => [
-          ...previous,
-          {
-            type: 'assistant',
-            content: '❌ Command execution cancelled',
-            timestamp: Date.now(),
-          },
-        ]);
+        addMessage({
+          type: 'assistant',
+          content: 'Command execution cancelled',
+          timestamp: Date.now(),
+        });
         return;
       }
     }
@@ -270,7 +262,7 @@ export function useChatComposerState({
         handleSubmitRef.current(createFakeSubmitEvent());
       }
     }, 0);
-  }, [setChatMessages]);
+  }, [addMessage]);
 
   const executeCommand = useCallback(
     async (command: SlashCommand, rawInput?: string) => {
@@ -328,14 +320,11 @@ export function useChatComposerState({
       } catch (error) {
         const message = error instanceof Error ? error.message : 'Unknown error';
         console.error('Error executing command:', error);
-        setChatMessages((previous) => [
-          ...previous,
-          {
-            type: 'assistant',
-            content: `Error executing command: ${message}`,
-            timestamp: Date.now(),
-          },
-        ]);
+        addMessage({
+          type: 'assistant',
+          content: `Error executing command: ${message}`,
+          timestamp: Date.now(),
+        });
       }
     },
     [
@@ -349,7 +338,7 @@ export function useChatComposerState({
       input,
       provider,
       selectedProject,
-      setChatMessages,
+      addMessage,
       tokenBudget,
     ],
   );
@@ -529,18 +518,19 @@ export function useChatComposerState({
         } catch (error) {
           const message = error instanceof Error ? error.message : 'Unknown error';
           console.error('Image upload failed:', error);
-          setChatMessages((previous) => [
-            ...previous,
-            {
-              type: 'error',
-              content: `Failed to upload images: ${message}`,
-              timestamp: new Date(),
-            },
-          ]);
+          addMessage({
+            type: 'error',
+            content: `Failed to upload images: ${message}`,
+            timestamp: new Date(),
+          });
           return;
         }
       }
 
+      const effectiveSessionId =
+        currentSessionId || selectedSession?.id || sessionStorage.getItem('cursorSessionId');
+      const sessionToActivate = effectiveSessionId || `new-session-${Date.now()}`;
+
       const userMessage: ChatMessage = {
         type: 'user',
         content: currentInput,
@@ -548,7 +538,7 @@ export function useChatComposerState({
         timestamp: new Date(),
       };
 
-      setChatMessages((previous) => [...previous, userMessage]);
+      addMessage(userMessage);
       setIsLoading(true); // Processing banner starts
       setCanAbortSession(true);
       setClaudeStatus({
@@ -560,10 +550,6 @@ export function useChatComposerState({
       setIsUserScrolledUp(false);
       setTimeout(() => scrollToBottom(), 100);
 
-      const effectiveSessionId =
-        currentSessionId || selectedSession?.id || sessionStorage.getItem('cursorSessionId');
-      const sessionToActivate = effectiveSessionId || `new-session-${Date.now()}`;
-
       if (!effectiveSessionId && !selectedSession?.id) {
         if (typeof window !== 'undefined') {
           // Reset stale pending IDs from previous interrupted runs before creating a new one.
@@ -603,6 +589,7 @@ export function useChatComposerState({
 
       const toolsSettings = getToolsSettings();
       const resolvedProjectPath = selectedProject.fullPath || selectedProject.path || '';
+      const sessionSummary = getNotificationSessionSummary(selectedSession, currentInput);
 
       if (provider === 'cursor') {
         sendMessage({
@@ -616,6 +603,7 @@ export function useChatComposerState({
             resume: Boolean(effectiveSessionId),
             model: cursorModel,
             skipPermissions: toolsSettings?.skipPermissions || false,
+            sessionSummary,
             toolsSettings,
           },
         });
@@ -630,6 +618,7 @@ export function useChatComposerState({
             sessionId: effectiveSessionId,
             resume: Boolean(effectiveSessionId),
             model: codexModel,
+            sessionSummary,
             permissionMode: permissionMode === 'plan' ? 'default' : permissionMode,
           },
         });
@@ -644,6 +633,7 @@ export function useChatComposerState({
             sessionId: effectiveSessionId,
             resume: Boolean(effectiveSessionId),
             model: geminiModel,
+            sessionSummary,
             permissionMode,
             toolsSettings,
           },
@@ -660,6 +650,7 @@ export function useChatComposerState({
             toolsSettings,
             permissionMode,
             model: claudeModel,
+            sessionSummary,
             images: uploadedImages,
           },
         });
@@ -681,6 +672,7 @@ export function useChatComposerState({
       safeLocalStorage.removeItem(`draft_input_${selectedProject.name}`);
     },
     [
+      selectedSession,
       attachedImages,
       claudeModel,
       codexModel,
@@ -697,10 +689,9 @@ export function useChatComposerState({
       resetCommandMenuState,
       scrollToBottom,
       selectedProject,
-      selectedSession?.id,
       sendMessage,
       setCanAbortSession,
-      setChatMessages,
+      addMessage,
       setClaudeStatus,
       setIsLoading,
       setIsUserScrolledUp,
@@ -887,30 +878,6 @@ export function useChatComposerState({
     });
   }, [canAbortSession, currentSessionId, pendingViewSessionRef, provider, selectedSession?.id, sendMessage]);
 
-  const handleTranscript = useCallback((text: string) => {
-    if (!text.trim()) {
-      return;
-    }
-
-    setInput((previousInput) => {
-      const newInput = previousInput.trim() ? `${previousInput} ${text}` : text;
-      inputValueRef.current = newInput;
-
-      setTimeout(() => {
-        if (!textareaRef.current) {
-          return;
-        }
-
-        textareaRef.current.style.height = 'auto';
-        textareaRef.current.style.height = `${textareaRef.current.scrollHeight}px`;
-        const lineHeight = parseInt(window.getComputedStyle(textareaRef.current).lineHeight);
-        setIsTextareaExpanded(textareaRef.current.scrollHeight > lineHeight * 2);
-      }, 0);
-
-      return newInput;
-    });
-  }, []);
-
   const handleGrantToolPermission = useCallback(
     (suggestion: { entry: string; toolName: string }) => {
       if (!suggestion || provider !== 'claude') {
@@ -1003,7 +970,6 @@ export function useChatComposerState({
     syncInputOverlayScroll,
     handleClearInput,
     handleAbortSession,
-    handleTranscript,
     handlePermissionDecision,
     handleGrantToolPermission,
     handleInputFocusChange,

src/components/chat/hooks/useChatMessages.ts

@@ -0,0 +1,183 @@
+/**
+ * Message normalization utilities.
+ * Converts NormalizedMessage[] from the session store into ChatMessage[] for the UI.
+ */
+
+import type { NormalizedMessage } from '../../../stores/useSessionStore';
+import type { ChatMessage, SubagentChildTool } from '../types/types';
+import { decodeHtmlEntities, unescapeWithMathProtection, formatUsageLimitText } from '../utils/chatFormatting';
+
+/**
+ * Convert NormalizedMessage[] from the session store into ChatMessage[]
+ * that the existing UI components expect.
+ *
+ * Internal/system content (e.g. <system-reminder>, <command-name>) is already
+ * filtered server-side by the Claude adapter (server/providers/utils.js).
+ */
+export function normalizedToChatMessages(messages: NormalizedMessage[]): ChatMessage[] {
+  const converted: ChatMessage[] = [];
+
+  // First pass: collect tool results for attachment
+  const toolResultMap = new Map<string, NormalizedMessage>();
+  for (const msg of messages) {
+    if (msg.kind === 'tool_result' && msg.toolId) {
+      toolResultMap.set(msg.toolId, msg);
+    }
+  }
+
+  for (const msg of messages) {
+    switch (msg.kind) {
+      case 'text': {
+        const content = msg.content || '';
+        if (!content.trim()) continue;
+
+        if (msg.role === 'user') {
+          // Parse task notifications
+          const taskNotifRegex = /<task-notification>\s*<task-id>[^<]*<\/task-id>\s*<output-file>[^<]*<\/output-file>\s*<status>([^<]*)<\/status>\s*<summary>([^<]*)<\/summary>\s*<\/task-notification>/g;
+          const taskNotifMatch = taskNotifRegex.exec(content);
+          if (taskNotifMatch) {
+            converted.push({
+              type: 'assistant',
+              content: taskNotifMatch[2]?.trim() || 'Background task finished',
+              timestamp: msg.timestamp,
+              isTaskNotification: true,
+              taskStatus: taskNotifMatch[1]?.trim() || 'completed',
+            });
+          } else {
+            converted.push({
+              type: 'user',
+              content: unescapeWithMathProtection(decodeHtmlEntities(content)),
+              timestamp: msg.timestamp,
+            });
+          }
+        } else {
+          let text = decodeHtmlEntities(content);
+          text = unescapeWithMathProtection(text);
+          text = formatUsageLimitText(text);
+          converted.push({
+            type: 'assistant',
+            content: text,
+            timestamp: msg.timestamp,
+          });
+        }
+        break;
+      }
+
+      case 'tool_use': {
+        const tr = msg.toolResult || (msg.toolId ? toolResultMap.get(msg.toolId) : null);
+        const isSubagentContainer = msg.toolName === 'Task';
+
+        // Build child tools from subagentTools
+        const childTools: SubagentChildTool[] = [];
+        if (isSubagentContainer && msg.subagentTools && Array.isArray(msg.subagentTools)) {
+          for (const tool of msg.subagentTools as any[]) {
+            childTools.push({
+              toolId: tool.toolId,
+              toolName: tool.toolName,
+              toolInput: tool.toolInput,
+              toolResult: tool.toolResult || null,
+              timestamp: new Date(tool.timestamp || Date.now()),
+            });
+          }
+        }
+
+        const toolResult = tr
+          ? {
+              content: typeof tr.content === 'string' ? tr.content : JSON.stringify(tr.content),
+              isError: Boolean(tr.isError),
+              toolUseResult: (tr as any).toolUseResult,
+            }
+          : null;
+
+        converted.push({
+          type: 'assistant',
+          content: '',
+          timestamp: msg.timestamp,
+          isToolUse: true,
+          toolName: msg.toolName,
+          toolInput: typeof msg.toolInput === 'string' ? msg.toolInput : JSON.stringify(msg.toolInput ?? '', null, 2),
+          toolId: msg.toolId,
+          toolResult,
+          isSubagentContainer,
+          subagentState: isSubagentContainer
+            ? {
+                childTools,
+                currentToolIndex: childTools.length > 0 ? childTools.length - 1 : -1,
+                isComplete: Boolean(toolResult),
+              }
+            : undefined,
+        });
+        break;
+      }
+
+      case 'thinking':
+        if (msg.content?.trim()) {
+          converted.push({
+            type: 'assistant',
+            content: unescapeWithMathProtection(msg.content),
+            timestamp: msg.timestamp,
+            isThinking: true,
+          });
+        }
+        break;
+
+      case 'error':
+        converted.push({
+          type: 'error',
+          content: msg.content || 'Unknown error',
+          timestamp: msg.timestamp,
+        });
+        break;
+
+      case 'interactive_prompt':
+        converted.push({
+          type: 'assistant',
+          content: msg.content || '',
+          timestamp: msg.timestamp,
+          isInteractivePrompt: true,
+        });
+        break;
+
+      case 'task_notification':
+        converted.push({
+          type: 'assistant',
+          content: msg.summary || 'Background task update',
+          timestamp: msg.timestamp,
+          isTaskNotification: true,
+          taskStatus: msg.status || 'completed',
+        });
+        break;
+
+      case 'stream_delta':
+        if (msg.content) {
+          converted.push({
+            type: 'assistant',
+            content: msg.content,
+            timestamp: msg.timestamp,
+            isStreaming: true,
+          });
+        }
+        break;
+
+      // stream_end, complete, status, permission_*, session_created
+      // are control events — not rendered as messages
+      case 'stream_end':
+      case 'complete':
+      case 'status':
+      case 'permission_request':
+      case 'permission_cancelled':
+      case 'session_created':
+        // Skip — these are handled by useChatRealtimeHandlers
+        break;
+
+      // tool_result is handled via attachment to tool_use above
+      case 'tool_result':
+        break;
+
+      default:
+        break;
+    }
+  }
+
+  return converted;
+}

src/components/chat/hooks/useChatProviderState.ts

@@ -2,7 +2,7 @@ import { useCallback, useEffect, useRef, useState } from 'react';
 import { authenticatedFetch } from '../../../utils/api';
 import { CLAUDE_MODELS, CODEX_MODELS, CURSOR_MODELS, GEMINI_MODELS } from '../../../../shared/modelConstants';
 import type { PendingPermissionRequest, PermissionMode } from '../types/types';
-import type { ProjectSession, SessionProvider } from '../../../types/app';
+import type { ProjectSession, LLMProvider } from '../../../types/app';
 
 interface UseChatProviderStateArgs {
   selectedSession: ProjectSession | null;
@@ -11,8 +11,8 @@ interface UseChatProviderStateArgs {
 export function useChatProviderState({ selectedSession }: UseChatProviderStateArgs) {
   const [permissionMode, setPermissionMode] = useState<PermissionMode>('default');
   const [pendingPermissionRequests, setPendingPermissionRequests] = useState<PendingPermissionRequest[]>([]);
-  const [provider, setProvider] = useState<SessionProvider>(() => {
-    return (localStorage.getItem('selected-provider') as SessionProvider) || 'claude';
+  const [provider, setProvider] = useState<LLMProvider>(() => {
+    return (localStorage.getItem('selected-provider') as LLMProvider) || 'claude';
   });
   const [cursorModel, setCursorModel] = useState<string>(() => {
     return localStorage.getItem('cursor-model') || CURSOR_MODELS.DEFAULT;