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.

.github/workflows/release.yml

@@ -20,14 +20,14 @@ jobs:
       contents: write
       id-token: write
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
         with:
           fetch-depth: 0
           token: ${{ secrets.RELEASE_PAT }}
 
-      - uses: actions/setup-node@v4
+      - uses: actions/setup-node@v6
         with:
-          node-version: 20
+          node-version: 22
           registry-url: https://registry.npmjs.org
 
       - name: git config

.gitignore

@@ -8,6 +8,7 @@ lerna-debug.log*
 
 # Build outputs
 dist/
+dist-server/
 dist-ssr/
 build/
 out/
@@ -138,4 +139,4 @@ tasks/
 !src/i18n/locales/de/tasks.json
 
 # Git worktrees
-.worktrees/
+.worktrees/

CHANGELOG.md

@@ -3,6 +3,47 @@
 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

README.de.md

@@ -76,6 +76,8 @@ Der schnellste Einstieg – keine lokale Einrichtung erforderlich. Erhalte eine
 
 ### Self-Hosted (Open Source)
 
+#### npm
+
 CloudCLI UI sofort mit **npx** ausprobieren (erfordert **Node.js** v22+):
 
 ```bash
@@ -93,6 +95,15 @@ cloudcli
 
 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/).
 
 ---
 

README.ja.md

@@ -72,6 +72,8 @@
 
 ### セルフホスト（オープンソース）
 
+#### npm
+
 **npx** で今すぐ CloudCLI UI を試せます（**Node.js** v22+ が必要）：
 
 ```bash
@@ -89,6 +91,15 @@ cloudcli
 
 より詳細な設定オプション、PM2、リモートサーバー設定などについては **[ドキュメントはこちら →](https://cloudcli.ai/docs)** を参照してください。
 
+#### 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 に対応。詳細は[サンドボックスのドキュメント](docker/)をご覧ください。
 
 ---
 

README.ko.md

@@ -72,6 +72,8 @@
 
 ### 셀프 호스트 (오픈 소스)
 
+#### npm
+
 **npx**로 즉시 CloudCLI UI를 실행하세요 (Node.js v22+ 필요):
 
 ```bash
@@ -87,7 +89,17 @@ cloudcli
 
 `http://localhost:3001`을 열면 기존 세션이 자동으로 발견됩니다.
 
-자세한 구성 옵션, PM2, 원격 서버 설정 등은 **[문서 →](https://cloudcli.ai/docs)**를 참고하세요
+자세한 구성 옵션, PM2, 원격 서버 설정 등은 **[문서 →](https://cloudcli.ai/docs)**를 참고하세요.
+
+#### 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를 지원합니다. 자세한 내용은 [샌드박스 문서](docker/)를 참고하세요.
 
 ---
 

README.md

@@ -76,6 +76,8 @@ 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+):
 
 ```
@@ -91,33 +93,41 @@ 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 @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 |
+| | 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.
 
 ---
 

README.ru.md

@@ -76,6 +76,8 @@
 
 ### Self-Hosted (Open source)
 
+#### npm
+
 Попробовать CloudCLI UI можно сразу через **npx** (требуется **Node.js** v22+):
 
 ```bash
@@ -91,8 +93,17 @@ cloudcli
 
 Откройте `http://localhost:3001` — все ваши существующие сессии будут обнаружены автоматически.
 
-Посетите **[документацию →](https://cloudcli.ai/docs)**, чтобы узнать про дополнительные варианты конфигурации, PM2, настройку удалённого сервера и многое другое
+Посетите **[документацию →](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/).
 
 ---
 

README.zh-CN.md

@@ -72,6 +72,8 @@
 
 ### 自托管（开源）
 
+#### npm
+
 启动 CloudCLI UI，只需一行 `npx`（需要 Node.js v22+）：
 
 ```bash
@@ -87,7 +89,17 @@ cloudcli
 
 打开 `http://localhost:3001`，系统会自动发现所有现有会话。
 
-更多配置选项、PM2、远程服务器设置等，请参阅 **[文档 →](https://cloudcli.ai/docs)**
+更多配置选项、PM2、远程服务器设置等，请参阅 **[文档 →](https://cloudcli.ai/docs)**。
+
+#### 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。详情请参阅 [沙箱文档](docker/)。
 
 ---
 

docker/README.md

@@ -1,89 +1,160 @@
-# CloudCLI — Docker Sandbox Templates
+<!-- Docker Hub short description (100 chars max): -->
+<!-- Sandbox templates for running AI coding agents with a web & mobile IDE (Claude Code, Codex, Gemini) -->
 
-Run AI coding agents with a full web IDE inside [Docker Sandboxes](https://docs.docker.com/ai/sandboxes/).
+# Sandboxed coding agents with a web & mobile IDE (CloudCLI)
 
-Instead of a terminal-only experience, get a browser-based interface with chat, file explorer, git panel, shell, and MCP configuration — all running safely inside an isolated sandbox.
+[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.
 
-## Available Templates
+## Get started
 
-| Template | Base Image | Agent |
-|----------|-----------|-------|
-| `cloudcli-ai/sandbox:claude-code` | `docker/sandbox-templates:claude-code` | Claude Code |
-| `cloudcli-ai/sandbox:codex` | `docker/sandbox-templates:codex` | OpenAI Codex |
-| `cloudcli-ai/sandbox:gemini` | `docker/sandbox-templates:gemini` | Gemini CLI |
+### 1. Install the sbx CLI
 
-## Quick Start
+Docker Sandboxes run agents in isolated microVMs. Install the `sbx` CLI:
 
-### 1. Start a sandbox with the template
+- **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 run --template docker.io/cloudcli-ai/sandbox:claude-code claude ~/my-project
+sbx login
+sbx secret set -g anthropic
 ```
 
-### 2. Forward the UI port
+### 3. Launch Claude Code
 
 ```bash
-sbx ports <sandbox-name> --publish 3001:3001
+npx @cloudcli-ai/cloudcli@latest sandbox ~/my-project
 ```
 
-### 3. Open the browser
+Open **http://localhost:3001**. Set a password on first visit. Start building.
 
-```
-http://localhost:3001
+### 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
 ```
 
-On first visit you'll set a password — this protects the UI if the port is ever exposed beyond localhost.
+### Available templates
 
-## What You Get
+| 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` |
 
-- **Chat** — Rich conversation UI with markdown rendering, code blocks, and message history
-- **Files** — Visual file tree with syntax-highlighted editor
-- **Git** — Diff viewer, staging, branch switching, and commit — all visual
+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 through the UI
+- **MCP** — Configure Model Context Protocol servers visually
 - **Mobile** — Works on tablet and phone browsers
 
-## Building Locally
-
-All Dockerfiles share scripts from `shared/`. Build with the `docker/` directory as context:
-
-```bash
-# Claude Code variant
-docker build -f docker/claude-code/Dockerfile -t cloudcli-sandbox:claude-code docker/
-
-# Codex variant
-docker build -f docker/codex/Dockerfile -t cloudcli-sandbox:codex docker/
-
-# Gemini variant
-docker build -f docker/gemini/Dockerfile -t cloudcli-sandbox:gemini docker/
-```
-
-## How It Works
-
-Each template extends Docker's official sandbox base image and adds:
-
-1. **Node.js 22** — Runtime for CloudCLI
-2. **CloudCLI** — Installed globally via `npm install -g @cloudcli-ai/cloudcli`
-3. **Auto-start** — The UI server starts in the background when the sandbox shell opens (port 3001)
-
-The agent (Claude Code, Codex, or Gemini) comes from the base image. CloudCLI connects to it and provides the web interface on top.
+Your project directory is mounted bidirectionally — edits propagate in real time, both ways.
 
 ## Configuration
 
-| Environment Variable | Default | Description |
-|---------------------|---------|-------------|
-| `SERVER_PORT` | `3001` | Port for the web UI |
-| `HOST` | `0.0.0.0` | Bind address |
-| `DATABASE_PATH` | `~/.cloudcli/auth.db` | SQLite database location |
-
-## Network Policies
-
-If your sandbox uses restricted network policies, allow the UI port:
+Set variables at creation time with `--env`:
 
 ```bash
-sbx policy allow network "localhost:3001"
+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
 
-These templates are free and open-source under the same license as CloudCLI (AGPL-3.0-or-later).
+AGPL-3.0-or-later

docker/claude-code/Dockerfile

@@ -5,7 +5,7 @@ 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
+RUN npm install -g @cloudcli-ai/cloudcli && cloudcli --version
 
-COPY shared/start-cloudcli.sh /home/agent/.cloudcli-start.sh
+COPY --chown=agent:agent shared/start-cloudcli.sh /home/agent/.cloudcli-start.sh
 RUN echo '. ~/.cloudcli-start.sh' >> /home/agent/.bashrc

docker/codex/Dockerfile

@@ -5,7 +5,7 @@ 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
+RUN npm install -g @cloudcli-ai/cloudcli && cloudcli --version
 
-COPY shared/start-cloudcli.sh /home/agent/.cloudcli-start.sh
+COPY --chown=agent:agent shared/start-cloudcli.sh /home/agent/.cloudcli-start.sh
 RUN echo '. ~/.cloudcli-start.sh' >> /home/agent/.bashrc

docker/gemini/Dockerfile

@@ -5,7 +5,7 @@ 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
+RUN npm install -g @cloudcli-ai/cloudcli && cloudcli --version
 
-COPY shared/start-cloudcli.sh /home/agent/.cloudcli-start.sh
+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

@@ -1,13 +1,10 @@
 #!/bin/bash
 set -e
 
-# Install Node.js 22 LTS
-curl -fsSL https://deb.nodesource.com/setup_22.x | bash -
-
-# Install Node.js + build tools needed for native modules (node-pty, better-sqlite3, bcrypt)
-# Node.js + build tools for native modules + common dev tools
-apt-get install -y --no-install-recommends \
-  nodejs build-essential python3 python3-setuptools \
+# 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

docker/shared/start-cloudcli.sh

@@ -4,19 +4,14 @@
 # This script is sourced from ~/.bashrc on sandbox shell open.
 
 if ! pgrep -f "server/index.js" > /dev/null 2>&1; then
-  # Start the pre-installed version immediately
   nohup cloudcli start --port 3001 > /tmp/cloudcli-ui.log 2>&1 &
   disown
 
-  # Check for updates in the background (non-blocking)
-  nohup npm update -g @cloudcli-ai/cloudcli > /tmp/cloudcli-update.log 2>&1 &
-  disown
-
   echo ""
   echo "  CloudCLI is starting on port 3001..."
   echo ""
-  echo "  To access the web UI, forward the port:"
-  echo "    sbx ports \$(hostname) --publish 3001:3001"
+  echo "  Forward the port from another terminal:"
+  echo "    sbx ports <sandbox-name> --publish 3001:3001"
   echo ""
   echo "  Then open: http://localhost:3001"
   echo ""

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,16 +1,17 @@
 {
   "name": "@cloudcli-ai/cloudcli",
-  "version": "1.28.0",
+  "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": {
-    "cloudcli": "server/cli.js"
+    "cloudcli": "dist-server/server/cli.js"
   },
   "files": [
     "server/",
     "shared/",
     "dist/",
+    "dist-server/",
     "scripts/",
     "README.md"
   ],
@@ -23,19 +24,25 @@
     "url": "https://github.com/siteboon/claudecodeui/issues"
   },
   "scripts": {
-    "dev": "concurrently --kill-others \"npm run server\" \"npm run client\"",
-    "server": "node server/index.js",
+    "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": "vite build",
+    "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",
@@ -121,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",
@@ -129,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",
@@ -143,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

@@ -585,7 +585,7 @@
                             <p>Server-sent events (SSE) format with real-time updates. Content-Type: <code>text/event-stream</code></p>
 
                             <h4>Response (Non-Streaming)</h4>
-                            <p>JSON object containing session details and assistant messages only (filtered). Content-Type: <code>application/json</code></p>
+                            <p>JSON object containing session details, assistant messages only (filtered), and token usage summary. Content-Type: <code>application/json</code></p>
 
                             <h4>Error Response</h4>
                             <p>Returns error details with appropriate HTTP status code.</p>
@@ -674,10 +674,21 @@ data: {"type":"done"}</code></pre>
             "type": "text",
             "text": "I've completed the task..."
           }
-        ]
+        ],
+        "usage": {
+          "input_tokens": 150,
+          "output_tokens": 50
+        }
       }
     }
   ],
+  "tokens": {
+    "inputTokens": 150,
+    "outputTokens": 50,
+    "cacheReadTokens": 0,
+    "cacheCreationTokens": 0,
+    "totalTokens": 200
+  },
   "projectPath": "/path/to/project",
   "branch": {
     "name": "fix-authentication-bug-abc123",

redirect-package/bin.js

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

server/claude-sdk.js

@@ -24,8 +24,8 @@ import {
   notifyRunStopped,
   notifyUserIfEnabled
 } from './services/notification-orchestrator.js';
-import { claudeAdapter } from './providers/claude/adapter.js';
-import { createNormalizedMessage } from './providers/types.js';
+import { sessionsService } from './modules/providers/services/sessions.service.js';
+import { createNormalizedMessage } from './shared/utils.js';
 
 const activeSessions = new Map();
 const pendingToolApprovals = new Map();
@@ -274,6 +274,46 @@ function transformMessage(sdkMessage) {
   return sdkMessage;
 }
 
+/**
+ * Extracts token usage from SDK result messages
+ * @param {Object} resultMessage - SDK result message
+ * @returns {Object|null} Token budget object or null
+ */
+function extractTokenBudget(resultMessage) {
+  if (resultMessage.type !== 'result' || !resultMessage.modelUsage) {
+    return null;
+  }
+
+  // Get the first model's usage data
+  const modelKey = Object.keys(resultMessage.modelUsage)[0];
+  const modelData = resultMessage.modelUsage[modelKey];
+
+  if (!modelData) {
+    return null;
+  }
+
+  // Use cumulative tokens if available (tracks total for the session)
+  // Otherwise fall back to per-request tokens
+  const inputTokens = modelData.cumulativeInputTokens || modelData.inputTokens || 0;
+  const outputTokens = modelData.cumulativeOutputTokens || modelData.outputTokens || 0;
+  const cacheReadTokens = modelData.cumulativeCacheReadInputTokens || modelData.cacheReadInputTokens || 0;
+  const cacheCreationTokens = modelData.cumulativeCacheCreationInputTokens || modelData.cacheCreationInputTokens || 0;
+
+  // Total used = input + output + cache tokens
+  const totalUsed = inputTokens + outputTokens + cacheReadTokens + cacheCreationTokens;
+
+  // Use configured context window budget from environment (default 160000)
+  // This is the user's budget limit, not the model's context window
+  const contextWindow = parseInt(process.env.CONTEXT_WINDOW) || 160000;
+
+  // Token calc logged via token-budget WS event
+
+  return {
+    used: totalUsed,
+    total: contextWindow
+  };
+}
+
 /**
  * Handles image processing for SDK queries
  * Saves base64 images to temporary files and returns modified prompt with file paths
@@ -609,7 +649,7 @@ async function queryClaudeSDK(command, options = {}, ws) {
       const sid = capturedSessionId || sessionId || null;
 
       // Use adapter to normalize SDK events into NormalizedMessage[]
-      const normalized = claudeAdapter.normalizeMessage(transformedMessage, sid);
+      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) {
@@ -617,6 +657,18 @@ async function queryClaudeSDK(command, options = {}, ws) {
         }
         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) {
+          // Model info available in result message
+        }
+        const tokenBudgetData = extractTokenBudget(message);
+        if (tokenBudgetData) {
+          ws.send(createNormalizedMessage({ kind: 'status', text: 'token_budget', tokenBudget: tokenBudgetData, sessionId: capturedSessionId || sessionId || null, provider: 'claude' }));
+        }
+      }
     }
 
     // Clean up session on completion

server/cli.js

@@ -7,6 +7,7 @@
  * 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,12 +79,12 @@ 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
@@ -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)}`);
@@ -150,6 +155,7 @@ Usage:
 
 Commands:
   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,8 +170,7 @@ 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:
@@ -244,6 +249,353 @@ async function updatePackage() {
     }
 }
 
+// ── 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
@@ -274,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;
+            }
         }
     }
 
@@ -283,7 +639,7 @@ 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.serverPort) {
@@ -299,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,8 +1,8 @@
 import { spawn } from 'child_process';
 import crossSpawn from 'cross-spawn';
 import { notifyRunFailed, notifyRunStopped } from './services/notification-orchestrator.js';
-import { cursorAdapter } from './providers/cursor/adapter.js';
-import { createNormalizedMessage } from './providers/types.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;
@@ -189,7 +189,7 @@ async function spawnCursor(command, options = {}, ws) {
             case 'assistant':
               // Accumulate assistant message chunks
               if (response.message && response.message.content && response.message.content.length > 0) {
-                const normalized = cursorAdapter.normalizeMessage(response, capturedSessionId || sessionId || null);
+                const normalized = sessionsService.normalizeMessage('cursor', response, capturedSessionId || sessionId || null);
                 for (const msg of normalized) ws.send(msg);
               }
               break;
@@ -219,7 +219,7 @@ async function spawnCursor(command, options = {}, ws) {
           }
 
           // If not JSON, send as stream delta via adapter
-          const normalized = cursorAdapter.normalizeMessage(line, capturedSessionId || sessionId || null);
+          const normalized = sessionsService.normalizeMessage('cursor', line, capturedSessionId || sessionId || null);
           for (const msg of normalized) ws.send(msg);
         }
       };

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,53 +105,12 @@ const runMigrations = () => {
       db.exec('ALTER TABLE users ADD COLUMN has_completed_onboarding BOOLEAN DEFAULT 0');
     }
 
-    db.exec(`
-      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
-      )
-    `);
-
-    db.exec(`
-      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
-      )
-    `);
-
-    db.exec(`
-      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
-      )
-    `);
-    // 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) {
@@ -158,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) {

server/database/init.sql

@@ -1,99 +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);
-
--- User notification preferences (backend-owned, provider-agnostic)
-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
-);
-
--- VAPID key pair for Web Push notifications
-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
-);
-
--- Browser push subscriptions
-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
-);
-
--- 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

@@ -9,7 +9,7 @@ import os from 'os';
 import sessionManager from './sessionManager.js';
 import GeminiResponseHandler from './gemini-response-handler.js';
 import { notifyRunFailed, notifyRunStopped } from './services/notification-orchestrator.js';
-import { createNormalizedMessage } from './providers/types.js';
+import { createNormalizedMessage } from './shared/utils.js';
 
 let activeGeminiProcesses = new Map(); // Track active processes by session ID
 

server/gemini-response-handler.js

@@ -1,5 +1,5 @@
 // Gemini Response Handler - JSON Stream processing
-import { geminiAdapter } from './providers/gemini/adapter.js';
+import { sessionsService } from './modules/providers/services/sessions.service.js';
 
 class GeminiResponseHandler {
   constructor(ws, options = {}) {
@@ -56,7 +56,7 @@ class GeminiResponseHandler {
     }
 
     // Normalize via adapter and send all resulting messages
-    const normalized = geminiAdapter.normalizeMessage(event, sid);
+    const normalized = sessionsService.normalizeMessage('gemini', event, sid);
     for (const msg of normalized) {
       this.ws.send(msg);
     }

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 = {
@@ -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, 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,13 +61,12 @@ 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 messagesRoutes from './routes/messages.js';
-import { createNormalizedMessage } from './providers/types.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';
@@ -365,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);
 
@@ -383,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);
 
@@ -401,15 +395,18 @@ 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
@@ -431,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 @cloudcli-ai/cloudcli@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
         });
 
@@ -578,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() : '';
@@ -1447,7 +1434,7 @@ wss.on('connection', (ws, request) => {
 /**
  * WebSocket Writer - Wrapper for WebSocket to match SSEStreamWriter interface
  *
- * Provider files use `createNormalizedMessage()` from `providers/types.js` and
+ * Provider files use `createNormalizedMessage()` from `shared/utils.js` and
  * adapter `normalizeMessage()` to produce unified NormalizedMessage events.
  * The writer simply serialises and sends.
  */
@@ -1984,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 {
@@ -2218,6 +2056,194 @@ app.post('/api/projects/:projectName/upload-images', authenticateToken, async (r
     }
 });
 
+// Get token usage for a specific session
+app.get('/api/projects/:projectName/sessions/:sessionId/token-usage', authenticateToken, async (req, res) => {
+    try {
+        const { projectName, sessionId } = req.params;
+        const { provider = 'claude' } = req.query;
+        const homeDir = os.homedir();
+
+        // Allow only safe characters in sessionId
+        const safeSessionId = String(sessionId).replace(/[^a-zA-Z0-9._-]/g, '');
+        if (!safeSessionId || safeSessionId !== String(sessionId)) {
+            return res.status(400).json({ error: 'Invalid sessionId' });
+        }
+
+        // Handle Cursor sessions - they use SQLite and don't have token usage info
+        if (provider === 'cursor') {
+            return res.json({
+                used: 0,
+                total: 0,
+                breakdown: { input: 0, cacheCreation: 0, cacheRead: 0 },
+                unsupported: true,
+                message: 'Token usage tracking not available for Cursor sessions'
+            });
+        }
+
+        // Handle Gemini sessions - they are raw logs in our current setup
+        if (provider === 'gemini') {
+            return res.json({
+                used: 0,
+                total: 0,
+                breakdown: { input: 0, cacheCreation: 0, cacheRead: 0 },
+                unsupported: true,
+                message: 'Token usage tracking not available for Gemini sessions'
+            });
+        }
+
+        // Handle Codex sessions
+        if (provider === 'codex') {
+            const codexSessionsDir = path.join(homeDir, '.codex', 'sessions');
+
+            // Find the session file by searching for the session ID
+            const findSessionFile = async (dir) => {
+                try {
+                    const entries = await fsPromises.readdir(dir, { withFileTypes: true });
+                    for (const entry of entries) {
+                        const fullPath = path.join(dir, entry.name);
+                        if (entry.isDirectory()) {
+                            const found = await findSessionFile(fullPath);
+                            if (found) return found;
+                        } else if (entry.name.includes(safeSessionId) && entry.name.endsWith('.jsonl')) {
+                            return fullPath;
+                        }
+                    }
+                } catch (error) {
+                    // Skip directories we can't read
+                }
+                return null;
+            };
+
+            const sessionFilePath = await findSessionFile(codexSessionsDir);
+
+            if (!sessionFilePath) {
+                return res.status(404).json({ error: 'Codex session file not found', sessionId: safeSessionId });
+            }
+
+            // Read and parse the Codex JSONL file
+            let fileContent;
+            try {
+                fileContent = await fsPromises.readFile(sessionFilePath, 'utf8');
+            } catch (error) {
+                if (error.code === 'ENOENT') {
+                    return res.status(404).json({ error: 'Session file not found', path: sessionFilePath });
+                }
+                throw error;
+            }
+            const lines = fileContent.trim().split('\n');
+            let totalTokens = 0;
+            let contextWindow = 200000; // Default for Codex/OpenAI
+
+            // Find the latest token_count event with info (scan from end)
+            for (let i = lines.length - 1; i >= 0; i--) {
+                try {
+                    const entry = JSON.parse(lines[i]);
+
+                    // Codex stores token info in event_msg with type: "token_count"
+                    if (entry.type === 'event_msg' && entry.payload?.type === 'token_count' && entry.payload?.info) {
+                        const tokenInfo = entry.payload.info;
+                        if (tokenInfo.total_token_usage) {
+                            totalTokens = tokenInfo.total_token_usage.total_tokens || 0;
+                        }
+                        if (tokenInfo.model_context_window) {
+                            contextWindow = tokenInfo.model_context_window;
+                        }
+                        break; // Stop after finding the latest token count
+                    }
+                } catch (parseError) {
+                    // Skip lines that can't be parsed
+                    continue;
+                }
+            }
+
+            return res.json({
+                used: totalTokens,
+                total: contextWindow
+            });
+        }
+
+        // Handle Claude sessions (default)
+        // Extract actual project path
+        let projectPath;
+        try {
+            projectPath = await extractProjectDirectory(projectName);
+        } catch (error) {
+            console.error('Error extracting project directory:', error);
+            return res.status(500).json({ error: 'Failed to determine project path' });
+        }
+
+        // Construct the JSONL file path
+        // Claude stores session files in ~/.claude/projects/[encoded-project-path]/[session-id].jsonl
+        // The encoding replaces any non-alphanumeric character (except -) with -
+        const encodedPath = projectPath.replace(/[^a-zA-Z0-9-]/g, '-');
+        const projectDir = path.join(homeDir, '.claude', 'projects', encodedPath);
+
+        const jsonlPath = path.join(projectDir, `${safeSessionId}.jsonl`);
+
+        // Constrain to projectDir
+        const rel = path.relative(path.resolve(projectDir), path.resolve(jsonlPath));
+        if (rel.startsWith('..') || path.isAbsolute(rel)) {
+            return res.status(400).json({ error: 'Invalid path' });
+        }
+
+        // Read and parse the JSONL file
+        let fileContent;
+        try {
+            fileContent = await fsPromises.readFile(jsonlPath, 'utf8');
+        } catch (error) {
+            if (error.code === 'ENOENT') {
+                return res.status(404).json({ error: 'Session file not found', path: jsonlPath });
+            }
+            throw error; // Re-throw other errors to be caught by outer try-catch
+        }
+        const lines = fileContent.trim().split('\n');
+
+        const parsedContextWindow = parseInt(process.env.CONTEXT_WINDOW, 10);
+        const contextWindow = Number.isFinite(parsedContextWindow) ? parsedContextWindow : 160000;
+        let inputTokens = 0;
+        let cacheCreationTokens = 0;
+        let cacheReadTokens = 0;
+
+        // Find the latest assistant message with usage data (scan from end)
+        for (let i = lines.length - 1; i >= 0; i--) {
+            try {
+                const entry = JSON.parse(lines[i]);
+
+                // Only count assistant messages which have usage data
+                if (entry.type === 'assistant' && entry.message?.usage) {
+                    const usage = entry.message.usage;
+
+                    // Use token counts from latest assistant message only
+                    inputTokens = usage.input_tokens || 0;
+                    cacheCreationTokens = usage.cache_creation_input_tokens || 0;
+                    cacheReadTokens = usage.cache_read_input_tokens || 0;
+
+                    break; // Stop after finding the latest assistant message
+                }
+            } catch (parseError) {
+                // Skip lines that can't be parsed
+                continue;
+            }
+        }
+
+        // Calculate total context usage (excluding output_tokens, as per ccusage)
+        const totalUsed = inputTokens + cacheCreationTokens + cacheReadTokens;
+
+        res.json({
+            used: totalUsed,
+            total: contextWindow,
+            breakdown: {
+                input: inputTokens,
+                cacheCreation: cacheCreationTokens,
+                cacheRead: cacheReadTokens
+            }
+        });
+    } catch (error) {
+        console.error('Error reading session token usage:', error);
+        res.status(500).json({ error: 'Failed to read session token usage' });
+    }
+});
+
 // Serve React app for all other routes (excluding static files)
 app.get('*', (req, res) => {
     // Skip requests for static assets (files with extensions)
@@ -2227,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)) {
@@ -2243,6 +2269,30 @@ app.get('*', (req, res) => {
     }
 });
 
+// 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' : '-';
@@ -2342,7 +2392,7 @@ async function startServer() {
         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
@@ -2356,7 +2406,7 @@ async function startServer() {
         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 = path.join(__dirname, '..');
+            const appInstallPath = APP_ROOT;
 
             console.log('');
             console.log(c.dim('═'.repeat(63)));

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/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

@@ -15,8 +15,8 @@
 
 import { Codex } from '@openai/codex-sdk';
 import { notifyRunFailed, notifyRunStopped } from './services/notification-orchestrator.js';
-import { codexAdapter } from './providers/codex/adapter.js';
-import { createNormalizedMessage } from './providers/types.js';
+import { sessionsService } from './modules/providers/services/sessions.service.js';
+import { createNormalizedMessage } from './shared/utils.js';
 
 // Track active sessions
 const activeCodexSessions = new Map();
@@ -129,7 +129,8 @@ function transformCodexEvent(event) {
 
     case 'turn.completed':
       return {
-        type: 'turn_complete'
+        type: 'turn_complete',
+        usage: event.usage
       };
 
     case 'turn.failed':
@@ -263,7 +264,7 @@ export async function queryCodex(command, options = {}, ws) {
       const transformed = transformCodexEvent(event);
 
       // Normalize the transformed event into NormalizedMessage(s) via adapter
-      const normalizedMsgs = codexAdapter.normalizeMessage(transformed, currentSessionId);
+      const normalizedMsgs = sessionsService.normalizeMessage('codex', transformed, currentSessionId);
       for (const msg of normalizedMsgs) {
         sendMessage(ws, msg);
       }
@@ -278,6 +279,12 @@ export async function queryCodex(command, options = {}, ws) {
           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, createNormalizedMessage({ kind: 'status', text: 'token_budget', tokenBudget: { used: totalTokens, total: 200000 }, sessionId: currentSessionId, provider: 'codex' }));
+      }
     }
 
     // Send completion event

server/projects.js

@@ -1618,6 +1618,7 @@ async function getCodexSessionMessages(sessionId, limit = null, offset = 0) {
     }
 
     const messages = [];
+    let tokenUsage = null;
     const fileStream = fsSync.createReadStream(sessionFilePath);
     const rl = readline.createInterface({
       input: fileStream,
@@ -1646,6 +1647,17 @@ async function getCodexSessionMessages(sessionId, limit = null, offset = 0) {
         try {
           const entry = JSON.parse(line);
 
+          // Extract token usage from token_count events (keep latest)
+          if (entry.type === 'event_msg' && entry.payload?.type === 'token_count' && entry.payload?.info) {
+            const info = entry.payload.info;
+            if (info.total_token_usage) {
+              tokenUsage = {
+                used: info.total_token_usage.total_tokens || 0,
+                total: info.model_context_window || 200000
+              };
+            }
+          }
+          
           // Use event_msg.user_message for user-visible inputs.
           if (entry.type === 'event_msg' && isVisibleCodexUserMessage(entry.payload)) {
             messages.push({
@@ -1808,10 +1820,11 @@ async function getCodexSessionMessages(sessionId, limit = null, offset = 0) {
         hasMore,
         offset,
         limit,
+        tokenUsage
       };
     }
 
-    return { messages };
+    return { messages, tokenUsage };
 
   } catch (error) {
     console.error(`Error reading Codex session messages for ${sessionId}:`, error);

server/providers/claude/adapter.js

@@ -1,278 +0,0 @@
-/**
- * Claude provider adapter.
- *
- * Normalizes Claude SDK session history into NormalizedMessage format.
- * @module adapters/claude
- */
-
-import { getSessionMessages } from '../../projects.js';
-import { createNormalizedMessage, generateMessageId } from '../types.js';
-import { isInternalContent } from '../utils.js';
-
-const PROVIDER = 'claude';
-
-/**
- * Normalize a raw JSONL message or realtime SDK event into NormalizedMessage(s).
- * Handles both history entries (JSONL `{ message: { role, content } }`) and
- * realtime streaming events (`content_block_delta`, `content_block_stop`, etc.).
- * @param {object} raw - A single entry from JSONL or a live SDK event
- * @param {string} sessionId
- * @returns {import('../types.js').NormalizedMessage[]}
- */
-export function normalizeMessage(raw, sessionId) {
-  // ── Streaming events (realtime) ──────────────────────────────────────────
-  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 })];
-  }
-
-  // ── History / full-message events ────────────────────────────────────────
-  const messages = [];
-  const ts = raw.timestamp || new Date().toISOString();
-  const baseId = raw.uuid || generateMessageId('claude');
-
-  // User message
-  if (raw.message?.role === 'user' && raw.message?.content) {
-    if (Array.isArray(raw.message.content)) {
-      // Handle tool_result parts
-      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') {
-          // Regular text parts from user
-          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 no text parts were found, check if it's a pure user message
-      if (messages.length === 0) {
-        const textParts = raw.message.content
-          .filter(p => p.type === 'text')
-          .map(p => p.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;
-  }
-
-  // Thinking message
-  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;
-  }
-
-  // Tool use result (codex-style in Claude)
-  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;
-  }
-
-  // Assistant message
-  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;
-}
-
-/**
- * @type {import('../types.js').ProviderAdapter}
- */
-export const claudeAdapter = {
-  normalizeMessage,
-
-  /**
-   * Fetch session history from JSONL files, returning normalized messages.
-   */
-  async fetchHistory(sessionId, opts = {}) {
-    const { projectName, limit = null, offset = 0 } = opts;
-    if (!projectName) {
-      return { messages: [], total: 0, hasMore: false, offset: 0, limit: null };
-    }
-
-    let result;
-    try {
-      result = await getSessionMessages(projectName, sessionId, limit, offset);
-    } catch (error) {
-      console.warn(`[ClaudeAdapter] Failed to load session ${sessionId}:`, error.message);
-      return { messages: [], total: 0, hasMore: false, offset: 0, limit: null };
-    }
-
-    // getSessionMessages returns either an array (no limit) or { messages, total, hasMore }
-    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);
-
-    // First pass: collect tool results for attachment to tool_use messages
-    const toolResultMap = new Map();
-    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') {
-            toolResultMap.set(part.tool_use_id, {
-              content: part.content,
-              isError: Boolean(part.is_error),
-              timestamp: raw.timestamp,
-              subagentTools: raw.subagentTools,
-              toolUseResult: raw.toolUseResult,
-            });
-          }
-        }
-      }
-    }
-
-    // Second pass: normalize all messages
-    const normalized = [];
-    for (const raw of rawMessages) {
-      const entries = normalizeMessage(raw, sessionId);
-      normalized.push(...entries);
-    }
-
-    // Attach tool results to their corresponding tool_use messages
-    for (const msg of normalized) {
-      if (msg.kind === 'tool_use' && msg.toolId && toolResultMap.has(msg.toolId)) {
-        const tr = toolResultMap.get(msg.toolId);
-        msg.toolResult = {
-          content: typeof tr.content === 'string' ? tr.content : JSON.stringify(tr.content),
-          isError: tr.isError,
-          toolUseResult: tr.toolUseResult,
-        };
-        msg.subagentTools = tr.subagentTools;
-      }
-    }
-
-    return {
-      messages: normalized,
-      total,
-      hasMore,
-      offset,
-      limit,
-    };
-  },
-};

server/providers/codex/adapter.js

@@ -1,246 +0,0 @@
-/**
- * Codex (OpenAI) provider adapter.
- *
- * Normalizes Codex SDK session history into NormalizedMessage format.
- * @module adapters/codex
- */
-
-import { getCodexSessionMessages } from '../../projects.js';
-import { createNormalizedMessage, generateMessageId } from '../types.js';
-
-const PROVIDER = 'codex';
-
-/**
- * Normalize a raw Codex JSONL message into NormalizedMessage(s).
- * @param {object} raw - A single parsed message from Codex JSONL
- * @param {string} sessionId
- * @returns {import('../types.js').NormalizedMessage[]}
- */
-function normalizeCodexHistoryEntry(raw, sessionId) {
-  const ts = raw.timestamp || new Date().toISOString();
-  const baseId = raw.uuid || generateMessageId('codex');
-
-  // User message
-  if (raw.message?.role === 'user') {
-    const content = typeof raw.message.content === 'string'
-      ? raw.message.content
-      : Array.isArray(raw.message.content)
-        ? raw.message.content.map(p => typeof p === 'string' ? p : p?.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,
-    })];
-  }
-
-  // Assistant message
-  if (raw.message?.role === 'assistant') {
-    const content = typeof raw.message.content === 'string'
-      ? raw.message.content
-      : Array.isArray(raw.message.content)
-        ? raw.message.content.map(p => typeof p === 'string' ? p : p?.text || '').filter(Boolean).join('\n')
-        : '';
-    if (!content.trim()) return [];
-    return [createNormalizedMessage({
-      id: baseId,
-      sessionId,
-      timestamp: ts,
-      provider: PROVIDER,
-      kind: 'text',
-      role: 'assistant',
-      content,
-    })];
-  }
-
-  // Thinking/reasoning
-  if (raw.type === 'thinking' || raw.isReasoning) {
-    return [createNormalizedMessage({
-      id: baseId,
-      sessionId,
-      timestamp: ts,
-      provider: PROVIDER,
-      kind: 'thinking',
-      content: raw.message?.content || '',
-    })];
-  }
-
-  // Tool use
-  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,
-    })];
-  }
-
-  // Tool result
-  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 [];
-}
-
-/**
- * Normalize a raw Codex event (history JSONL or transformed SDK event) into NormalizedMessage(s).
- * @param {object} raw - A history entry (has raw.message.role) or transformed SDK event (has raw.type)
- * @param {string} sessionId
- * @returns {import('../types.js').NormalizedMessage[]}
- */
-export function normalizeMessage(raw, sessionId) {
-  // History format: has message.role
-  if (raw.message?.role) {
-    return normalizeCodexHistoryEntry(raw, sessionId);
-  }
-
-  const ts = raw.timestamp || new Date().toISOString();
-  const baseId = raw.uuid || generateMessageId('codex');
-
-  // SDK event format (output of transformCodexEvent)
-  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:
-        // Unknown item type — pass through as generic tool_use
-        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 [];
-}
-
-/**
- * @type {import('../types.js').ProviderAdapter}
- */
-export const codexAdapter = {
-  normalizeMessage,
-  /**
-   * Fetch session history from Codex JSONL files.
-   */
-  async fetchHistory(sessionId, opts = {}) {
-    const { limit = null, offset = 0 } = opts;
-
-    let result;
-    try {
-      result = await getCodexSessionMessages(sessionId, limit, offset);
-    } catch (error) {
-      console.warn(`[CodexAdapter] Failed to load session ${sessionId}:`, error.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 normalized = [];
-    for (const raw of rawMessages) {
-      const entries = normalizeCodexHistoryEntry(raw, sessionId);
-      normalized.push(...entries);
-    }
-
-    // Attach tool results to tool_use messages
-    const toolResultMap = new Map();
-    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 tr = toolResultMap.get(msg.toolId);
-        msg.toolResult = { content: tr.content, isError: tr.isError };
-      }
-    }
-
-    return {
-      messages: normalized,
-      total,
-      hasMore,
-      offset,
-      limit,
-    };
-  },
-};

server/providers/cursor/adapter.js

@@ -1,353 +0,0 @@
-/**
- * Cursor provider adapter.
- *
- * Normalizes Cursor CLI session history into NormalizedMessage format.
- * @module adapters/cursor
- */
-
-import path from 'path';
-import os from 'os';
-import crypto from 'crypto';
-import { createNormalizedMessage, generateMessageId } from '../types.js';
-
-const PROVIDER = 'cursor';
-
-/**
- * Load raw blobs from Cursor's SQLite store.db, parse the DAG structure,
- * and return sorted message blobs in chronological order.
- * @param {string} sessionId
- * @param {string} projectPath - Absolute project path (used to compute cwdId hash)
- * @returns {Promise<Array<{id: string, sequence: number, rowid: number, content: object}>>}
- */
-async function loadCursorBlobs(sessionId, projectPath) {
-  // Lazy-import sqlite so the module doesn't fail if sqlite3 is unavailable
-  const { default: sqlite3 } = await import('sqlite3');
-  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');
-
-    const blobMap = new Map();
-    const parentRefs = new Map();
-    const childRefs = new Map();
-    const jsonBlobs = [];
-
-    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'));
-          jsonBlobs.push({ ...blob, parsed });
-        } catch {
-          // skip unparseable blobs
-        }
-      } else if (blob.data) {
-        const parents = [];
-        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);
-          }
-        }
-      }
-    }
-
-    // Topological sort (DFS)
-    const visited = new Set();
-    const sorted = [];
-    function visit(nodeId) {
-      if (visited.has(nodeId)) return;
-      visited.add(nodeId);
-      for (const pid of (parentRefs.get(nodeId) || [])) visit(pid);
-      const b = blobMap.get(nodeId);
-      if (b) sorted.push(b);
-    }
-    for (const blob of allBlobs) {
-      if (!parentRefs.has(blob.id)) visit(blob.id);
-    }
-    for (const blob of allBlobs) visit(blob.id);
-
-    // Order JSON blobs by DAG appearance
-    const messageOrder = new Map();
-    let orderIndex = 0;
-    for (const blob of sorted) {
-      if (blob.data && blob.data[0] !== 0x7B) {
-        for (const jb of jsonBlobs) {
-          try {
-            const idBytes = Buffer.from(jb.id, 'hex');
-            if (blob.data.includes(idBytes) && !messageOrder.has(jb.id)) {
-              messageOrder.set(jb.id, orderIndex++);
-            }
-          } catch { /* skip */ }
-        }
-      }
-    }
-
-    const sortedJsonBlobs = jsonBlobs.sort((a, b) => {
-      const oa = messageOrder.get(a.id) ?? Number.MAX_SAFE_INTEGER;
-      const ob = messageOrder.get(b.id) ?? Number.MAX_SAFE_INTEGER;
-      return oa !== ob ? oa - ob : a.rowid - b.rowid;
-    });
-
-    const messages = [];
-    for (let idx = 0; idx < sortedJsonBlobs.length; idx++) {
-      const blob = sortedJsonBlobs[idx];
-      const parsed = blob.parsed;
-      if (!parsed) continue;
-      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();
-  }
-}
-
-/**
- * Normalize a realtime NDJSON event from Cursor CLI into NormalizedMessage(s).
- * History uses normalizeCursorBlobs (SQLite DAG), this handles streaming NDJSON.
- * @param {object|string} raw - A parsed NDJSON event or a raw text line
- * @param {string} sessionId
- * @returns {import('../types.js').NormalizedMessage[]}
- */
-export function normalizeMessage(raw, sessionId) {
-  // Structured assistant message with content array
-  if (raw && typeof raw === 'object' && raw.type === 'assistant' && raw.message?.content?.[0]?.text) {
-    return [createNormalizedMessage({ kind: 'stream_delta', content: raw.message.content[0].text, sessionId, provider: PROVIDER })];
-  }
-  // Plain string line (non-JSON output)
-  if (typeof raw === 'string' && raw.trim()) {
-    return [createNormalizedMessage({ kind: 'stream_delta', content: raw, sessionId, provider: PROVIDER })];
-  }
-  return [];
-}
-
-/**
- * @type {import('../types.js').ProviderAdapter}
- */
-export const cursorAdapter = {
-  normalizeMessage,
-  /**
-   * Fetch session history for Cursor from SQLite store.db.
-   */
-  async fetchHistory(sessionId, opts = {}) {
-    const { projectPath = '', limit = null, offset = 0 } = opts;
-
-    try {
-      const blobs = await loadCursorBlobs(sessionId, projectPath);
-      const allNormalized = cursorAdapter.normalizeCursorBlobs(blobs, sessionId);
-
-      // Apply pagination
-      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) {
-      // DB doesn't exist or is unreadable — return empty
-      console.warn(`[CursorAdapter] Failed to load session ${sessionId}:`, error.message);
-      return { messages: [], total: 0, hasMore: false, offset: 0, limit: null };
-    }
-  },
-
-  /**
-   * Normalize raw Cursor blob messages into NormalizedMessage[].
-   * @param {any[]} blobs - Raw cursor blobs from store.db ({id, sequence, rowid, content})
-   * @param {string} sessionId
-   * @returns {import('../types.js').NormalizedMessage[]}
-   */
-  normalizeCursorBlobs(blobs, sessionId) {
-    const messages = [];
-    const toolUseMap = new Map();
-
-    // Use a fixed base timestamp so messages have stable, monotonically-increasing
-    // timestamps based on their sequence number rather than wall-clock time.
-    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) {
-          // Try nested message format
-          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(p => typeof p === 'string' ? p : p?.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;
-
-        // Tool results
-        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 toolName = (part.toolName || part.name || 'Unknown Tool') === 'ApplyPatch'
-                ? 'Edit' : (part.toolName || part.name || 'Unknown Tool');
-              const toolId = part.toolCallId || part.id || `tool_${i}_${partIdx}`;
-              messages.push(createNormalizedMessage({
-                id: `${baseId}_${partIdx}`,
-                sessionId,
-                timestamp: ts,
-                provider: PROVIDER,
-                kind: 'tool_use',
-                toolName,
-                toolInput: part.args || part.input,
-                toolId,
-              }));
-              toolUseMap.set(toolId, messages[messages.length - 1]);
-            }
-          }
-        } 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);
-      }
-    }
-
-    // Attach tool results to tool_use messages
-    for (const msg of messages) {
-      if (msg.kind === 'tool_result' && msg.toolId && toolUseMap.has(msg.toolId)) {
-        const toolUse = toolUseMap.get(msg.toolId);
-        toolUse.toolResult = {
-          content: msg.content,
-          isError: msg.isError,
-        };
-      }
-    }
-
-    // Sort by sequence/rowid
-    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/providers/gemini/adapter.js

@@ -1,179 +0,0 @@
-/**
- * Gemini provider adapter.
- *
- * Normalizes Gemini CLI session history into NormalizedMessage format.
- * @module adapters/gemini
- */
-
-import sessionManager from '../../sessionManager.js';
-import { getGeminiCliSessionMessages } from '../../projects.js';
-import { createNormalizedMessage, generateMessageId } from '../types.js';
-
-const PROVIDER = 'gemini';
-
-/**
- * Normalize a realtime NDJSON event from Gemini CLI into NormalizedMessage(s).
- * Handles: message (delta/final), tool_use, tool_result, result, error.
- * @param {object} raw - A parsed NDJSON event
- * @param {string} sessionId
- * @returns {import('../types.js').NormalizedMessage[]}
- */
-export function normalizeMessage(raw, sessionId) {
-  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 msgs = [];
-    if (content) {
-      msgs.push(createNormalizedMessage({ id: baseId, sessionId, timestamp: ts, provider: PROVIDER, kind: 'stream_delta', content }));
-    }
-    // If not a delta, also send stream_end
-    if (raw.delta !== true) {
-      msgs.push(createNormalizedMessage({ sessionId, timestamp: ts, provider: PROVIDER, kind: 'stream_end' }));
-    }
-    return msgs;
-  }
-
-  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') {
-    return [createNormalizedMessage({ sessionId, timestamp: ts, provider: PROVIDER, kind: 'stream_end' })];
-  }
-
-  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 [];
-}
-
-/**
- * @type {import('../types.js').ProviderAdapter}
- */
-export const geminiAdapter = {
-  normalizeMessage,
-  /**
-   * Fetch session history for Gemini.
-   * First tries in-memory session manager, then falls back to CLI sessions on disk.
-   */
-  async fetchHistory(sessionId, opts = {}) {
-    let rawMessages;
-    try {
-      rawMessages = sessionManager.getSessionMessages(sessionId);
-
-      // Fallback to Gemini CLI sessions on disk
-      if (rawMessages.length === 0) {
-        rawMessages = await getGeminiCliSessionMessages(sessionId);
-      }
-    } catch (error) {
-      console.warn(`[GeminiAdapter] Failed to load session ${sessionId}:`, error.message);
-      return { messages: [], total: 0, hasMore: false, offset: 0, limit: null };
-    }
-
-    const normalized = [];
-    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');
-
-      // sessionManager format: { type: 'message', message: { role, content }, timestamp }
-      // CLI format: { role: 'user'|'gemini'|'assistant', content: string|array }
-      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,
-        }));
-      }
-    }
-
-    // Attach tool results to tool_use messages
-    const toolResultMap = new Map();
-    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 tr = toolResultMap.get(msg.toolId);
-        msg.toolResult = { content: tr.content, isError: tr.isError };
-      }
-    }
-
-    return {
-      messages: normalized,
-      total: normalized.length,
-      hasMore: false,
-      offset: 0,
-      limit: null,
-    };
-  },
-};

server/providers/registry.js

@@ -1,44 +0,0 @@
-/**
- * Provider Registry
- *
- * Centralizes provider adapter lookup. All code that needs a provider adapter
- * should go through this registry instead of importing individual adapters directly.
- *
- * @module providers/registry
- */
-
-import { claudeAdapter } from './claude/adapter.js';
-import { cursorAdapter } from './cursor/adapter.js';
-import { codexAdapter } from './codex/adapter.js';
-import { geminiAdapter } from './gemini/adapter.js';
-
-/**
- * @typedef {import('./types.js').ProviderAdapter} ProviderAdapter
- * @typedef {import('./types.js').SessionProvider} SessionProvider
- */
-
-/** @type {Map<string, ProviderAdapter>} */
-const providers = new Map();
-
-// Register built-in providers
-providers.set('claude', claudeAdapter);
-providers.set('cursor', cursorAdapter);
-providers.set('codex', codexAdapter);
-providers.set('gemini', geminiAdapter);
-
-/**
- * Get a provider adapter by name.
- * @param {string} name - Provider name (e.g., 'claude', 'cursor', 'codex', 'gemini')
- * @returns {ProviderAdapter | undefined}
- */
-export function getProvider(name) {
-  return providers.get(name);
-}
-
-/**
- * Get all registered provider names.
- * @returns {string[]}
- */
-export function getAllProviders() {
-  return Array.from(providers.keys());
-}

server/providers/types.js

@@ -1,118 +0,0 @@
-/**
- * Provider Types & Interface
- *
- * Defines the normalized message format and the provider adapter interface.
- * All providers normalize their native formats into NormalizedMessage
- * before sending over REST or WebSocket.
- *
- * @module providers/types
- */
-
-// ─── Session Provider ────────────────────────────────────────────────────────
-
-/**
- * @typedef {'claude' | 'cursor' | 'codex' | 'gemini'} SessionProvider
- */
-
-// ─── Message Kind ────────────────────────────────────────────────────────────
-
-/**
- * @typedef {'text' | 'tool_use' | 'tool_result' | 'thinking' | 'stream_delta' | 'stream_end'
- *   | 'error' | 'complete' | 'status' | 'permission_request' | 'permission_cancelled'
- *   | 'session_created' | 'interactive_prompt' | 'task_notification'} MessageKind
- */
-
-// ─── NormalizedMessage ───────────────────────────────────────────────────────
-
-/**
- * @typedef {Object} NormalizedMessage
- * @property {string} id - Unique message id (for dedup between server + realtime)
- * @property {string} sessionId
- * @property {string} timestamp - ISO 8601
- * @property {SessionProvider} provider
- * @property {MessageKind} kind
- *
- * Additional fields depending on kind:
- * - text:                 role ('user'|'assistant'), content, images?
- * - tool_use:             toolName, toolInput, toolId
- * - tool_result:          toolId, content, isError
- * - thinking:             content
- * - stream_delta:         content
- * - stream_end:           (no extra fields)
- * - error:                content
- * - complete:             (no extra fields)
- * - status:               text, canInterrupt?
- * - permission_request:   requestId, toolName, input, context?
- * - permission_cancelled: requestId
- * - session_created:      newSessionId
- * - interactive_prompt:   content
- * - task_notification:    status, summary
- */
-
-// ─── Fetch History ───────────────────────────────────────────────────────────
-
-/**
- * @typedef {Object} FetchHistoryOptions
- * @property {string} [projectName] - Project name (required for Claude)
- * @property {string} [projectPath] - Absolute project path (required for Cursor cwdId hash)
- * @property {number|null} [limit] - Page size (null = all messages)
- * @property {number} [offset] - Pagination offset (default: 0)
- */
-
-/**
- * @typedef {Object} FetchHistoryResult
- * @property {NormalizedMessage[]} messages - Normalized messages
- * @property {number} total - Total number of messages in the session
- * @property {boolean} hasMore - Whether more messages exist before the current page
- * @property {number} offset - Current offset
- * @property {number|null} limit - Page size used
- */
-
-// ─── Provider Adapter Interface ──────────────────────────────────────────────
-
-/**
- * Every provider adapter MUST implement this interface.
- *
- * @typedef {Object} ProviderAdapter
- *
- * @property {(sessionId: string, opts?: FetchHistoryOptions) => Promise<FetchHistoryResult>} fetchHistory
- *   Read persisted session messages from disk/database and return them as NormalizedMessage[].
- *   The backend calls this from the unified GET /api/sessions/:id/messages endpoint.
- *
- *   Provider implementations:
- *   - Claude: reads ~/.claude/projects/{projectName}/*.jsonl
- *   - Cursor: reads from SQLite store.db (via normalizeCursorBlobs helper)
- *   - Codex:  reads ~/.codex/sessions/*.jsonl
- *   - Gemini: reads from in-memory sessionManager or ~/.gemini/tmp/ JSON files
- *
- * @property {(raw: any, sessionId: string) => NormalizedMessage[]} normalizeMessage
- *   Normalize a provider-specific event (JSONL entry or live SDK event) into NormalizedMessage[].
- *   Used by provider files to convert both history and realtime events.
- */
-
-// ─── Runtime Helpers ─────────────────────────────────────────────────────────
-
-/**
- * Generate a unique message ID.
- * Uses crypto.randomUUID() to avoid collisions across server restarts and workers.
- * @param {string} [prefix='msg'] - Optional prefix
- * @returns {string}
- */
-export function generateMessageId(prefix = 'msg') {
-  return `${prefix}_${crypto.randomUUID()}`;
-}
-
-/**
- * Create a NormalizedMessage with common fields pre-filled.
- * @param {Partial<NormalizedMessage> & {kind: MessageKind, provider: SessionProvider}} fields
- * @returns {NormalizedMessage}
- */
-export function createNormalizedMessage(fields) {
-  return {
-    ...fields,
-    id: fields.id || generateMessageId(fields.kind),
-    sessionId: fields.sessionId || '',
-    timestamp: fields.timestamp || new Date().toISOString(),
-    provider: fields.provider,
-  };
-}

server/providers/utils.js

@@ -1,29 +0,0 @@
-/**
- * Shared provider utilities.
- *
- * @module providers/utils
- */
-
-/**
- * Prefixes that indicate internal/system content which should be hidden from the UI.
- * @type {readonly string[]}
- */
-export const INTERNAL_CONTENT_PREFIXES = Object.freeze([
-  '<command-name>',
-  '<command-message>',
-  '<command-args>',
-  '<local-command-stdout>',
-  '<system-reminder>',
-  'Caveat:',
-  'This session is being continued from a previous',
-  '[Request interrupted',
-]);
-
-/**
- * Check if user text content is internal/system that should be skipped.
- * @param {string} content
- * @returns {boolean}
- */
-export function isInternalContent(content) {
-  return INTERNAL_CONTENT_PREFIXES.some(prefix => content.startsWith(prefix));
-}

server/routes/agent.js

@@ -546,12 +546,7 @@ class ResponseCollector {
           const parsed = JSON.parse(msg);
           // Only include claude-response messages with assistant type
           if (parsed.type === 'claude-response' && parsed.data && parsed.data.type === 'assistant') {
-            const assistantMessage = { ...parsed.data };
-            if (assistantMessage.message?.usage) {
-              assistantMessage.message = { ...assistantMessage.message };
-              delete assistantMessage.message.usage;
-            }
-            assistantMessages.push(assistantMessage);
+            assistantMessages.push(parsed.data);
           }
         } catch (e) {
           // Not JSON, skip
@@ -561,6 +556,49 @@ class ResponseCollector {
 
     return assistantMessages;
   }
+
+  /**
+   * Calculate total tokens from all messages
+   */
+  getTotalTokens() {
+    let totalInput = 0;
+    let totalOutput = 0;
+    let totalCacheRead = 0;
+    let totalCacheCreation = 0;
+
+    for (const msg of this.messages) {
+      let data = msg;
+
+      // Parse if string
+      if (typeof msg === 'string') {
+        try {
+          data = JSON.parse(msg);
+        } catch (e) {
+          continue;
+        }
+      }
+
+      // Extract usage from claude-response messages
+      if (data && data.type === 'claude-response' && data.data) {
+        const msgData = data.data;
+        if (msgData.message && msgData.message.usage) {
+          const usage = msgData.message.usage;
+          totalInput += usage.input_tokens || 0;
+          totalOutput += usage.output_tokens || 0;
+          totalCacheRead += usage.cache_read_input_tokens || 0;
+          totalCacheCreation += usage.cache_creation_input_tokens || 0;
+        }
+      }
+    }
+
+    return {
+      inputTokens: totalInput,
+      outputTokens: totalOutput,
+      cacheReadTokens: totalCacheRead,
+      cacheCreationTokens: totalCacheCreation,
+      totalTokens: totalInput + totalOutput + totalCacheRead + totalCacheCreation
+    };
+  }
 }
 
 // ===============================
@@ -751,6 +789,13 @@ class ResponseCollector {
  *     success: true,
  *     sessionId: "session-123",
  *     messages: [...],        // Assistant messages only (filtered)
+ *     tokens: {
+ *       inputTokens: 150,
+ *       outputTokens: 50,
+ *       cacheReadTokens: 0,
+ *       cacheCreationTokens: 0,
+ *       totalTokens: 200
+ *     },
  *     projectPath: "/path/to/project",
  *     branch: {               // Only if createBranch=true
  *       name: "feature/xyz",
@@ -1128,13 +1173,15 @@ router.post('/', validateExternalApiKey, async (req, res) => {
       // Streaming mode: end the SSE stream
       writer.end();
     } else {
-      // Non-streaming mode: send filtered messages as JSON
+      // Non-streaming mode: send filtered messages and token summary as JSON
       const assistantMessages = writer.getAssistantMessages();
+      const tokenSummary = writer.getTotalTokens();
 
       const response = {
         success: true,
         sessionId: writer.getSessionId(),
         messages: assistantMessages,
+        tokens: tokenSummary,
         projectPath: finalProjectPath
       };
 

server/routes/cli-auth.js

@@ -1,434 +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
-    });
-  }
-});
-
-async function loadClaudeSettingsEnv() {
-  try {
-    const settingsPath = path.join(os.homedir(), '.claude', 'settings.json');
-    const content = await fs.readFile(settingsPath, 'utf8');
-    const settings = JSON.parse(content);
-
-    if (settings?.env && typeof settings.env === 'object') {
-      return settings.env;
-    }
-  } catch (error) {
-    // Ignore missing or malformed settings and fall back to other auth sources.
-  }
-
-  return {};
-}
-
-/**
- * Checks Claude authentication credentials using two methods with priority order:
- *
- * Priority 1: ANTHROPIC_API_KEY environment variable
- * Priority 1b: ~/.claude/settings.json env values
- * 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 1b: Check ~/.claude/settings.json env values.
-  // Claude Code can read proxy/auth values from settings.json even when the
-  // CloudCLI server process itself was not started with those env vars exported.
-  const settingsEnv = await loadClaudeSettingsEnv();
-
-  if (typeof settingsEnv.ANTHROPIC_API_KEY === 'string' && settingsEnv.ANTHROPIC_API_KEY.trim()) {
-    return {
-      authenticated: true,
-      email: 'API Key Auth',
-      method: 'api_key'
-    };
-  }
-
-  if (typeof settingsEnv.ANTHROPIC_AUTH_TOKEN === 'string' && settingsEnv.ANTHROPIC_AUTH_TOKEN.trim()) {
-    return {
-      authenticated: true,
-      email: 'Configured via settings.json',
-      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,73 +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, 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.delete('/sessions/:sessionId', async (req, res) => {
   try {
     const { sessionId } = req.params;
@@ -80,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();
 
@@ -97,6 +99,12 @@ const builtInCommands = [
     namespace: 'builtin',
     metadata: { type: 'builtin' }
   },
+  {
+    name: '/cost',
+    description: 'Display token usage and cost information',
+    namespace: 'builtin',
+    metadata: { type: 'builtin' }
+  },
   {
     name: '/memory',
     description: 'Open CLAUDE.md memory file for editing',
@@ -203,9 +211,89 @@ Custom commands can be created in:
     };
   },
 
+  '/cost': async (args, context) => {
+    const tokenUsage = context?.tokenUsage || {};
+    const provider = context?.provider || 'claude';
+    const model =
+      context?.model ||
+      (provider === 'cursor'
+        ? CURSOR_MODELS.DEFAULT
+        : provider === 'codex'
+          ? CODEX_MODELS.DEFAULT
+          : CLAUDE_MODELS.DEFAULT);
+
+    const used = Number(tokenUsage.used ?? tokenUsage.totalUsed ?? tokenUsage.total_tokens ?? 0) || 0;
+    const total =
+      Number(
+        tokenUsage.total ??
+          tokenUsage.contextWindow ??
+          parseInt(process.env.CONTEXT_WINDOW || '160000', 10),
+      ) || 160000;
+    const percentage = total > 0 ? Number(((used / total) * 100).toFixed(1)) : 0;
+
+    const inputTokensRaw =
+      Number(
+        tokenUsage.inputTokens ??
+          tokenUsage.input ??
+          tokenUsage.cumulativeInputTokens ??
+          tokenUsage.promptTokens ??
+          0,
+      ) || 0;
+    const outputTokens =
+      Number(
+        tokenUsage.outputTokens ??
+          tokenUsage.output ??
+          tokenUsage.cumulativeOutputTokens ??
+          tokenUsage.completionTokens ??
+          0,
+      ) || 0;
+    const cacheTokens =
+      Number(
+        tokenUsage.cacheReadTokens ??
+          tokenUsage.cacheCreationTokens ??
+          tokenUsage.cacheTokens ??
+          tokenUsage.cachedTokens ??
+          0,
+      ) || 0;
+
+    // If we only have total used tokens, treat them as input for display/estimation.
+    const inputTokens =
+      inputTokensRaw > 0 || outputTokens > 0 || cacheTokens > 0 ? inputTokensRaw + cacheTokens : used;
+
+    // Rough default rates by provider (USD / 1M tokens).
+    const pricingByProvider = {
+      claude: { input: 3, output: 15 },
+      cursor: { input: 3, output: 15 },
+      codex: { input: 1.5, output: 6 },
+    };
+    const rates = pricingByProvider[provider] || pricingByProvider.claude;
+
+    const inputCost = (inputTokens / 1_000_000) * rates.input;
+    const outputCost = (outputTokens / 1_000_000) * rates.output;
+    const totalCost = inputCost + outputCost;
+
+    return {
+      type: 'builtin',
+      action: 'cost',
+      data: {
+        tokenUsage: {
+          used,
+          total,
+          percentage,
+        },
+        cost: {
+          input: inputCost.toFixed(4),
+          output: outputCost.toFixed(4),
+          total: totalCost.toFixed(4),
+        },
+        model,
+      },
+    };
+  },
+
   '/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';
 
@@ -363,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/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

@@ -10,7 +10,7 @@
  */
 
 import express from 'express';
-import { getProvider, getAllProviders } from '../providers/registry.js';
+import { sessionsService } from '../modules/providers/services/sessions.service.js';
 
 const router = express.Router();
 
@@ -29,7 +29,7 @@ const router = express.Router();
 router.get('/:sessionId/messages', async (req, res) => {
   try {
     const { sessionId } = req.params;
-    const provider = req.query.provider || 'claude';
+    const provider = String(req.query.provider || 'claude').trim().toLowerCase();
     const projectName = req.query.projectName || '';
     const projectPath = req.query.projectPath || '';
     const limitParam = req.query.limit;
@@ -38,13 +38,13 @@ router.get('/:sessionId/messages', async (req, res) => {
       : null;
     const offset = parseInt(req.query.offset || '0', 10);
 
-    const adapter = getProvider(provider);
-    if (!adapter) {
-      const available = getAllProviders().join(', ');
+    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 adapter.fetchHistory(sessionId, {
+    const result = await sessionsService.fetchHistory(provider, sessionId, {
       projectName,
       projectPath,
       limit,

server/routes/settings.js

@@ -273,4 +273,14 @@ router.post('/push/unsubscribe', async (req, res) => {
   }
 });
 
+// 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.SERVER_PORT || 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

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/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",
 };

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;
@@ -42,6 +42,7 @@ interface UseChatComposerStateArgs {
   geminiModel: string;
   isLoading: boolean;
   canAbortSession: boolean;
+  tokenBudget: Record<string, unknown> | null;
   sendMessage: (message: unknown) => void;
   sendByCtrlEnter?: boolean;
   onSessionActive?: (sessionId?: string | null) => void;
@@ -56,7 +57,7 @@ interface UseChatComposerStateArgs {
   rewindMessages: (count: number) => void;
   setIsLoading: (loading: boolean) => void;
   setCanAbortSession: (canAbort: boolean) => void;
-  setClaudeStatus: (status: { text: string; can_interrupt: boolean } | null) => void;
+  setClaudeStatus: (status: { text: string; tokens: number; can_interrupt: boolean } | null) => void;
   setIsUserScrolledUp: (isScrolledUp: boolean) => void;
   setPendingPermissionRequests: Dispatch<SetStateAction<PendingPermissionRequest[]>>;
 }
@@ -113,6 +114,7 @@ export function useChatComposerState({
   geminiModel,
   isLoading,
   canAbortSession,
+  tokenBudget,
   sendMessage,
   sendByCtrlEnter,
   onSessionActive,
@@ -174,6 +176,12 @@ export function useChatComposerState({
           });
           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}`;
+          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}`;
           addMessage({ type: 'assistant', content: statusMessage, timestamp: Date.now() });
@@ -274,6 +282,7 @@ export function useChatComposerState({
           sessionId: currentSessionId,
           provider,
           model: provider === 'cursor' ? cursorModel : provider === 'codex' ? codexModel : provider === 'gemini' ? geminiModel : claudeModel,
+          tokenUsage: tokenBudget,
         };
 
         const response = await authenticatedFetch('/api/commands/execute', {
@@ -330,6 +339,7 @@ export function useChatComposerState({
       provider,
       selectedProject,
       addMessage,
+      tokenBudget,
     ],
   );
 
@@ -533,6 +543,7 @@ export function useChatComposerState({
       setCanAbortSession(true);
       setClaudeStatus({
         text: 'Processing',
+        tokens: 0,
         can_interrupt: true,
       });
 
@@ -867,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') {
@@ -983,7 +970,6 @@ export function useChatComposerState({
     syncInputOverlayScroll,
     handleClearInput,
     handleAbortSession,
-    handleTranscript,
     handlePermissionDecision,
     handleGrantToolPermission,
     handleInputFocusChange,

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;

src/components/chat/hooks/useChatRealtimeHandlers.ts

@@ -1,7 +1,7 @@
 import { useEffect, useRef } from 'react';
 import type { Dispatch, MutableRefObject, SetStateAction } from 'react';
 import type { PendingPermissionRequest } from '../types/types';
-import type { Project, ProjectSession, SessionProvider } from '../../../types/app';
+import type { Project, ProjectSession, LLMProvider } from '../../../types/app';
 import type { SessionStore, NormalizedMessage } from '../../../stores/useSessionStore';
 
 type PendingViewSession = {
@@ -38,7 +38,9 @@ type LatestChatMessage = {
   provider?: string;
   content?: string;
   text?: string;
+  tokens?: number;
   canInterrupt?: boolean;
+  tokenBudget?: unknown;
   newSessionId?: string;
   aborted?: boolean;
   [key: string]: any;
@@ -46,14 +48,15 @@ type LatestChatMessage = {
 
 interface UseChatRealtimeHandlersArgs {
   latestMessage: LatestChatMessage | null;
-  provider: SessionProvider;
+  provider: LLMProvider;
   selectedProject: Project | null;
   selectedSession: ProjectSession | null;
   currentSessionId: string | null;
   setCurrentSessionId: (sessionId: string | null) => void;
   setIsLoading: (loading: boolean) => void;
   setCanAbortSession: (canAbort: boolean) => void;
-  setClaudeStatus: (status: { text: string; can_interrupt: boolean } | null) => void;
+  setClaudeStatus: (status: { text: string; tokens: number; can_interrupt: boolean } | null) => void;
+  setTokenBudget: (budget: Record<string, unknown> | null) => void;
   setPendingPermissionRequests: Dispatch<SetStateAction<PendingPermissionRequest[]>>;
   pendingViewSessionRef: MutableRefObject<PendingViewSession | null>;
   streamBufferRef: MutableRefObject<string>;
@@ -82,6 +85,7 @@ export function useChatRealtimeHandlers({
   setIsLoading,
   setCanAbortSession,
   setClaudeStatus,
+  setTokenBudget,
   setPendingPermissionRequests,
   pendingViewSessionRef,
   streamBufferRef,
@@ -136,6 +140,7 @@ export function useChatRealtimeHandlers({
           if (status) {
             const statusInfo = {
               text: status.text || 'Working...',
+              tokens: status.tokens || 0,
               can_interrupt: status.can_interrupt !== undefined ? status.can_interrupt : true,
             };
             setClaudeStatus(statusInfo);
@@ -306,7 +311,7 @@ export function useChatRealtimeHandlers({
         });
         setIsLoading(true);
         setCanAbortSession(true);
-        setClaudeStatus({ text: 'Waiting for permission', can_interrupt: true });
+        setClaudeStatus({ text: 'Waiting for permission', tokens: 0, can_interrupt: true });
         break;
       }
 
@@ -318,9 +323,12 @@ export function useChatRealtimeHandlers({
       }
 
       case 'status': {
-        if (msg.text) {
+        if (msg.text === 'token_budget' && msg.tokenBudget) {
+          setTokenBudget(msg.tokenBudget as Record<string, unknown>);
+        } else if (msg.text) {
           setClaudeStatus({
             text: msg.text,
+            tokens: msg.tokens || 0,
             can_interrupt: msg.canInterrupt !== undefined ? msg.canInterrupt : true,
           });
           setIsLoading(true);
@@ -344,6 +352,7 @@ export function useChatRealtimeHandlers({
     setIsLoading,
     setCanAbortSession,
     setClaudeStatus,
+    setTokenBudget,
     setPendingPermissionRequests,
     pendingViewSessionRef,
     streamBufferRef,

src/components/chat/hooks/useChatSessionState.ts

@@ -1,7 +1,8 @@
 import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState } from 'react';
 import type { MutableRefObject } from 'react';
+import { authenticatedFetch } from '../../../utils/api';
 import type { ChatMessage, Provider } from '../types/types';
-import type { Project, ProjectSession, SessionProvider } from '../../../types/app';
+import type { Project, ProjectSession, LLMProvider } from '../../../types/app';
 import { createCachedDiffCalculator, type DiffCalculator } from '../utils/messageTransforms';
 import { normalizedToChatMessages } from './useChatMessages';
 import type { SessionStore, NormalizedMessage } from '../../../stores/useSessionStore';
@@ -39,7 +40,7 @@ interface ScrollRestoreState {
 function chatMessageToNormalized(
   msg: ChatMessage,
   sessionId: string,
-  provider: SessionProvider,
+  provider: LLMProvider,
 ): NormalizedMessage | null {
   const id = `local_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
   const ts = msg.timestamp instanceof Date
@@ -107,8 +108,9 @@ export function useChatSessionState({
   const [totalMessages, setTotalMessages] = useState(0);
   const [canAbortSession, setCanAbortSession] = useState(false);
   const [isUserScrolledUp, setIsUserScrolledUp] = useState(false);
+  const [tokenBudget, setTokenBudget] = useState<Record<string, unknown> | null>(null);
   const [visibleMessageCount, setVisibleMessageCount] = useState(INITIAL_VISIBLE_MESSAGES);
-  const [claudeStatus, setClaudeStatus] = useState<{ text: string; can_interrupt: boolean } | null>(null);
+  const [claudeStatus, setClaudeStatus] = useState<{ text: string; tokens: number; can_interrupt: boolean } | null>(null);
   const [allMessagesLoaded, setAllMessagesLoaded] = useState(false);
   const [isLoadingAllMessages, setIsLoadingAllMessages] = useState(false);
   const [loadAllJustFinished, setLoadAllJustFinished] = useState(false);
@@ -149,7 +151,7 @@ export function useChatSessionState({
   // When a real session ID arrives and we have a pending user message, flush it to the store
   const prevActiveSessionRef = useRef<string | null>(null);
   if (activeSessionId && activeSessionId !== prevActiveSessionRef.current && pendingUserMessage) {
-    const prov = (localStorage.getItem('selected-provider') as SessionProvider) || 'claude';
+    const prov = (localStorage.getItem('selected-provider') as LLMProvider) || 'claude';
     const normalized = chatMessageToNormalized(pendingUserMessage, activeSessionId, prov);
     if (normalized) {
       sessionStore.appendRealtime(activeSessionId, normalized);
@@ -187,7 +189,7 @@ export function useChatSessionState({
       setPendingUserMessage(msg);
       return;
     }
-    const prov = (localStorage.getItem('selected-provider') as SessionProvider) || 'claude';
+    const prov = (localStorage.getItem('selected-provider') as LLMProvider) || 'claude';
     const normalized = chatMessageToNormalized(msg, activeSessionId, prov);
     if (normalized) {
       sessionStore.appendRealtime(activeSessionId, normalized);
@@ -238,7 +240,7 @@ export function useChatSessionState({
 
       try {
         const slot = await sessionStore.fetchMore(selectedSession.id, {
-          provider: sessionProvider as SessionProvider,
+          provider: sessionProvider as LLMProvider,
           projectName: selectedProject.name,
           projectPath: selectedProject.fullPath || selectedProject.path || '',
           limit: MESSAGES_PER_PAGE,
@@ -317,6 +319,7 @@ export function useChatSessionState({
       messagesOffsetRef.current = 0;
       setHasMoreMessages(false);
       setTotalMessages(0);
+      setTokenBudget(null);
       lastLoadedSessionKeyRef.current = null;
       return;
     }
@@ -352,6 +355,7 @@ export function useChatSessionState({
     if (loadAllFinishedTimerRef.current) clearTimeout(loadAllFinishedTimerRef.current);
 
     if (sessionChanged) {
+      setTokenBudget(null);
       setIsLoading(false);
     }
 
@@ -370,7 +374,7 @@ export function useChatSessionState({
     // Fetch from server → store updates → chatMessages re-derives automatically
     setIsLoadingSessionMessages(true);
     sessionStore.fetchFromServer(selectedSession.id, {
-      provider: (selectedSession.__provider || provider) as SessionProvider,
+      provider: (selectedSession.__provider || provider) as LLMProvider,
       projectName: selectedProject.name,
       projectPath: selectedProject.fullPath || selectedProject.path || '',
       limit: MESSAGES_PER_PAGE,
@@ -379,6 +383,7 @@ export function useChatSessionState({
       if (slot) {
         setHasMoreMessages(slot.hasMore);
         setTotalMessages(slot.total);
+        if (slot.tokenUsage) setTokenBudget(slot.tokenUsage as Record<string, unknown>);
       }
       setIsLoadingSessionMessages(false);
     }).catch(() => {
@@ -405,7 +410,7 @@ export function useChatSessionState({
         // Skip store refresh during active streaming
         if (!isLoading) {
           await sessionStore.refreshFromServer(selectedSession.id, {
-            provider: (selectedSession.__provider || provider) as SessionProvider,
+            provider: (selectedSession.__provider || provider) as LLMProvider,
             projectName: selectedProject.name,
             projectPath: selectedProject.fullPath || selectedProject.path || '',
           });
@@ -463,7 +468,7 @@ export function useChatSessionState({
           try {
             // Load all messages into the store for search navigation
             const slot = await sessionStore.fetchFromServer(selectedSession.id, {
-              provider: sessionProvider as SessionProvider,
+              provider: sessionProvider as LLMProvider,
               projectName: selectedProject.name,
               projectPath: selectedProject.fullPath || selectedProject.path || '',
               limit: null,
@@ -534,6 +539,31 @@ export function useChatSessionState({
   // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [chatMessages.length, isLoadingSessionMessages, searchTarget]);
 
+  // Token usage fetch for Claude
+  useEffect(() => {
+    if (!selectedProject || !selectedSession?.id || selectedSession.id.startsWith('new-session-')) {
+      setTokenBudget(null);
+      return;
+    }
+    const sessionProvider = selectedSession.__provider || 'claude';
+    if (sessionProvider !== 'claude') return;
+
+    const fetchInitialTokenUsage = async () => {
+      try {
+        const url = `/api/projects/${selectedProject.name}/sessions/${selectedSession.id}/token-usage`;
+        const response = await authenticatedFetch(url);
+        if (response.ok) {
+          setTokenBudget(await response.json());
+        } else {
+          setTokenBudget(null);
+        }
+      } catch (error) {
+        console.error('Failed to fetch initial token usage:', error);
+      }
+    };
+    fetchInitialTokenUsage();
+  }, [selectedProject, selectedSession?.id, selectedSession?.__provider]);
+
   const visibleMessages = useMemo(() => {
     if (chatMessages.length <= visibleMessageCount) return chatMessages;
     return chatMessages.slice(-visibleMessageCount);
@@ -625,7 +655,7 @@ export function useChatSessionState({
 
     try {
       const slot = await sessionStore.fetchFromServer(requestSessionId, {
-        provider: sessionProvider as SessionProvider,
+        provider: sessionProvider as LLMProvider,
         projectName: selectedProject.name,
         projectPath: selectedProject.fullPath || selectedProject.path || '',
         limit: null,
@@ -683,6 +713,8 @@ export function useChatSessionState({
     setCanAbortSession,
     isUserScrolledUp,
     setIsUserScrolledUp,
+    tokenBudget,
+    setTokenBudget,
     visibleMessageCount,
     visibleMessages,
     loadEarlierMessages,

src/components/chat/types/types.ts

@@ -1,6 +1,6 @@
-import type { Project, ProjectSession, SessionProvider } from '../../../types/app';
+import type { Project, ProjectSession, LLMProvider } from '../../../types/app';
 
-export type Provider = SessionProvider;
+export type Provider = LLMProvider;
 
 export type PermissionMode = 'default' | 'acceptEdits' | 'bypassPermissions' | 'plan';
 

src/components/chat/view/ChatInterface.tsx

@@ -3,7 +3,7 @@ import { useTranslation } from 'react-i18next';
 import { useTasksSettings } from '../../../contexts/TasksSettingsContext';
 import { QuickSettingsPanel } from '../../quick-settings-panel';
 import type { ChatInterfaceProps, Provider  } from '../types/types';
-import type { SessionProvider } from '../../../types/app';
+import type { LLMProvider } from '../../../types/app';
 import { useChatProviderState } from '../hooks/useChatProviderState';
 import { useChatSessionState } from '../hooks/useChatSessionState';
 import { useChatRealtimeHandlers } from '../hooks/useChatRealtimeHandlers';
@@ -96,6 +96,8 @@ function ChatInterface({
     setCanAbortSession,
     isUserScrolledUp,
     setIsUserScrolledUp,
+    tokenBudget,
+    setTokenBudget,
     visibleMessageCount,
     visibleMessages,
     loadEarlierMessages,
@@ -163,7 +165,6 @@ function ChatInterface({
     syncInputOverlayScroll,
     handleClearInput,
     handleAbortSession,
-    handleTranscript,
     handlePermissionDecision,
     handleGrantToolPermission,
     handleInputFocusChange,
@@ -181,6 +182,7 @@ function ChatInterface({
     geminiModel,
     isLoading,
     canAbortSession,
+    tokenBudget,
     sendMessage,
     sendByCtrlEnter,
     onSessionActive,
@@ -204,9 +206,9 @@ function ChatInterface({
   // so missed streaming events are shown. Also reset isLoading.
   const handleWebSocketReconnect = useCallback(async () => {
     if (!selectedProject || !selectedSession) return;
-    const providerVal = (localStorage.getItem('selected-provider') as SessionProvider) || 'claude';
+    const providerVal = (localStorage.getItem('selected-provider') as LLMProvider) || 'claude';
     await sessionStore.refreshFromServer(selectedSession.id, {
-      provider: (selectedSession.__provider || providerVal) as SessionProvider,
+      provider: (selectedSession.__provider || providerVal) as LLMProvider,
       projectName: selectedProject.name,
       projectPath: selectedProject.fullPath || selectedProject.path || '',
     });
@@ -224,6 +226,7 @@ function ChatInterface({
     setIsLoading,
     setCanAbortSession,
     setClaudeStatus,
+    setTokenBudget,
     setPendingPermissionRequests,
     pendingViewSessionRef,
     streamBufferRef,
@@ -348,6 +351,7 @@ function ChatInterface({
           onModeSwitch={cyclePermissionMode}
           thinkingMode={thinkingMode}
           setThinkingMode={setThinkingMode}
+          tokenBudget={tokenBudget}
           slashCommandsCount={slashCommandsCount}
           onToggleCommandMenu={handleToggleCommandMenu}
           hasInput={Boolean(input.trim())}
@@ -402,7 +406,6 @@ function ChatInterface({
           })}
           isTextareaExpanded={isTextareaExpanded}
           sendByCtrlEnter={sendByCtrlEnter}
-          onTranscript={handleTranscript}
         />
       </div>
 

src/components/chat/view/subcomponents/ChatComposer.tsx

@@ -11,7 +11,6 @@ import type {
   SetStateAction,
   TouchEvent,
 } from 'react';
-import MicButton from '../../../mic-button/view/MicButton';
 import type { PendingPermissionRequest, PermissionMode, Provider } from '../../types/types';
 import CommandMenu from './CommandMenu';
 import ClaudeStatus from './ClaudeStatus';
@@ -41,7 +40,7 @@ interface ChatComposerProps {
     decision: { allow?: boolean; message?: string; rememberEntry?: string | null; updatedInput?: unknown },
   ) => void;
   handleGrantToolPermission: (suggestion: { entry: string; toolName: string }) => { success: boolean };
-  claudeStatus: { text: string; can_interrupt: boolean } | null;
+  claudeStatus: { text: string; tokens: number; can_interrupt: boolean } | null;
   isLoading: boolean;
   onAbortSession: () => void;
   provider: Provider | string;
@@ -49,6 +48,7 @@ interface ChatComposerProps {
   onModeSwitch: () => void;
   thinkingMode: string;
   setThinkingMode: Dispatch<SetStateAction<string>>;
+  tokenBudget: { used?: number; total?: number } | null;
   slashCommandsCount: number;
   onToggleCommandMenu: () => void;
   hasInput: boolean;
@@ -90,7 +90,6 @@ interface ChatComposerProps {
   placeholder: string;
   isTextareaExpanded: boolean;
   sendByCtrlEnter?: boolean;
-  onTranscript: (text: string) => void;
 }
 
 export default function ChatComposer({
@@ -105,6 +104,7 @@ export default function ChatComposer({
   onModeSwitch,
   thinkingMode,
   setThinkingMode,
+  tokenBudget,
   slashCommandsCount,
   onToggleCommandMenu,
   hasInput,
@@ -146,7 +146,6 @@ export default function ChatComposer({
   placeholder,
   isTextareaExpanded,
   sendByCtrlEnter,
-  onTranscript,
 }: ChatComposerProps) {
   const { t } = useTranslation('chat');
   const textareaRect = textareaRef.current?.getBoundingClientRect();
@@ -192,6 +191,7 @@ export default function ChatComposer({
           provider={provider}
           thinkingMode={thinkingMode}
           setThinkingMode={setThinkingMode}
+          tokenBudget={tokenBudget}
           slashCommandsCount={slashCommandsCount}
           onToggleCommandMenu={onToggleCommandMenu}
           hasInput={hasInput}
@@ -318,10 +318,6 @@ export default function ChatComposer({
               </svg>
             </button>
 
-            <div className="absolute right-16 top-1/2 -translate-y-1/2 transform sm:right-16" style={{ display: 'none' }}>
-              <MicButton onTranscript={onTranscript} className="h-10 w-10 sm:h-10 sm:w-10" />
-            </div>
-
             <button
               type="submit"
               disabled={!input.trim() || isLoading}

src/components/chat/view/subcomponents/ChatInputControls.tsx

@@ -2,6 +2,7 @@ import React from 'react';
 import { useTranslation } from 'react-i18next';
 import type { PermissionMode, Provider } from '../../types/types';
 import ThinkingModeSelector from './ThinkingModeSelector';
+import TokenUsagePie from './TokenUsagePie';
 
 interface ChatInputControlsProps {
   permissionMode: PermissionMode | string;
@@ -9,6 +10,7 @@ interface ChatInputControlsProps {
   provider: Provider | string;
   thinkingMode: string;
   setThinkingMode: React.Dispatch<React.SetStateAction<string>>;
+  tokenBudget: { used?: number; total?: number } | null;
   slashCommandsCount: number;
   onToggleCommandMenu: () => void;
   hasInput: boolean;
@@ -24,6 +26,7 @@ export default function ChatInputControls({
   provider,
   thinkingMode,
   setThinkingMode,
+  tokenBudget,
   slashCommandsCount,
   onToggleCommandMenu,
   hasInput,
@@ -75,6 +78,8 @@ export default function ChatInputControls({
         <ThinkingModeSelector selectedMode={thinkingMode} onModeChange={setThinkingMode} onClose={() => {}} className="" />
       )}
 
+      <TokenUsagePie used={tokenBudget?.used || 0} total={tokenBudget?.total || parseInt(import.meta.env.VITE_CONTEXT_WINDOW) || 160000} />
+
       <button
         type="button"
         onClick={onToggleCommandMenu}

src/components/chat/view/subcomponents/ChatMessagesPane.tsx

@@ -2,7 +2,7 @@ import { useTranslation } from 'react-i18next';
 import { useCallback, useRef } from 'react';
 import type { Dispatch, RefObject, SetStateAction } from 'react';
 import type { ChatMessage } from '../../types/types';
-import type { Project, ProjectSession, SessionProvider } from '../../../../types/app';
+import type { Project, ProjectSession, LLMProvider } from '../../../../types/app';
 import { getIntrinsicMessageKey } from '../../utils/messageKeys';
 import MessageComponent from './MessageComponent';
 import ProviderSelectionEmptyState from './ProviderSelectionEmptyState';
@@ -15,8 +15,8 @@ interface ChatMessagesPaneProps {
   chatMessages: ChatMessage[];
   selectedSession: ProjectSession | null;
   currentSessionId: string | null;
-  provider: SessionProvider;
-  setProvider: (provider: SessionProvider) => void;
+  provider: LLMProvider;
+  setProvider: (provider: LLMProvider) => void;
   textareaRef: RefObject<HTMLTextAreaElement>;
   claudeModel: string;
   setClaudeModel: (model: string) => void;

src/components/chat/view/subcomponents/ClaudeStatus.tsx

@@ -6,6 +6,7 @@ import SessionProviderLogo from '../../../llm-logo-provider/SessionProviderLogo'
 type ClaudeStatusProps = {
   status: {
     text?: string;
+    tokens?: number;
     can_interrupt?: boolean;
   } | null;
   onAbort?: () => void;
@@ -125,4 +126,4 @@ export default function ClaudeStatus({
       </div>
     </div>
   );
-}
+}

src/components/chat/view/subcomponents/ProviderSelectionEmptyState.tsx

@@ -1,6 +1,7 @@
-import React from "react";
+import React, { useEffect, useMemo } from "react";
 import { Check, ChevronDown } from "lucide-react";
 import { useTranslation } from "react-i18next";
+import { useServerPlatform } from "../../../../hooks/useServerPlatform";
 import SessionProviderLogo from "../../../llm-logo-provider/SessionProviderLogo";
 import {
   CLAUDE_MODELS,
@@ -8,14 +9,14 @@ import {
   CODEX_MODELS,
   GEMINI_MODELS,
 } from "../../../../../shared/modelConstants";
-import type { ProjectSession, SessionProvider } from "../../../../types/app";
+import type { ProjectSession, LLMProvider } from "../../../../types/app";
 import { NextTaskBanner } from "../../../task-master";
 
 type ProviderSelectionEmptyStateProps = {
   selectedSession: ProjectSession | null;
   currentSessionId: string | null;
-  provider: SessionProvider;
-  setProvider: (next: SessionProvider) => void;
+  provider: LLMProvider;
+  setProvider: (next: LLMProvider) => void;
   textareaRef: React.RefObject<HTMLTextAreaElement>;
   claudeModel: string;
   setClaudeModel: (model: string) => void;
@@ -32,7 +33,7 @@ type ProviderSelectionEmptyStateProps = {
 };
 
 type ProviderDef = {
-  id: SessionProvider;
+  id: LLMProvider;
   name: string;
   infoKey: string;
   accent: string;
@@ -75,7 +76,7 @@ const PROVIDERS: ProviderDef[] = [
   },
 ];
 
-function getModelConfig(p: SessionProvider) {
+function getModelConfig(p: LLMProvider) {
   if (p === "claude") return CLAUDE_MODELS;
   if (p === "codex") return CODEX_MODELS;
   if (p === "gemini") return GEMINI_MODELS;
@@ -83,7 +84,7 @@ function getModelConfig(p: SessionProvider) {
 }
 
 function getModelValue(
-  p: SessionProvider,
+  p: LLMProvider,
   c: string,
   cu: string,
   co: string,
@@ -115,11 +116,28 @@ export default function ProviderSelectionEmptyState({
   setInput,
 }: ProviderSelectionEmptyStateProps) {
   const { t } = useTranslation("chat");
+  const { isWindowsServer } = useServerPlatform();
+
+  const visibleProviders = useMemo(
+    () =>
+      isWindowsServer
+        ? PROVIDERS.filter((p) => p.id !== "cursor")
+        : PROVIDERS,
+    [isWindowsServer],
+  );
+
+  useEffect(() => {
+    if (isWindowsServer && provider === "cursor") {
+      setProvider("claude");
+      localStorage.setItem("selected-provider", "claude");
+    }
+  }, [isWindowsServer, provider, setProvider]);
+
   const nextTaskPrompt = t("tasks.nextTaskPrompt", {
     defaultValue: "Start the next task",
   });
 
-  const selectProvider = (next: SessionProvider) => {
+  const selectProvider = (next: LLMProvider) => {
     setProvider(next);
     localStorage.setItem("selected-provider", next);
     setTimeout(() => textareaRef.current?.focus(), 100);
@@ -166,8 +184,10 @@ export default function ProviderSelectionEmptyState({
           </div>
 
           {/* Provider cards — horizontal row, equal width */}
-          <div className="mb-6 grid grid-cols-2 gap-2 sm:grid-cols-4 sm:gap-2.5">
-            {PROVIDERS.map((p) => {
+          <div
+            className={`mb-6 grid grid-cols-2 gap-2 sm:gap-2.5 ${visibleProviders.length >= 4 ? "sm:grid-cols-4" : "sm:grid-cols-3"}`}
+          >
+            {visibleProviders.map((p) => {
               const active = provider === p.id;
               return (
                 <button

src/components/chat/view/subcomponents/ThinkingModeSelector.tsx

@@ -1,4 +1,5 @@
-import { useState, useRef, useEffect } from 'react';
+import { useState, useRef, useEffect, useCallback, type CSSProperties } from 'react';
+import { createPortal } from 'react-dom';
 import { Brain, X } from 'lucide-react';
 import { useTranslation } from 'react-i18next';
 import { thinkingModes } from '../../constants/thinkingModes';
@@ -12,6 +13,11 @@ type ThinkingModeSelectorProps = {
 
 function ThinkingModeSelector({ selectedMode, onModeChange, onClose, className = '' }: ThinkingModeSelectorProps) {
   const { t } = useTranslation('chat');
+  const [isOpen, setIsOpen] = useState(false);
+  const containerRef = useRef<HTMLDivElement>(null);
+  const triggerRef = useRef<HTMLButtonElement>(null);
+  const dropdownRef = useRef<HTMLDivElement>(null);
+  const [dropdownStyle, setDropdownStyle] = useState<CSSProperties | null>(null);
 
   // Mapping from mode ID to translation key
   const modeKeyMap: Record<string, string> = {
@@ -29,50 +35,143 @@ function ThinkingModeSelector({ selectedMode, onModeChange, onClose, className =
     };
   });
 
-  const [isOpen, setIsOpen] = useState(false);
-  const dropdownRef = useRef<HTMLDivElement>(null);
+  const closeDropdown = useCallback(() => {
+    setIsOpen(false);
+    onClose?.();
+  }, [onClose]);
+
+  const updateDropdownPosition = useCallback(() => {
+    const trigger = triggerRef.current;
+    const dropdown = dropdownRef.current;
+    if (!trigger || !dropdown || typeof window === 'undefined') {
+      return;
+    }
+
+    const triggerRect = trigger.getBoundingClientRect();
+    const viewportPadding = window.innerWidth < 640 ? 12 : 16;
+    const spacing = 8;
+    const width = Math.min(window.innerWidth - viewportPadding * 2, window.innerWidth < 640 ? 320 : 256);
+    let left = triggerRect.left + triggerRect.width / 2 - width / 2;
+    left = Math.max(viewportPadding, Math.min(left, window.innerWidth - width - viewportPadding));
+
+    const measuredHeight = dropdown.offsetHeight || 0;
+    const spaceBelow = window.innerHeight - triggerRect.bottom - spacing - viewportPadding;
+    const spaceAbove = triggerRect.top - spacing - viewportPadding;
+    const openBelow = spaceBelow >= Math.min(measuredHeight || 320, 320) || spaceBelow >= spaceAbove;
+    const availableHeight = Math.min(
+      window.innerHeight - viewportPadding * 2,
+      Math.max(180, openBelow ? spaceBelow : spaceAbove),
+    );
+    const panelHeight = Math.min(measuredHeight || availableHeight, availableHeight);
+    const top = openBelow
+      ? Math.min(triggerRect.bottom + spacing, window.innerHeight - viewportPadding - panelHeight)
+      : Math.max(viewportPadding, triggerRect.top - spacing - panelHeight);
+
+    setDropdownStyle({
+      position: 'fixed',
+      top,
+      left,
+      width,
+      maxHeight: availableHeight,
+      zIndex: 80,
+    });
+  }, []);
 
   useEffect(() => {
-    const handleClickOutside = (event: MouseEvent) => {
-      if (dropdownRef.current && !dropdownRef.current.contains(event.target as Node)) {
-        setIsOpen(false);
-        if (onClose) onClose();
+    if (!isOpen) {
+      setDropdownStyle(null);
+      return;
+    }
+
+    const rafId = window.requestAnimationFrame(updateDropdownPosition);
+    const handleViewportChange = () => updateDropdownPosition();
+
+    window.addEventListener('resize', handleViewportChange);
+    window.addEventListener('scroll', handleViewportChange, true);
+
+    return () => {
+      window.cancelAnimationFrame(rafId);
+      window.removeEventListener('resize', handleViewportChange);
+      window.removeEventListener('scroll', handleViewportChange, true);
+    };
+  }, [isOpen, updateDropdownPosition]);
+
+  useEffect(() => {
+    if (!isOpen) {
+      return;
+    }
+
+    const handlePointerDown = (event: PointerEvent) => {
+      const target = event.target;
+      if (!(target instanceof Node)) {
+        return;
+      }
+
+      if (containerRef.current?.contains(target) || dropdownRef.current?.contains(target)) {
+        return;
+      }
+
+      closeDropdown();
+    };
+
+    const handleKeyDown = (event: KeyboardEvent) => {
+      if (event.key === 'Escape') {
+        closeDropdown();
       }
     };
 
-    document.addEventListener('mousedown', handleClickOutside);
-    return () => document.removeEventListener('mousedown', handleClickOutside);
-  }, [onClose]);
+    document.addEventListener('pointerdown', handlePointerDown, true);
+    document.addEventListener('keydown', handleKeyDown);
+
+    return () => {
+      document.removeEventListener('pointerdown', handlePointerDown, true);
+      document.removeEventListener('keydown', handleKeyDown);
+    };
+  }, [isOpen, closeDropdown]);
 
   const currentMode = translatedModes.find(mode => mode.id === selectedMode) || translatedModes[0];
   const IconComponent = currentMode.icon || Brain;
 
   return (
-    <div className={`relative ${className}`} ref={dropdownRef}>
+    <div className={`relative ${className}`} ref={containerRef}>
       <button
+        ref={triggerRef}
         type="button"
-        onClick={() => setIsOpen(!isOpen)}
+        onClick={() => {
+          if (isOpen) {
+            closeDropdown();
+            return;
+          }
+
+          setIsOpen(true);
+        }}
         className={`flex h-10 w-10 items-center justify-center rounded-full transition-all duration-200 sm:h-10 sm:w-10 ${selectedMode === 'none'
             ? 'bg-gray-100 hover:bg-gray-200 dark:bg-gray-700 dark:hover:bg-gray-600'
             : 'bg-blue-100 hover:bg-blue-200 dark:bg-blue-900 dark:hover:bg-blue-800'
           }`}
         title={t('thinkingMode.buttonTitle', { mode: currentMode.name })}
+        aria-haspopup="dialog"
+        aria-expanded={isOpen}
       >
         <IconComponent className={`h-5 w-5 ${currentMode.color}`} />
       </button>
 
-      {isOpen && (
-        <div className="absolute bottom-full right-0 mb-2 w-64 overflow-hidden rounded-lg border border-gray-200 bg-white shadow-xl dark:border-gray-700 dark:bg-gray-800">
+      {isOpen && typeof document !== 'undefined' && createPortal(
+        <div
+          ref={dropdownRef}
+          style={dropdownStyle || { position: 'fixed', top: 0, left: 0, visibility: 'hidden' }}
+          className="flex flex-col overflow-hidden rounded-xl border border-gray-200 bg-white shadow-xl dark:border-gray-700 dark:bg-gray-800"
+          role="dialog"
+          aria-modal="false"
+        >
           <div className="border-b border-gray-200 p-3 dark:border-gray-700">
             <div className="flex items-center justify-between">
               <h3 className="text-sm font-semibold text-gray-900 dark:text-white">
                 {t('thinkingMode.selector.title')}
               </h3>
               <button
-                onClick={() => {
-                  setIsOpen(false);
-                  if (onClose) onClose();
-                }}
+                type="button"
+                onClick={closeDropdown}
                 className="rounded p-1 hover:bg-gray-100 dark:hover:bg-gray-700"
               >
                 <X className="h-4 w-4 text-gray-500" />
@@ -83,7 +182,7 @@ function ThinkingModeSelector({ selectedMode, onModeChange, onClose, className =
             </p>
           </div>
 
-          <div className="py-1">
+          <div className="min-h-0 overflow-y-auto py-1">
             {translatedModes.map((mode) => {
               const ModeIcon = mode.icon;
               const isSelected = mode.id === selectedMode;
@@ -91,10 +190,10 @@ function ThinkingModeSelector({ selectedMode, onModeChange, onClose, className =
               return (
                 <button
                   key={mode.id}
+                  type="button"
                   onClick={() => {
                     onModeChange(mode.id);
-                    setIsOpen(false);
-                    if (onClose) onClose();
+                    closeDropdown();
                   }}
                   className={`w-full px-4 py-3 text-left transition-colors hover:bg-gray-50 dark:hover:bg-gray-700 ${isSelected ? 'bg-gray-50 dark:bg-gray-700' : ''
                     }`}
@@ -135,10 +234,11 @@ function ThinkingModeSelector({ selectedMode, onModeChange, onClose, className =
               <strong>Tip:</strong> {t('thinkingMode.selector.tip')}
             </p>
           </div>
-        </div>
+        </div>,
+        document.body
       )}
     </div>
   );
 }
 
-export default ThinkingModeSelector;
+export default ThinkingModeSelector;

src/components/chat/view/subcomponents/TokenUsagePie.tsx

@@ -0,0 +1,54 @@
+type TokenUsagePieProps = {
+  used: number;
+  total: number;
+};
+
+export default function TokenUsagePie({ used, total }: TokenUsagePieProps) {
+  // Token usage visualization component
+  // Only bail out on missing values or non‐positive totals; allow used===0 to render 0%
+  if (used == null || total == null || total <= 0) return null;
+
+  const percentage = Math.min(100, (used / total) * 100);
+  const radius = 10;
+  const circumference = 2 * Math.PI * radius;
+  const offset = circumference - (percentage / 100) * circumference;
+
+  // Color based on usage level
+  const getColor = () => {
+    if (percentage < 50) return '#3b82f6'; // blue
+    if (percentage < 75) return '#f59e0b'; // orange
+    return '#ef4444'; // red
+  };
+
+  return (
+    <div className="flex items-center gap-2 text-xs text-gray-600 dark:text-gray-400">
+      <svg width="24" height="24" viewBox="0 0 24 24" className="-rotate-90 transform">
+        {/* Background circle */}
+        <circle
+          cx="12"
+          cy="12"
+          r={radius}
+          fill="none"
+          stroke="currentColor"
+          strokeWidth="2"
+          className="text-gray-300 dark:text-gray-600"
+        />
+        {/* Progress circle */}
+        <circle
+          cx="12"
+          cy="12"
+          r={radius}
+          fill="none"
+          stroke={getColor()}
+          strokeWidth="2"
+          strokeDasharray={circumference}
+          strokeDashoffset={offset}
+          strokeLinecap="round"
+        />
+      </svg>
+      <span title={`${used.toLocaleString()} / ${total.toLocaleString()} tokens`}>
+        {percentage.toFixed(1)}%
+      </span>
+    </div>
+  );
+}

src/components/git-panel/view/changes/CommitComposer.tsx

@@ -1,6 +1,5 @@
 import { Check, ChevronDown, GitCommit, RefreshCw, Sparkles } from 'lucide-react';
 import { useState } from 'react';
-import MicButton from '../../../mic-button/view/MicButton';
 import type { ConfirmationRequest } from '../../types/types';
 
 // Persists commit messages across unmount/remount, keyed by project path
@@ -147,13 +146,6 @@ export default function CommitComposer({
                   <Sparkles className="h-4 w-4" />
                 )}
               </button>
-              <div style={{ display: 'none' }}>
-                <MicButton
-                  onTranscript={(transcript) => setCommitMessage(transcript)}
-                  mode="default"
-                  className="p-1.5"
-                />
-              </div>
             </div>
           </div>
 

src/components/llm-logo-provider/SessionProviderLogo.tsx

@@ -1,11 +1,11 @@
-import type { SessionProvider } from '../../types/app';
+import type { LLMProvider } from '../../types/app';
 import ClaudeLogo from './ClaudeLogo';
 import CodexLogo from './CodexLogo';
 import CursorLogo from './CursorLogo';
 import GeminiLogo from './GeminiLogo';
 
 type SessionProviderLogoProps = {
-  provider?: SessionProvider | string | null;
+  provider?: LLMProvider | string | null;
   className?: string;
 };
 

src/components/mcp/constants.ts

@@ -0,0 +1,58 @@
+import type { McpFormState, McpProvider, McpScope, McpTransport } from './types';
+
+export const MCP_PROVIDER_NAMES: Record<McpProvider, string> = {
+  claude: 'Claude',
+  cursor: 'Cursor',
+  codex: 'Codex',
+  gemini: 'Gemini',
+};
+
+export const MCP_SUPPORTED_SCOPES: Record<McpProvider, McpScope[]> = {
+  claude: ['user', 'project', 'local'],
+  cursor: ['user', 'project'],
+  codex: ['user', 'project'],
+  gemini: ['user', 'project'],
+};
+
+export const MCP_SUPPORTED_TRANSPORTS: Record<McpProvider, McpTransport[]> = {
+  claude: ['stdio', 'http', 'sse'],
+  cursor: ['stdio', 'http'],
+  codex: ['stdio', 'http'],
+  gemini: ['stdio', 'http', 'sse'],
+};
+
+export const MCP_GLOBAL_SUPPORTED_SCOPES: McpScope[] = ['user', 'project'];
+
+export const MCP_GLOBAL_SUPPORTED_TRANSPORTS: McpTransport[] = ['stdio', 'http'];
+
+export const MCP_PROVIDER_BUTTON_CLASSES: Record<McpProvider, string> = {
+  claude: 'bg-purple-600 text-white hover:bg-purple-700',
+  cursor: 'bg-purple-600 text-white hover:bg-purple-700',
+  codex: 'bg-gray-800 text-white hover:bg-gray-900 dark:bg-gray-700 dark:hover:bg-gray-600',
+  gemini: 'bg-blue-600 text-white hover:bg-blue-700',
+};
+
+export const MCP_SUPPORTS_WORKING_DIRECTORY: Record<McpProvider, boolean> = {
+  claude: false,
+  cursor: false,
+  codex: true,
+  gemini: true,
+};
+
+export const DEFAULT_MCP_FORM: McpFormState = {
+  name: '',
+  scope: 'user',
+  workspacePath: '',
+  transport: 'stdio',
+  command: '',
+  args: [],
+  env: {},
+  cwd: '',
+  url: '',
+  headers: {},
+  envVars: [],
+  bearerTokenEnvVar: '',
+  envHttpHeaders: {},
+  importMode: 'form',
+  jsonInput: '',
+};

src/components/mcp/hooks/useMcpServerForm.ts

@@ -0,0 +1,248 @@
+import { type FormEvent, useEffect, useMemo, useState } from 'react';
+import { useTranslation } from 'react-i18next';
+
+import { DEFAULT_MCP_FORM, MCP_SUPPORTED_SCOPES, MCP_SUPPORTED_TRANSPORTS } from '../constants';
+import type { McpFormState, McpProject, McpProvider, McpScope, McpTransport, ProviderMcpServer } from '../types';
+import {
+  formatKeyValueLines,
+  getErrorMessage,
+  getProjectPath,
+  isMcpTransport,
+  parseKeyValueLines,
+  parseListLines,
+} from '../utils/mcpFormatting';
+
+type UseMcpServerFormArgs = {
+  provider: McpProvider;
+  isOpen: boolean;
+  editingServer: ProviderMcpServer | null;
+  currentProjects: McpProject[];
+  supportedScopes?: McpScope[];
+  supportedTransports?: McpTransport[];
+  unsupportedTransportMessage?: (transport: McpTransport) => string;
+  onSubmit: (formData: McpFormState, editingServer: ProviderMcpServer | null) => Promise<void>;
+};
+
+type MultilineFieldText = {
+  args: string;
+  env: string;
+  headers: string;
+  envVars: string;
+  envHttpHeaders: string;
+};
+
+const cloneDefaultForm = (
+  provider: McpProvider,
+  supportedScopes = MCP_SUPPORTED_SCOPES[provider],
+  supportedTransports = MCP_SUPPORTED_TRANSPORTS[provider],
+): McpFormState => ({
+  ...DEFAULT_MCP_FORM,
+  scope: supportedScopes[0],
+  transport: supportedTransports[0],
+  args: [],
+  env: {},
+  headers: {},
+  envVars: [],
+  envHttpHeaders: {},
+});
+
+const createFormStateFromServer = (
+  provider: McpProvider,
+  server: ProviderMcpServer,
+  supportedScopes?: McpScope[],
+  supportedTransports?: McpTransport[],
+): McpFormState => ({
+  ...cloneDefaultForm(provider, supportedScopes, supportedTransports),
+  name: server.name,
+  scope: server.scope,
+  workspacePath: server.workspacePath || '',
+  transport: server.transport,
+  command: server.command || '',
+  args: server.args || [],
+  env: server.env || {},
+  cwd: server.cwd || '',
+  url: server.url || '',
+  headers: server.headers || {},
+  envVars: server.envVars || [],
+  bearerTokenEnvVar: server.bearerTokenEnvVar || '',
+  envHttpHeaders: server.envHttpHeaders || {},
+});
+
+const createMultilineTextFromForm = (formData: McpFormState): MultilineFieldText => ({
+  args: formData.args.join('\n'),
+  env: formatKeyValueLines(formData.env),
+  headers: formatKeyValueLines(formData.headers),
+  envVars: formData.envVars.join('\n'),
+  envHttpHeaders: formatKeyValueLines(formData.envHttpHeaders),
+});
+
+const normalizeScope = (supportedScopes: McpScope[], value: McpScope): McpScope => (
+  supportedScopes.includes(value) ? value : supportedScopes[0]
+);
+
+const normalizeTransport = (supportedTransports: McpTransport[], value: McpTransport): McpTransport => (
+  supportedTransports.includes(value) ? value : supportedTransports[0]
+);
+
+export function useMcpServerForm({
+  provider,
+  isOpen,
+  editingServer,
+  currentProjects,
+  supportedScopes = MCP_SUPPORTED_SCOPES[provider],
+  supportedTransports = MCP_SUPPORTED_TRANSPORTS[provider],
+  unsupportedTransportMessage,
+  onSubmit,
+}: UseMcpServerFormArgs) {
+  const { t } = useTranslation('settings');
+  const [formData, setFormData] = useState<McpFormState>(() => (
+    cloneDefaultForm(provider, supportedScopes, supportedTransports)
+  ));
+  const [multilineText, setMultilineText] = useState<MultilineFieldText>(() => (
+    createMultilineTextFromForm(cloneDefaultForm(provider, supportedScopes, supportedTransports))
+  ));
+  const [jsonValidationError, setJsonValidationError] = useState('');
+  const [isSubmitting, setIsSubmitting] = useState(false);
+
+  const isEditing = Boolean(editingServer);
+
+  useEffect(() => {
+    if (!isOpen) {
+      return;
+    }
+
+    setJsonValidationError('');
+    if (editingServer) {
+      const nextFormData = createFormStateFromServer(provider, editingServer, supportedScopes, supportedTransports);
+      setFormData(nextFormData);
+      setMultilineText(createMultilineTextFromForm(nextFormData));
+      return;
+    }
+
+    const nextFormData = cloneDefaultForm(provider, supportedScopes, supportedTransports);
+    setFormData(nextFormData);
+    setMultilineText(createMultilineTextFromForm(nextFormData));
+  }, [editingServer, isOpen, provider, supportedScopes, supportedTransports]);
+
+  const projectOptions = useMemo(() => (
+    currentProjects
+      .map((project) => ({
+        value: getProjectPath(project),
+        label: project.displayName || project.name,
+      }))
+      .filter((project) => project.value)
+  ), [currentProjects]);
+
+  const updateForm = <K extends keyof McpFormState>(key: K, value: McpFormState[K]) => {
+    setFormData((prev) => ({ ...prev, [key]: value }));
+  };
+
+  const updateScope = (scope: McpScope) => {
+    setFormData((prev) => ({
+      ...prev,
+      scope: normalizeScope(supportedScopes, scope),
+      workspacePath: scope === 'user' ? '' : prev.workspacePath,
+    }));
+  };
+
+  const updateTransport = (transport: McpTransport) => {
+    setFormData((prev) => ({ ...prev, transport: normalizeTransport(supportedTransports, transport) }));
+  };
+
+  const validateJsonInput = (value: string) => {
+    if (!value.trim()) {
+      setJsonValidationError('');
+      return;
+    }
+
+    try {
+      const parsed = JSON.parse(value) as { type?: unknown; transport?: unknown; command?: unknown; url?: unknown };
+      const transportInput = parsed.transport || parsed.type;
+      if (!isMcpTransport(transportInput)) {
+        setJsonValidationError(t('mcpForm.validation.missingType'));
+      } else if (!supportedTransports.includes(transportInput)) {
+        setJsonValidationError(
+          unsupportedTransportMessage?.(transportInput) ?? `${provider} does not support ${transportInput} MCP servers`,
+        );
+      } else if (transportInput === 'stdio' && !parsed.command) {
+        setJsonValidationError(t('mcpForm.validation.stdioRequiresCommand'));
+      } else if ((transportInput === 'http' || transportInput === 'sse') && !parsed.url) {
+        setJsonValidationError(t('mcpForm.validation.httpRequiresUrl', { type: transportInput }));
+      } else {
+        setJsonValidationError('');
+      }
+    } catch {
+      setJsonValidationError(t('mcpForm.validation.invalidJson'));
+    }
+  };
+
+  const updateJsonInput = (value: string) => {
+    setFormData((prev) => ({ ...prev, jsonInput: value }));
+    validateJsonInput(value);
+  };
+
+  const updateMultilineText = <K extends keyof MultilineFieldText>(key: K, value: MultilineFieldText[K]) => {
+    setMultilineText((prev) => ({ ...prev, [key]: value }));
+  };
+
+  const createSubmitFormData = (): McpFormState => ({
+    ...formData,
+    args: parseListLines(multilineText.args),
+    env: parseKeyValueLines(multilineText.env),
+    headers: parseKeyValueLines(multilineText.headers),
+    envVars: parseListLines(multilineText.envVars),
+    envHttpHeaders: parseKeyValueLines(multilineText.envHttpHeaders),
+  });
+
+  const canSubmit = useMemo(() => {
+    if (!formData.name.trim()) {
+      return false;
+    }
+
+    if (formData.scope !== 'user' && !formData.workspacePath.trim()) {
+      return false;
+    }
+
+    if (formData.importMode === 'json') {
+      return Boolean(formData.jsonInput.trim()) && !jsonValidationError;
+    }
+
+    if (formData.transport === 'stdio') {
+      return Boolean(formData.command.trim());
+    }
+
+    return Boolean(formData.url.trim());
+  }, [formData, jsonValidationError]);
+
+  const handleSubmit = async (event: FormEvent<HTMLFormElement>) => {
+    event.preventDefault();
+    setIsSubmitting(true);
+
+    try {
+      // Textareas keep raw strings while editing so users can create blank
+      // lines or partial KEY=value entries without the form rewriting them.
+      await onSubmit(createSubmitFormData(), editingServer);
+    } catch (error) {
+      alert(`Error: ${getErrorMessage(error)}`);
+    } finally {
+      setIsSubmitting(false);
+    }
+  };
+
+  return {
+    formData,
+    setFormData,
+    multilineText,
+    projectOptions,
+    isEditing,
+    isSubmitting,
+    jsonValidationError,
+    canSubmit,
+    updateForm,
+    updateScope,
+    updateTransport,
+    updateJsonInput,
+    updateMultilineText,
+    handleSubmit,
+  };
+}

src/components/mcp/hooks/useMcpServers.ts

@@ -0,0 +1,535 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+
+import { authenticatedFetch } from '../../../utils/api';
+import { MCP_GLOBAL_SUPPORTED_TRANSPORTS, MCP_PROVIDER_NAMES, MCP_SUPPORTED_SCOPES } from '../constants';
+import type {
+  ApiResponse,
+  GlobalMcpServerResult,
+  McpFormState,
+  McpProject,
+  McpProvider,
+  McpScope,
+  McpTransport,
+  ProviderMcpServer,
+  UpsertProviderMcpServerPayload,
+} from '../types';
+import {
+  createMcpPayloadFromForm,
+  getErrorMessage,
+  getProjectPath,
+  isMcpScope,
+  isMcpTransport,
+} from '../utils/mcpFormatting';
+
+type ProviderMcpServerResponse = {
+  provider: McpProvider;
+  scope: McpScope;
+  servers: Array<Partial<ProviderMcpServer>>;
+};
+
+type GlobalMcpServerResponse = {
+  results: GlobalMcpServerResult[];
+};
+
+type ProjectTarget = {
+  name: string;
+  displayName: string;
+  path: string;
+};
+
+type McpServersCacheEntry = {
+  servers: ProviderMcpServer[];
+  updatedAt: number;
+};
+
+type ScopedProjectRequest = {
+  scope: McpScope;
+  project: ProjectTarget;
+};
+
+const MCP_CACHE_TTL_MS = 30_000;
+const mcpServersCache = new Map<string, McpServersCacheEntry>();
+
+// Settings users often switch between provider tabs repeatedly. A short module
+// cache prevents those tab switches from refetching every project config file.
+
+const toResponseJson = async <T>(response: Response): Promise<T> => response.json() as Promise<T>;
+
+const getApiErrorMessage = (payload: unknown, fallback: string): string => {
+  if (!payload || typeof payload !== 'object') {
+    return fallback;
+  }
+
+  const record = payload as Record<string, unknown>;
+  const error = record.error;
+  if (error && typeof error === 'object') {
+    const message = (error as Record<string, unknown>).message;
+    if (typeof message === 'string' && message.trim()) {
+      return message;
+    }
+  }
+
+  if (typeof error === 'string' && error.trim()) {
+    return error;
+  }
+
+  const details = record.details;
+  if (typeof details === 'string' && details.trim()) {
+    return details;
+  }
+
+  return fallback;
+};
+
+const normalizeTransport = (value: unknown, fallback: McpTransport = 'stdio'): McpTransport => (
+  isMcpTransport(value) ? value : fallback
+);
+
+const normalizeScope = (value: unknown, fallback: McpScope): McpScope => (
+  isMcpScope(value) ? value : fallback
+);
+
+const normalizeServer = (
+  provider: McpProvider,
+  scope: McpScope,
+  server: Partial<ProviderMcpServer>,
+  project?: ProjectTarget,
+): ProviderMcpServer => {
+  const transport = normalizeTransport(server.transport, server.url ? 'http' : 'stdio');
+  return {
+    provider,
+    name: String(server.name ?? ''),
+    scope: normalizeScope(server.scope, scope),
+    transport,
+    command: server.command,
+    args: server.args ?? [],
+    env: server.env ?? {},
+    cwd: server.cwd,
+    url: server.url,
+    headers: server.headers ?? {},
+    envVars: server.envVars ?? [],
+    bearerTokenEnvVar: server.bearerTokenEnvVar,
+    envHttpHeaders: server.envHttpHeaders ?? {},
+    workspacePath: project?.path || server.workspacePath,
+    projectName: project?.name || server.projectName,
+    projectDisplayName: project?.displayName || server.projectDisplayName,
+  };
+};
+
+const createProjectTargets = (projects: McpProject[]): ProjectTarget[] => {
+  const seen = new Set<string>();
+  return projects.reduce<ProjectTarget[]>((acc, project) => {
+    const projectPath = getProjectPath(project);
+    if (!projectPath || seen.has(projectPath)) {
+      return acc;
+    }
+
+    seen.add(projectPath);
+    acc.push({
+      name: project.name,
+      displayName: project.displayName || project.name,
+      path: projectPath,
+    });
+    return acc;
+  }, []);
+};
+
+const fetchProviderScopeServers = async (
+  provider: McpProvider,
+  scope: McpScope,
+  project?: ProjectTarget,
+): Promise<ProviderMcpServer[]> => {
+  const params = new URLSearchParams({ scope });
+  if (project?.path) {
+    params.set('workspacePath', project.path);
+  }
+
+  const response = await authenticatedFetch(`/api/providers/${provider}/mcp/servers?${params.toString()}`);
+  const data = await toResponseJson<ApiResponse<ProviderMcpServerResponse>>(response);
+
+  if (!response.ok || !data.success) {
+    throw new Error(getApiErrorMessage(data, `Failed to load ${provider} MCP servers`));
+  }
+
+  return (data.data.servers || []).map((server) => normalizeServer(provider, scope, server, project));
+};
+
+const deleteProviderServer = async (
+  provider: McpProvider,
+  server: ProviderMcpServer,
+): Promise<void> => {
+  const params = new URLSearchParams({ scope: server.scope });
+  if (server.workspacePath) {
+    params.set('workspacePath', server.workspacePath);
+  }
+
+  const response = await authenticatedFetch(
+    `/api/providers/${provider}/mcp/servers/${encodeURIComponent(server.name)}?${params.toString()}`,
+    { method: 'DELETE' },
+  );
+  const data = await toResponseJson<ApiResponse<{ removed: boolean }>>(response);
+
+  if (!response.ok || !data.success) {
+    throw new Error(getApiErrorMessage(data, 'Failed to delete MCP server'));
+  }
+};
+
+const saveProviderServer = async (
+  provider: McpProvider,
+  payload: UpsertProviderMcpServerPayload,
+): Promise<void> => {
+  const response = await authenticatedFetch(`/api/providers/${provider}/mcp/servers`, {
+    method: 'POST',
+    body: JSON.stringify(payload),
+  });
+  const data = await toResponseJson<ApiResponse<{ server: ProviderMcpServer }>>(response);
+
+  if (!response.ok || !data.success) {
+    throw new Error(getApiErrorMessage(data, 'Failed to save MCP server'));
+  }
+};
+
+const saveGlobalServer = async (
+  payload: UpsertProviderMcpServerPayload,
+): Promise<GlobalMcpServerResult[]> => {
+  const response = await authenticatedFetch('/api/providers/mcp/servers/global', {
+    method: 'POST',
+    body: JSON.stringify(payload),
+  });
+  const data = await toResponseJson<ApiResponse<GlobalMcpServerResponse>>(response);
+
+  if (!response.ok || !data.success) {
+    throw new Error(getApiErrorMessage(data, 'Failed to save MCP server to all providers'));
+  }
+
+  return data.data.results || [];
+};
+
+const didServerIdentityChange = (
+  editingServer: ProviderMcpServer,
+  payload: UpsertProviderMcpServerPayload,
+): boolean => (
+  editingServer.name !== payload.name
+  || editingServer.scope !== payload.scope
+  || (editingServer.workspacePath || '') !== (payload.workspacePath || '')
+);
+
+const getServerIdentity = (server: ProviderMcpServer): string => (
+  `${server.provider}:${server.scope}:${server.workspacePath || 'global'}:${server.name}`
+);
+
+const getCacheKey = (provider: McpProvider, projects: ProjectTarget[]): string => {
+  const projectKey = projects.map((project) => project.path).sort().join('|');
+  return `${provider}:${projectKey}`;
+};
+
+const formatGlobalAddFailures = (failures: GlobalMcpServerResult[]): string => (
+  failures
+    .map((failure) => `${MCP_PROVIDER_NAMES[failure.provider]}: ${failure.error || 'Unknown error'}`)
+    .join('; ')
+);
+
+const sortServers = (servers: ProviderMcpServer[]): ProviderMcpServer[] => {
+  const scopeOrder: Record<McpScope, number> = {
+    user: 0,
+    project: 1,
+    local: 2,
+  };
+
+  return [...servers].sort((left, right) => {
+    const scopeDelta = scopeOrder[left.scope] - scopeOrder[right.scope];
+    if (scopeDelta !== 0) {
+      return scopeDelta;
+    }
+
+    const projectDelta = (left.projectDisplayName || '').localeCompare(right.projectDisplayName || '');
+    if (projectDelta !== 0) {
+      return projectDelta;
+    }
+
+    return left.name.localeCompare(right.name);
+  });
+};
+
+const mergeServers = (
+  existingServers: ProviderMcpServer[],
+  incomingServers: ProviderMcpServer[],
+): ProviderMcpServer[] => {
+  const serversById = new Map<string, ProviderMcpServer>();
+  existingServers.forEach((server) => {
+    serversById.set(getServerIdentity(server), server);
+  });
+  incomingServers.forEach((server) => {
+    serversById.set(getServerIdentity(server), server);
+  });
+
+  return sortServers([...serversById.values()]);
+};
+
+const replaceScopedServers = (
+  existingServers: ProviderMcpServer[],
+  incomingServers: ProviderMcpServer[],
+  scope: McpScope,
+  workspacePath?: string,
+): ProviderMcpServer[] => {
+  const remainingServers = existingServers.filter((server) => (
+    server.scope !== scope || (server.workspacePath || '') !== (workspacePath || '')
+  ));
+
+  return mergeServers(remainingServers, incomingServers);
+};
+
+type UseMcpServersArgs = {
+  selectedProvider: McpProvider;
+  currentProjects: McpProject[];
+};
+
+export function useMcpServers({ selectedProvider, currentProjects }: UseMcpServersArgs) {
+  const [servers, setServers] = useState<ProviderMcpServer[]>([]);
+  const [isLoading, setIsLoading] = useState(false);
+  const [loadError, setLoadError] = useState<string | null>(null);
+  const [deleteError, setDeleteError] = useState<string | null>(null);
+  const [saveStatus, setSaveStatus] = useState<'success' | 'error' | null>(null);
+  const [isLoadingProjectScopes, setIsLoadingProjectScopes] = useState(false);
+  const [isFormOpen, setIsFormOpen] = useState(false);
+  const [isGlobalFormOpen, setIsGlobalFormOpen] = useState(false);
+  const [editingServer, setEditingServer] = useState<ProviderMcpServer | null>(null);
+  const activeLoadIdRef = useRef(0);
+
+  const projectTargets = useMemo(() => createProjectTargets(currentProjects), [currentProjects]);
+  const cacheKey = useMemo(() => getCacheKey(selectedProvider, projectTargets), [projectTargets, selectedProvider]);
+
+  const refreshServers = useCallback(async (options: { force?: boolean } = {}) => {
+    const loadId = activeLoadIdRef.current + 1;
+    activeLoadIdRef.current = loadId;
+
+    const cachedEntry = mcpServersCache.get(cacheKey);
+    const canUseCache = !options.force && cachedEntry && Date.now() - cachedEntry.updatedAt < MCP_CACHE_TTL_MS;
+    if (canUseCache) {
+      setServers(cachedEntry.servers);
+      setIsLoading(false);
+      setIsLoadingProjectScopes(false);
+      setLoadError(null);
+      return;
+    }
+
+    if (cachedEntry && !options.force) {
+      setServers(cachedEntry.servers);
+    } else {
+      setServers([]);
+    }
+
+    setIsLoading(!cachedEntry);
+    setIsLoadingProjectScopes(false);
+    setLoadError(null);
+
+    const supportedScopes = MCP_SUPPORTED_SCOPES[selectedProvider];
+    let nextServers: ProviderMcpServer[] = cachedEntry && !options.force ? cachedEntry.servers : [];
+    let firstError: string | null = null;
+
+    // Load the global/user scope first so the visible list can paint quickly.
+    // Project and local scopes can involve many project config files, so they
+    // are appended below as background requests instead of blocking this render.
+    if (supportedScopes.includes('user')) {
+      try {
+        const userServers = await fetchProviderScopeServers(selectedProvider, 'user');
+        if (activeLoadIdRef.current !== loadId) {
+          return;
+        }
+
+        nextServers = replaceScopedServers(nextServers, userServers, 'user');
+        setServers(sortServers(nextServers));
+      } catch (error) {
+        firstError = getErrorMessage(error);
+      }
+    }
+
+    if (activeLoadIdRef.current !== loadId) {
+      return;
+    }
+
+    setIsLoading(false);
+
+    const projectScopeRequests: ScopedProjectRequest[] = [];
+    projectTargets.forEach((project) => {
+      if (supportedScopes.includes('project')) {
+        projectScopeRequests.push({ scope: 'project', project });
+      }
+
+      if (supportedScopes.includes('local')) {
+        projectScopeRequests.push({ scope: 'local', project });
+      }
+    });
+
+    if (projectScopeRequests.length === 0) {
+      const finalServers = sortServers(nextServers);
+      mcpServersCache.set(cacheKey, { servers: finalServers, updatedAt: Date.now() });
+      setLoadError(firstError);
+      return;
+    }
+
+    setIsLoadingProjectScopes(true);
+
+    // Update the UI as each project scope resolves. This avoids waiting for the
+    // slowest project before showing servers from faster config files.
+    await Promise.all(projectScopeRequests.map(async ({ scope, project }) => {
+      try {
+        const scopedServers = await fetchProviderScopeServers(selectedProvider, scope, project);
+        if (activeLoadIdRef.current !== loadId) {
+          return;
+        }
+
+        nextServers = replaceScopedServers(nextServers, scopedServers, scope, project.path);
+        setServers(nextServers);
+      } catch (error) {
+        firstError = firstError || getErrorMessage(error);
+      }
+    }));
+
+    if (activeLoadIdRef.current !== loadId) {
+      return;
+    }
+
+    const finalServers = sortServers(nextServers);
+    mcpServersCache.set(cacheKey, { servers: finalServers, updatedAt: Date.now() });
+    setServers(finalServers);
+    setLoadError(firstError);
+    setIsLoadingProjectScopes(false);
+  }, [cacheKey, projectTargets, selectedProvider]);
+
+  const openForm = useCallback((server?: ProviderMcpServer) => {
+    setEditingServer(server || null);
+    setIsFormOpen(true);
+  }, []);
+
+  const closeForm = useCallback(() => {
+    setIsFormOpen(false);
+    setEditingServer(null);
+  }, []);
+
+  const openGlobalForm = useCallback(() => {
+    setIsGlobalFormOpen(true);
+  }, []);
+
+  const closeGlobalForm = useCallback(() => {
+    setIsGlobalFormOpen(false);
+  }, []);
+
+  const submitForm = useCallback(
+    async (formData: McpFormState, serverBeingEdited: ProviderMcpServer | null) => {
+      const payload = createMcpPayloadFromForm(selectedProvider, formData);
+      if (payload.scope !== 'user' && !payload.workspacePath) {
+        throw new Error('Select a project for project-scoped MCP servers');
+      }
+
+      await saveProviderServer(selectedProvider, payload);
+
+      if (serverBeingEdited && didServerIdentityChange(serverBeingEdited, payload)) {
+        await deleteProviderServer(selectedProvider, serverBeingEdited);
+      }
+
+      mcpServersCache.delete(cacheKey);
+      await refreshServers({ force: true });
+      setSaveStatus('success');
+      closeForm();
+    },
+    [cacheKey, closeForm, refreshServers, selectedProvider],
+  );
+
+  const submitGlobalForm = useCallback(
+    async (formData: McpFormState) => {
+      const payload = createMcpPayloadFromForm(selectedProvider, formData, {
+        supportedTransports: MCP_GLOBAL_SUPPORTED_TRANSPORTS,
+        supportsWorkingDirectory: false,
+        includeProviderSpecificFields: false,
+        unsupportedTransportMessage: (transport) =>
+          `Add MCP Server supports only stdio and http across all providers, not ${transport}.`,
+      });
+
+      if (payload.scope === 'local') {
+        throw new Error('Add MCP Server supports only user or project scope across all providers.');
+      }
+
+      if (payload.scope !== 'user' && !payload.workspacePath) {
+        throw new Error('Select a project for project-scoped MCP servers');
+      }
+
+      // The global endpoint updates every provider, so clear every provider
+      // cache entry instead of only the currently visible provider tab.
+      const results = await saveGlobalServer(payload);
+      mcpServersCache.clear();
+      await refreshServers({ force: true });
+
+      const failures = results.filter((result) => !result.created);
+      if (failures.length > 0) {
+        setSaveStatus('error');
+        throw new Error(`Failed to add MCP server to all providers. ${formatGlobalAddFailures(failures)}`);
+      }
+
+      setSaveStatus('success');
+      closeGlobalForm();
+    },
+    [closeGlobalForm, refreshServers, selectedProvider],
+  );
+
+  const deleteServer = useCallback(
+    async (server: ProviderMcpServer) => {
+      if (!window.confirm('Are you sure you want to delete this MCP server?')) {
+        return;
+      }
+
+      setDeleteError(null);
+      try {
+        await deleteProviderServer(selectedProvider, server);
+        mcpServersCache.delete(cacheKey);
+        await refreshServers({ force: true });
+        setSaveStatus('success');
+      } catch (error) {
+        setDeleteError(getErrorMessage(error));
+        setSaveStatus('error');
+      }
+    },
+    [cacheKey, refreshServers, selectedProvider],
+  );
+
+  useEffect(() => {
+    void refreshServers();
+  }, [refreshServers]);
+
+  useEffect(() => {
+    setIsFormOpen(false);
+    setIsGlobalFormOpen(false);
+    setEditingServer(null);
+    setDeleteError(null);
+    setSaveStatus(null);
+  }, [selectedProvider]);
+
+  useEffect(() => {
+    if (saveStatus === null) {
+      return;
+    }
+
+    const timer = window.setTimeout(() => setSaveStatus(null), 2000);
+    return () => window.clearTimeout(timer);
+  }, [saveStatus]);
+
+  return {
+    servers,
+    isLoading,
+    isLoadingProjectScopes,
+    loadError,
+    deleteError,
+    saveStatus,
+    isFormOpen,
+    isGlobalFormOpen,
+    editingServer,
+    openForm,
+    openGlobalForm,
+    closeForm,
+    closeGlobalForm,
+    submitForm,
+    submitGlobalForm,
+    deleteServer,
+    refreshServers,
+  };
+}

src/components/mcp/index.ts

@@ -0,0 +1 @@
+export { default as McpServers } from './view/McpServers';

src/components/mcp/types.ts

@@ -0,0 +1,90 @@
+import type { LLMProvider } from '../../types/app';
+
+export type McpProvider = LLMProvider;
+export type McpScope = 'user' | 'local' | 'project';
+export type McpTransport = 'stdio' | 'http' | 'sse';
+export type McpImportMode = 'form' | 'json';
+export type McpFormMode = 'provider' | 'global';
+export type KeyValueMap = Record<string, string>;
+
+export type McpProject = {
+  name: string;
+  displayName?: string;
+  fullPath?: string;
+  path?: string;
+};
+
+export type ProviderMcpServer = {
+  provider: McpProvider;
+  name: string;
+  scope: McpScope;
+  transport: McpTransport;
+  command?: string;
+  args?: string[];
+  env?: KeyValueMap;
+  cwd?: string;
+  url?: string;
+  headers?: KeyValueMap;
+  envVars?: string[];
+  bearerTokenEnvVar?: string;
+  envHttpHeaders?: KeyValueMap;
+  workspacePath?: string;
+  projectName?: string;
+  projectDisplayName?: string;
+};
+
+export type McpFormState = {
+  name: string;
+  scope: McpScope;
+  workspacePath: string;
+  transport: McpTransport;
+  command: string;
+  args: string[];
+  env: KeyValueMap;
+  cwd: string;
+  url: string;
+  headers: KeyValueMap;
+  envVars: string[];
+  bearerTokenEnvVar: string;
+  envHttpHeaders: KeyValueMap;
+  importMode: McpImportMode;
+  jsonInput: string;
+};
+
+export type UpsertProviderMcpServerPayload = {
+  name: string;
+  scope: McpScope;
+  transport: McpTransport;
+  workspacePath?: string;
+  command?: string;
+  args?: string[];
+  env?: KeyValueMap;
+  cwd?: string;
+  url?: string;
+  headers?: KeyValueMap;
+  envVars?: string[];
+  bearerTokenEnvVar?: string;
+  envHttpHeaders?: KeyValueMap;
+};
+
+export type GlobalMcpServerResult = {
+  provider: McpProvider;
+  created: boolean;
+  error?: string;
+};
+
+export type ApiSuccessResponse<T> = {
+  success: true;
+  data: T;
+};
+
+export type ApiErrorResponse = {
+  success: false;
+  error?: {
+    code?: string;
+    message?: string;
+    details?: unknown;
+  };
+};
+
+export type ApiResponse<T> = ApiSuccessResponse<T> | ApiErrorResponse;

src/components/mcp/utils/mcpFormatting.ts

@@ -0,0 +1,184 @@
+import { MCP_SUPPORTED_TRANSPORTS, MCP_SUPPORTS_WORKING_DIRECTORY } from '../constants';
+import type {
+  KeyValueMap,
+  McpFormState,
+  McpProvider,
+  McpScope,
+  McpTransport,
+  UpsertProviderMcpServerPayload,
+} from '../types';
+
+type CreateMcpPayloadOptions = {
+  supportedTransports?: McpTransport[];
+  supportsWorkingDirectory?: boolean;
+  includeProviderSpecificFields?: boolean;
+  unsupportedTransportMessage?: (transport: McpTransport) => string;
+};
+
+const isRecord = (value: unknown): value is Record<string, unknown> => (
+  Boolean(value) && typeof value === 'object' && !Array.isArray(value)
+);
+
+const readString = (value: unknown): string | undefined => (
+  typeof value === 'string' && value.trim() ? value.trim() : undefined
+);
+
+const readStringArray = (value: unknown): string[] | undefined => (
+  Array.isArray(value) ? value.filter((entry): entry is string => typeof entry === 'string') : undefined
+);
+
+const readStringRecord = (value: unknown): KeyValueMap | undefined => {
+  if (!isRecord(value)) {
+    return undefined;
+  }
+
+  const normalized: KeyValueMap = {};
+  Object.entries(value).forEach(([key, entry]) => {
+    if (typeof entry === 'string') {
+      normalized[key] = entry;
+    }
+  });
+
+  return Object.keys(normalized).length > 0 ? normalized : undefined;
+};
+
+export const formatKeyValueLines = (value: KeyValueMap): string => (
+  Object.entries(value).map(([key, entry]) => `${key}=${entry}`).join('\n')
+);
+
+export const parseKeyValueLines = (value: string): KeyValueMap => {
+  const normalized: KeyValueMap = {};
+  value.split('\n').forEach((line) => {
+    const [key, ...valueParts] = line.split('=');
+    if (key?.trim()) {
+      normalized[key.trim()] = valueParts.join('=').trim();
+    }
+  });
+  return normalized;
+};
+
+export const parseListLines = (value: string): string[] => (
+  value.split('\n').map((entry) => entry.trim()).filter(Boolean)
+);
+
+export const maskSecret = (value: unknown): string => {
+  const normalizedValue = String(value ?? '');
+  if (normalizedValue.length <= 4) {
+    return '****';
+  }
+
+  return `${normalizedValue.slice(0, 2)}****${normalizedValue.slice(-2)}`;
+};
+
+export const isMcpScope = (value: unknown): value is McpScope => (
+  value === 'user' || value === 'local' || value === 'project'
+);
+
+export const isMcpTransport = (value: unknown): value is McpTransport => (
+  value === 'stdio' || value === 'http' || value === 'sse'
+);
+
+export const getProjectPath = (project: { fullPath?: string; path?: string }): string => (
+  project.fullPath || project.path || ''
+);
+
+export const getErrorMessage = (error: unknown): string => (
+  error instanceof Error ? error.message : 'Unknown error'
+);
+
+const assertSupportedTransport = (
+  provider: McpProvider,
+  transport: McpTransport,
+  options?: CreateMcpPayloadOptions,
+) => {
+  const supportedTransports = options?.supportedTransports ?? MCP_SUPPORTED_TRANSPORTS[provider];
+  if (supportedTransports.includes(transport)) {
+    return;
+  }
+
+  throw new Error(
+    options?.unsupportedTransportMessage?.(transport) ?? `${provider} does not support ${transport} MCP servers`,
+  );
+};
+
+export const parseJsonMcpPayload = (
+  provider: McpProvider,
+  formData: McpFormState,
+  options?: CreateMcpPayloadOptions,
+): UpsertProviderMcpServerPayload => {
+  const parsed = JSON.parse(formData.jsonInput) as unknown;
+  if (!isRecord(parsed)) {
+    throw new Error('JSON configuration must be an object');
+  }
+
+  const transportInput = readString(parsed.transport) ?? readString(parsed.type);
+  const transport = isMcpTransport(transportInput) ? transportInput : undefined;
+  if (!transport) {
+    throw new Error('Missing required field: type');
+  }
+
+  assertSupportedTransport(provider, transport, options);
+
+  if (transport === 'stdio' && !readString(parsed.command)) {
+    throw new Error('stdio type requires a command field');
+  }
+
+  if ((transport === 'http' || transport === 'sse') && !readString(parsed.url)) {
+    throw new Error(`${transport} type requires a url field`);
+  }
+
+  return {
+    name: formData.name.trim(),
+    scope: formData.scope,
+    workspacePath: formData.scope === 'user' ? undefined : formData.workspacePath,
+    transport,
+    command: readString(parsed.command),
+    args: readStringArray(parsed.args) ?? [],
+    env: readStringRecord(parsed.env) ?? {},
+    cwd: (options?.supportsWorkingDirectory ?? MCP_SUPPORTS_WORKING_DIRECTORY[provider])
+      ? readString(parsed.cwd)
+      : undefined,
+    url: readString(parsed.url),
+    headers: readStringRecord(parsed.headers ?? parsed.http_headers) ?? {},
+    envVars: (options?.includeProviderSpecificFields ?? provider === 'codex')
+      ? readStringArray(parsed.envVars ?? parsed.env_vars) ?? []
+      : undefined,
+    bearerTokenEnvVar: (options?.includeProviderSpecificFields ?? provider === 'codex')
+      ? readString(parsed.bearerTokenEnvVar ?? parsed.bearer_token_env_var)
+      : undefined,
+    envHttpHeaders: (options?.includeProviderSpecificFields ?? provider === 'codex')
+      ? readStringRecord(parsed.envHttpHeaders ?? parsed.env_http_headers) ?? {}
+      : undefined,
+  };
+};
+
+export const createMcpPayloadFromForm = (
+  provider: McpProvider,
+  formData: McpFormState,
+  options?: CreateMcpPayloadOptions,
+): UpsertProviderMcpServerPayload => {
+  if (formData.importMode === 'json') {
+    return parseJsonMcpPayload(provider, formData, options);
+  }
+
+  assertSupportedTransport(provider, formData.transport, options);
+
+  const supportsWorkingDirectory = options?.supportsWorkingDirectory ?? MCP_SUPPORTS_WORKING_DIRECTORY[provider];
+  const includeProviderSpecificFields = options?.includeProviderSpecificFields ?? provider === 'codex';
+
+  return {
+    name: formData.name.trim(),
+    scope: formData.scope,
+    workspacePath: formData.scope === 'user' ? undefined : formData.workspacePath,
+    transport: formData.transport,
+    command: formData.transport === 'stdio' ? formData.command.trim() : undefined,
+    args: formData.transport === 'stdio' ? formData.args : undefined,
+    env: formData.env,
+    cwd: supportsWorkingDirectory ? formData.cwd.trim() || undefined : undefined,
+    url: formData.transport !== 'stdio' ? formData.url.trim() : undefined,
+    headers: formData.transport !== 'stdio' ? formData.headers : undefined,
+    envVars: includeProviderSpecificFields ? formData.envVars : undefined,
+    bearerTokenEnvVar: includeProviderSpecificFields ? formData.bearerTokenEnvVar.trim() || undefined : undefined,
+    envHttpHeaders: includeProviderSpecificFields ? formData.envHttpHeaders : undefined,
+  };
+};

src/components/mcp/view/McpServers.tsx

@@ -0,0 +1,281 @@
+import { Edit3, ExternalLink, Globe, Lock, Plus, Server, Terminal, Trash2, Users, Zap } from 'lucide-react';
+import { useTranslation } from 'react-i18next';
+
+import type { McpProject, McpProvider, McpScope, ProviderMcpServer } from '../types';
+import { IS_PLATFORM } from '../../../constants/config';
+import { Badge, Button } from '../../../shared/view/ui';
+import {
+  MCP_GLOBAL_SUPPORTED_SCOPES,
+  MCP_GLOBAL_SUPPORTED_TRANSPORTS,
+  MCP_PROVIDER_BUTTON_CLASSES,
+  MCP_PROVIDER_NAMES,
+} from '../constants';
+import { useMcpServers } from '../hooks/useMcpServers';
+import { maskSecret } from '../utils/mcpFormatting';
+
+import McpServerFormModal from './modals/McpServerFormModal';
+
+type McpServersProps = {
+  selectedProvider: McpProvider;
+  currentProjects: McpProject[];
+};
+
+const getTransportIcon = (transport: string | undefined) => {
+  if (transport === 'stdio') {
+    return <Terminal className="h-4 w-4" />;
+  }
+
+  if (transport === 'sse') {
+    return <Zap className="h-4 w-4" />;
+  }
+
+  if (transport === 'http') {
+    return <Globe className="h-4 w-4" />;
+  }
+
+  return <Server className="h-4 w-4" />;
+};
+
+const getScopeLabel = (scope: McpScope): string => {
+  if (scope === 'user') {
+    return 'user';
+  }
+
+  if (scope === 'local') {
+    return 'local';
+  }
+
+  return 'project';
+};
+
+const getServerKey = (server: ProviderMcpServer): string => (
+  `${server.provider}:${server.scope}:${server.workspacePath || 'global'}:${server.name}`
+);
+
+function ConfigLine({ label, children }: { label: string; children: string }) {
+  if (!children) {
+    return null;
+  }
+
+  return (
+    <div>
+      {label}:{' '}
+      <code className="rounded bg-muted px-1 text-xs">{children}</code>
+    </div>
+  );
+}
+
+function TeamMcpFeatureCard() {
+  return (
+    <div className="rounded-xl border border-dashed border-border/60 bg-muted/20 p-5">
+      <div className="flex items-start gap-3">
+        <div className="flex h-9 w-9 flex-shrink-0 items-center justify-center rounded-lg bg-muted/60 text-muted-foreground">
+          <Users className="h-5 w-5" />
+        </div>
+        <div className="min-w-0 flex-1">
+          <div className="flex items-center gap-2">
+            <h4 className="text-sm font-medium text-foreground">Team MCP Configs</h4>
+            <Lock className="h-3 w-3 text-muted-foreground/60" />
+          </div>
+          <p className="mt-1 text-xs leading-relaxed text-muted-foreground">
+            Share MCP server configurations across your team. Everyone stays in sync automatically.
+          </p>
+          <a
+            href="https://cloudcli.ai"
+            target="_blank"
+            rel="noopener noreferrer"
+            className="mt-3 inline-flex items-center gap-1 text-xs font-medium text-primary transition-colors hover:underline"
+          >
+            Available with CloudCLI Pro
+            <ExternalLink className="h-3 w-3" />
+          </a>
+        </div>
+      </div>
+    </div>
+  );
+}
+
+export default function McpServers({ selectedProvider, currentProjects }: McpServersProps) {
+  const { t } = useTranslation('settings');
+  const {
+    servers,
+    isLoading,
+    isLoadingProjectScopes,
+    loadError,
+    deleteError,
+    saveStatus,
+    isFormOpen,
+    isGlobalFormOpen,
+    editingServer,
+    openForm,
+    openGlobalForm,
+    closeForm,
+    closeGlobalForm,
+    submitForm,
+    submitGlobalForm,
+    deleteServer,
+  } = useMcpServers({ selectedProvider, currentProjects });
+
+  const providerName = MCP_PROVIDER_NAMES[selectedProvider];
+  const description = t(`mcpServers.description.${selectedProvider}`, {
+    defaultValue: `Model Context Protocol servers provide additional tools and data sources to ${providerName}`,
+  });
+  const globalButtonLabel = 'Add Global MCP Server';
+  const providerButtonLabel = `Add ${providerName} MCP Server`;
+  const globalAddDescription = 'Add Global MCP Server writes one common stdio or HTTP server to Claude, Cursor, Codex, and Gemini.';
+  const providerAddDescription = `${providerButtonLabel} only changes ${providerName}.`;
+  const globalModalDescription = 'Adds this MCP server to every provider: Claude, Cursor, Codex, and Gemini. '
+    + 'Only stdio and HTTP transports are supported because the same config must work across all providers.';
+
+  return (
+    <div className="space-y-4">
+      <div className="flex items-center gap-3">
+        <Server className="h-5 w-5 text-purple-500" />
+        <h3 className="text-lg font-medium text-foreground">{t('mcpServers.title')}</h3>
+      </div>
+      <p className="text-sm text-muted-foreground">{description}</p>
+
+      <div className="space-y-2">
+        <div className="flex flex-wrap items-center gap-2">
+          <Button
+            onClick={openGlobalForm}
+            className={MCP_PROVIDER_BUTTON_CLASSES[selectedProvider]}
+            size="sm"
+            title={globalAddDescription}
+          >
+            <Plus className="mr-2 h-4 w-4" />
+            {globalButtonLabel}
+          </Button>
+          <Button
+            onClick={() => openForm()}
+            variant="outline"
+            size="sm"
+            title={providerAddDescription}
+          >
+            <Plus className="mr-2 h-4 w-4" />
+            {providerButtonLabel}
+          </Button>
+        </div>
+        <div className="min-h-4">
+          {saveStatus === 'success' && (
+            <span className="animate-in fade-in text-xs text-muted-foreground">{t('saveStatus.success')}</span>
+          )}
+          {isLoadingProjectScopes && (
+            <span className="animate-in fade-in text-xs text-muted-foreground">Refreshing project scopes...</span>
+          )}
+        </div>
+      </div>
+
+      {(loadError || deleteError) && (
+        <div className="rounded-lg border border-red-200 bg-red-50 px-3 py-2 text-sm text-red-700 dark:border-red-800/60 dark:bg-red-900/20 dark:text-red-200">
+          {deleteError || loadError}
+        </div>
+      )}
+
+      <div className="space-y-2">
+        {isLoading && servers.length === 0 && (
+          <div className="py-8 text-center text-muted-foreground">Loading MCP servers...</div>
+        )}
+
+        {servers.map((server) => (
+          <div key={getServerKey(server)} className="rounded-lg border border-border bg-card/50 p-4">
+            <div className="flex items-start justify-between">
+              <div className="min-w-0 flex-1">
+                <div className="mb-2 flex flex-wrap items-center gap-2">
+                  {getTransportIcon(server.transport)}
+                  <span className="font-medium text-foreground">{server.name}</span>
+                  <Badge variant="outline" className="text-xs">
+                    {server.transport || 'stdio'}
+                  </Badge>
+                  <Badge variant="outline" className="text-xs">
+                    {getScopeLabel(server.scope)}
+                  </Badge>
+                  {server.projectDisplayName && (
+                    <Badge variant="outline" className="max-w-full truncate text-xs">
+                      {server.projectDisplayName}
+                    </Badge>
+                  )}
+                </div>
+
+                <div className="space-y-1 text-sm text-muted-foreground">
+                  <ConfigLine label={t('mcpServers.config.command')}>{server.command || ''}</ConfigLine>
+                  <ConfigLine label={t('mcpServers.config.url')}>{server.url || ''}</ConfigLine>
+                  <ConfigLine label={t('mcpServers.config.args')}>{(server.args || []).join(' ')}</ConfigLine>
+                  <ConfigLine label="Cwd">{server.cwd || ''}</ConfigLine>
+                  {server.env && Object.keys(server.env).length > 0 && (
+                    <ConfigLine label={t('mcpServers.config.environment')}>
+                      {Object.entries(server.env).map(([key, value]) => `${key}=${maskSecret(value)}`).join(', ')}
+                    </ConfigLine>
+                  )}
+                  {server.envVars && server.envVars.length > 0 && (
+                    <ConfigLine label="Env Vars">{server.envVars.join(', ')}</ConfigLine>
+                  )}
+                </div>
+              </div>
+
+              <div className="ml-4 flex items-center gap-2">
+                <Button
+                  onClick={() => openForm(server)}
+                  variant="ghost"
+                  size="sm"
+                  className="text-muted-foreground hover:text-foreground"
+                  title={t('mcpServers.actions.edit')}
+                >
+                  <Edit3 className="h-4 w-4" />
+                </Button>
+                <Button
+                  onClick={() => deleteServer(server)}
+                  variant="ghost"
+                  size="sm"
+                  className="text-red-600 hover:text-red-700"
+                  title={t('mcpServers.actions.delete')}
+                >
+                  <Trash2 className="h-4 w-4" />
+                </Button>
+              </div>
+            </div>
+          </div>
+        ))}
+
+        {!isLoading && !isLoadingProjectScopes && servers.length === 0 && (
+          <div className="py-8 text-center text-muted-foreground">{t('mcpServers.empty')}</div>
+        )}
+      </div>
+
+      {selectedProvider === 'codex' && (
+        <div className="rounded-lg border border-border bg-muted/50 p-4">
+          <h4 className="mb-2 font-medium text-foreground">{t('mcpServers.help.title')}</h4>
+          <p className="text-sm text-muted-foreground">{t('mcpServers.help.description')}</p>
+        </div>
+      )}
+
+      {selectedProvider === 'claude' && !IS_PLATFORM && <TeamMcpFeatureCard />}
+
+      <McpServerFormModal
+        provider={selectedProvider}
+        isOpen={isFormOpen}
+        editingServer={editingServer}
+        currentProjects={currentProjects}
+        title={editingServer ? undefined : providerButtonLabel}
+        submitLabel={providerButtonLabel}
+        onClose={closeForm}
+        onSubmit={submitForm}
+      />
+
+      <McpServerFormModal
+        provider={selectedProvider}
+        mode="global"
+        isOpen={isGlobalFormOpen}
+        editingServer={null}
+        currentProjects={currentProjects}
+        title={globalButtonLabel}
+        description={globalModalDescription}
+        submitLabel={globalButtonLabel}
+        supportedScopes={MCP_GLOBAL_SUPPORTED_SCOPES}
+        supportedTransports={MCP_GLOBAL_SUPPORTED_TRANSPORTS}
+        onClose={closeGlobalForm}
+        onSubmit={(formData) => submitGlobalForm(formData)}
+      />
+    </div>
+  );
+}

src/components/mcp/view/modals/McpServerFormModal.tsx

@@ -0,0 +1,434 @@
+import { FolderOpen, Globe, X } from 'lucide-react';
+import { useTranslation } from 'react-i18next';
+
+import { Button, Input } from '../../../../shared/view/ui';
+import {
+  MCP_PROVIDER_NAMES,
+  MCP_SUPPORTED_SCOPES,
+  MCP_SUPPORTED_TRANSPORTS,
+  MCP_SUPPORTS_WORKING_DIRECTORY,
+} from '../../constants';
+import { useMcpServerForm } from '../../hooks/useMcpServerForm';
+import type {
+  McpFormMode,
+  McpFormState,
+  McpProject,
+  McpProvider,
+  McpScope,
+  McpTransport,
+  ProviderMcpServer,
+} from '../../types';
+
+type McpServerFormModalProps = {
+  provider: McpProvider;
+  mode?: McpFormMode;
+  isOpen: boolean;
+  editingServer: ProviderMcpServer | null;
+  currentProjects: McpProject[];
+  title?: string;
+  description?: string;
+  submitLabel?: string;
+  supportedScopes?: McpScope[];
+  supportedTransports?: McpTransport[];
+  onClose: () => void;
+  onSubmit: (formData: McpFormState, editingServer: ProviderMcpServer | null) => Promise<void>;
+};
+
+const getScopeLabel = (scope: McpScope, mode: McpFormMode): string => {
+  if (scope === 'user') {
+    return mode === 'global' ? 'User (All Providers)' : 'User (Global)';
+  }
+
+  if (scope === 'local') {
+    return 'Claude Local';
+  }
+
+  return mode === 'global' ? 'Project (All Providers)' : 'Project';
+};
+
+const getScopeDescription = (scope: McpScope, mode: McpFormMode): string => {
+  if (scope === 'user') {
+    return mode === 'global'
+      ? 'Writes to each provider user config and is available across projects on this machine'
+      : 'Available across all projects on your machine';
+  }
+
+  if (scope === 'local') {
+    return 'Stored in Claude user settings for the selected project';
+  }
+
+  return mode === 'global'
+    ? 'Writes to the selected project workspace for every provider'
+    : 'Stored in the selected project workspace';
+};
+
+export default function McpServerFormModal({
+  provider,
+  mode = 'provider',
+  isOpen,
+  editingServer,
+  currentProjects,
+  title,
+  description,
+  submitLabel,
+  supportedScopes,
+  supportedTransports,
+  onClose,
+  onSubmit,
+}: McpServerFormModalProps) {
+  const { t } = useTranslation('settings');
+  const isGlobalMode = mode === 'global';
+  const availableScopes = supportedScopes ?? MCP_SUPPORTED_SCOPES[provider];
+  const availableTransports = supportedTransports ?? MCP_SUPPORTED_TRANSPORTS[provider];
+  const {
+    formData,
+    multilineText,
+    projectOptions,
+    isEditing,
+    isSubmitting,
+    jsonValidationError,
+    canSubmit,
+    updateForm,
+    updateScope,
+    updateTransport,
+    updateJsonInput,
+    updateMultilineText,
+    handleSubmit,
+  } = useMcpServerForm({
+    provider,
+    isOpen,
+    editingServer,
+    currentProjects,
+    supportedScopes: availableScopes,
+    supportedTransports: availableTransports,
+    unsupportedTransportMessage: isGlobalMode
+      ? (transport) => `Add MCP Server supports only stdio and http across all providers, not ${transport}.`
+      : undefined,
+    onSubmit,
+  });
+
+  if (!isOpen) {
+    return null;
+  }
+
+  const providerName = MCP_PROVIDER_NAMES[provider];
+  const modalTitle = title ?? (isEditing ? t('mcpForm.title.edit') : t('mcpForm.title.add'));
+  const addButtonLabel = submitLabel ?? `${t('mcpForm.actions.addServer')} to ${providerName}`;
+  const showProjectSelector = formData.scope !== 'user';
+  const supportsHttpHeaders = formData.transport === 'http' || formData.transport === 'sse';
+  const supportsWorkingDirectory = !isGlobalMode && MCP_SUPPORTS_WORKING_DIRECTORY[provider];
+  const showCodexOnlyFields = provider === 'codex' && !isGlobalMode;
+
+  return (
+    <div className="fixed inset-0 z-[110] flex items-center justify-center bg-black/50 p-4">
+      <div className="max-h-[90vh] w-full max-w-2xl overflow-y-auto rounded-lg border border-border bg-background">
+        <div className="flex items-center justify-between border-b border-border p-4">
+          <h3 className="text-lg font-medium text-foreground">{modalTitle}</h3>
+          <Button variant="ghost" size="sm" onClick={onClose}>
+            <X className="h-4 w-4" />
+          </Button>
+        </div>
+
+        <form onSubmit={handleSubmit} className="space-y-4 p-4">
+          {description && (
+            <div className="rounded-lg border border-border bg-muted/40 px-3 py-2 text-sm text-muted-foreground">
+              {description}
+            </div>
+          )}
+
+          {!isEditing && (
+            <div className="mb-4 flex gap-2">
+              <button
+                type="button"
+                onClick={() => updateForm('importMode', 'form')}
+                className={`rounded-lg px-4 py-2 font-medium transition-colors ${
+                  formData.importMode === 'form'
+                    ? 'bg-blue-600 text-white'
+                    : 'bg-gray-100 text-gray-700 hover:bg-gray-200 dark:bg-gray-800 dark:text-gray-300 dark:hover:bg-gray-700'
+                }`}
+              >
+                {t('mcpForm.importMode.form')}
+              </button>
+              <button
+                type="button"
+                onClick={() => updateForm('importMode', 'json')}
+                className={`rounded-lg px-4 py-2 font-medium transition-colors ${
+                  formData.importMode === 'json'
+                    ? 'bg-blue-600 text-white'
+                    : 'bg-gray-100 text-gray-700 hover:bg-gray-200 dark:bg-gray-800 dark:text-gray-300 dark:hover:bg-gray-700'
+                }`}
+              >
+                {t('mcpForm.importMode.json')}
+              </button>
+            </div>
+          )}
+
+          {isEditing && (
+            <div className="rounded-lg border border-gray-200 bg-gray-50 p-3 dark:border-gray-700 dark:bg-gray-900/50">
+              <label className="mb-2 block text-sm font-medium text-foreground">
+                {t('mcpForm.scope.label')}
+              </label>
+              <div className="flex items-center gap-2">
+                {formData.scope === 'user' ? <Globe className="h-4 w-4" /> : <FolderOpen className="h-4 w-4" />}
+                <span className="text-sm">{getScopeLabel(formData.scope, mode)}</span>
+                {formData.workspacePath && (
+                  <span className="truncate text-xs text-muted-foreground">- {formData.workspacePath}</span>
+                )}
+              </div>
+              <p className="mt-2 text-xs text-muted-foreground">{t('mcpForm.scope.cannotChange')}</p>
+            </div>
+          )}
+
+          {!isEditing && (
+            <div className="space-y-4">
+              <div>
+                <label className="mb-2 block text-sm font-medium text-foreground">
+                  {t('mcpForm.scope.label')} *
+                </label>
+                <div className="grid grid-cols-1 gap-2 sm:grid-cols-2">
+                  {availableScopes.map((scope) => (
+                    <button
+                      key={scope}
+                      type="button"
+                      onClick={() => updateScope(scope)}
+                      className={`rounded-lg px-4 py-2 font-medium transition-colors ${
+                        formData.scope === scope
+                          ? 'bg-blue-600 text-white'
+                          : 'bg-gray-100 text-gray-700 hover:bg-gray-200 dark:bg-gray-800 dark:text-gray-300 dark:hover:bg-gray-700'
+                      }`}
+                    >
+                      <div className="flex items-center justify-center gap-2">
+                        {scope === 'user' ? <Globe className="h-4 w-4" /> : <FolderOpen className="h-4 w-4" />}
+                        <span>{getScopeLabel(scope, mode)}</span>
+                      </div>
+                    </button>
+                  ))}
+                </div>
+                <p className="mt-2 text-xs text-muted-foreground">{getScopeDescription(formData.scope, mode)}</p>
+              </div>
+
+              {showProjectSelector && (
+                <div>
+                  <label className="mb-2 block text-sm font-medium text-foreground">
+                    {t('mcpForm.fields.selectProject')} *
+                  </label>
+                  <select
+                    value={formData.workspacePath}
+                    onChange={(event) => updateForm('workspacePath', event.target.value)}
+                    className="w-full rounded-lg border border-gray-300 bg-gray-50 px-3 py-2 text-gray-900 focus:border-blue-500 focus:ring-blue-500 dark:border-gray-600 dark:bg-gray-800 dark:text-gray-100"
+                    required
+                  >
+                    <option value="">{t('mcpForm.fields.selectProject')}</option>
+                    {projectOptions.map((project) => (
+                      <option key={project.value} value={project.value}>
+                        {project.label}
+                      </option>
+                    ))}
+                  </select>
+                  {formData.workspacePath && (
+                    <p className="mt-1 truncate text-xs text-muted-foreground">
+                      {t('mcpForm.projectPath', { path: formData.workspacePath })}
+                    </p>
+                  )}
+                </div>
+              )}
+            </div>
+          )}
+
+          <div className="grid grid-cols-1 gap-4 md:grid-cols-2">
+            <div className={formData.importMode === 'json' ? 'md:col-span-2' : ''}>
+              <label className="mb-2 block text-sm font-medium text-foreground">
+                {t('mcpForm.fields.serverName')} *
+              </label>
+              <Input
+                value={formData.name}
+                onChange={(event) => updateForm('name', event.target.value)}
+                placeholder={t('mcpForm.placeholders.serverName')}
+                required
+              />
+            </div>
+
+            {formData.importMode === 'form' && (
+              <div>
+                <label className="mb-2 block text-sm font-medium text-foreground">
+                  {t('mcpForm.fields.transportType')} *
+                </label>
+                <select
+                  value={formData.transport}
+                  onChange={(event) => updateTransport(event.target.value as McpFormState['transport'])}
+                  className="w-full rounded-lg border border-gray-300 bg-gray-50 px-3 py-2 text-gray-900 focus:border-blue-500 focus:ring-blue-500 dark:border-gray-600 dark:bg-gray-800 dark:text-gray-100"
+                >
+                  {availableTransports.map((transport) => (
+                    <option key={transport} value={transport}>
+                      {transport === 'sse' ? 'SSE' : transport.toUpperCase()}
+                    </option>
+                  ))}
+                </select>
+              </div>
+            )}
+          </div>
+
+          {formData.importMode === 'json' && (
+            <div>
+              <label className="mb-2 block text-sm font-medium text-foreground">
+                {t('mcpForm.fields.jsonConfig')} *
+              </label>
+              <textarea
+                value={formData.jsonInput}
+                onChange={(event) => updateJsonInput(event.target.value)}
+                className={`w-full border px-3 py-2 ${
+                  jsonValidationError ? 'border-red-500' : 'border-gray-300 dark:border-gray-600'
+                } rounded-lg bg-gray-50 font-mono text-sm text-gray-900 focus:border-blue-500 focus:ring-blue-500 dark:bg-gray-800 dark:text-gray-100`}
+                rows={8}
+                placeholder={'{\n  "type": "stdio",\n  "command": "npx",\n  "args": ["@upstash/context7-mcp"]\n}'}
+                required
+              />
+              {jsonValidationError && (
+                <p className="mt-1 text-xs text-red-500">{jsonValidationError}</p>
+              )}
+              <p className="mt-2 text-xs text-muted-foreground">
+                {t('mcpForm.validation.jsonHelp')}
+                <br />
+                - stdio: {`{"type":"stdio","command":"npx","args":["@upstash/context7-mcp"]}`}
+                <br />
+                - http/sse: {`{"type":"http","url":"https://api.example.com/mcp"}`}
+              </p>
+            </div>
+          )}
+
+          {formData.importMode === 'form' && formData.transport === 'stdio' && (
+            <div className="space-y-4">
+              <div>
+                <label className="mb-2 block text-sm font-medium text-foreground">
+                  {t('mcpForm.fields.command')} *
+                </label>
+                <Input
+                  value={formData.command}
+                  onChange={(event) => updateForm('command', event.target.value)}
+                  placeholder="npx @my-org/mcp-server"
+                  required
+                />
+              </div>
+
+              <div>
+                <label className="mb-2 block text-sm font-medium text-foreground">
+                  {t('mcpForm.fields.arguments')}
+                </label>
+                <textarea
+                  value={multilineText.args}
+                  onChange={(event) => updateMultilineText('args', event.target.value)}
+                  className="w-full rounded-lg border border-gray-300 bg-gray-50 px-3 py-2 text-gray-900 focus:border-blue-500 focus:ring-blue-500 dark:border-gray-600 dark:bg-gray-800 dark:text-gray-100"
+                  rows={3}
+                  placeholder="--port&#10;3000"
+                />
+              </div>
+
+              {supportsWorkingDirectory && (
+                <div>
+                  <label className="mb-2 block text-sm font-medium text-foreground">
+                    Working Directory
+                  </label>
+                  <Input
+                    value={formData.cwd}
+                    onChange={(event) => updateForm('cwd', event.target.value)}
+                    placeholder="."
+                  />
+                </div>
+              )}
+            </div>
+          )}
+
+          {formData.importMode === 'form' && formData.transport !== 'stdio' && (
+            <div>
+              <label className="mb-2 block text-sm font-medium text-foreground">
+                {t('mcpForm.fields.url')} *
+              </label>
+              <Input
+                value={formData.url}
+                onChange={(event) => updateForm('url', event.target.value)}
+                placeholder="https://api.example.com/mcp"
+                type="url"
+                required
+              />
+            </div>
+          )}
+
+          {formData.importMode === 'form' && (
+            <div>
+              <label className="mb-2 block text-sm font-medium text-foreground">
+                {t('mcpForm.fields.envVars')}
+              </label>
+              <textarea
+                value={multilineText.env}
+                onChange={(event) => updateMultilineText('env', event.target.value)}
+                className="w-full rounded-lg border border-gray-300 bg-gray-50 px-3 py-2 text-gray-900 focus:border-blue-500 focus:ring-blue-500 dark:border-gray-600 dark:bg-gray-800 dark:text-gray-100"
+                rows={3}
+                placeholder="API_KEY=your-key&#10;DEBUG=true"
+              />
+            </div>
+          )}
+
+          {formData.importMode === 'form' && supportsHttpHeaders && (
+            <div>
+              <label className="mb-2 block text-sm font-medium text-foreground">
+                {t('mcpForm.fields.headers')}
+              </label>
+              <textarea
+                value={multilineText.headers}
+                onChange={(event) => updateMultilineText('headers', event.target.value)}
+                className="w-full rounded-lg border border-gray-300 bg-gray-50 px-3 py-2 text-gray-900 focus:border-blue-500 focus:ring-blue-500 dark:border-gray-600 dark:bg-gray-800 dark:text-gray-100"
+                rows={3}
+                placeholder="Authorization=Bearer token&#10;X-API-Key=your-key"
+              />
+            </div>
+          )}
+
+          {showCodexOnlyFields && formData.importMode === 'form' && formData.transport === 'stdio' && (
+            <div>
+              <label className="mb-2 block text-sm font-medium text-foreground">
+                Environment Variable Names
+              </label>
+              <textarea
+                value={multilineText.envVars}
+                onChange={(event) => updateMultilineText('envVars', event.target.value)}
+                className="w-full rounded-lg border border-gray-300 bg-gray-50 px-3 py-2 text-gray-900 focus:border-blue-500 focus:ring-blue-500 dark:border-gray-600 dark:bg-gray-800 dark:text-gray-100"
+                rows={3}
+                placeholder="GITHUB_TOKEN&#10;API_KEY"
+              />
+            </div>
+          )}
+
+          {showCodexOnlyFields && formData.importMode === 'form' && formData.transport === 'http' && (
+            <div>
+              <label className="mb-2 block text-sm font-medium text-foreground">
+                Bearer Token Environment Variable
+              </label>
+              <Input
+                value={formData.bearerTokenEnvVar}
+                onChange={(event) => updateForm('bearerTokenEnvVar', event.target.value)}
+                placeholder="MCP_TOKEN"
+              />
+            </div>
+          )}
+
+          <div className="flex justify-end gap-2 pt-4">
+            <Button type="button" variant="outline" onClick={onClose}>
+              {t('mcpForm.actions.cancel')}
+            </Button>
+            <Button
+              type="submit"
+              disabled={isSubmitting || !canSubmit}
+              className="bg-purple-600 text-white hover:bg-purple-700 disabled:opacity-50"
+            >
+              {isSubmitting
+                ? t('mcpForm.actions.saving')
+                : isEditing
+                ? t('mcpForm.actions.updateServer')
+                : addButtonLabel}
+            </Button>
+          </div>
+        </form>
+      </div>
+    </div>
+  );
+}

src/components/mic-button/constants/constants.ts

@@ -1,45 +0,0 @@
-import type { MicButtonState } from '../types/types';
-
-export const MIC_BUTTON_STATES = {
-  IDLE: 'idle',
-  RECORDING: 'recording',
-  TRANSCRIBING: 'transcribing',
-  PROCESSING: 'processing',
-} as const;
-
-export const MIC_TAP_DEBOUNCE_MS = 300;
-export const PROCESSING_STATE_DELAY_MS = 2000;
-
-export const DEFAULT_WHISPER_MODE = 'default';
-
-// Modes that use post-transcription enhancement on the backend.
-export const ENHANCEMENT_WHISPER_MODES = new Set([
-  'prompt',
-  'vibe',
-  'instructions',
-  'architect',
-]);
-
-export const BUTTON_BACKGROUND_BY_STATE: Record<MicButtonState, string> = {
-  idle: '#374151',
-  recording: '#ef4444',
-  transcribing: '#3b82f6',
-  processing: '#a855f7',
-};
-
-export const MIC_ERROR_BY_NAME = {
-  NotAllowedError: 'Microphone access denied. Please allow microphone permissions.',
-  NotFoundError: 'No microphone found. Please check your audio devices.',
-  NotSupportedError: 'Microphone not supported by this browser.',
-  NotReadableError: 'Microphone is being used by another application.',
-} as const;
-
-export const MIC_NOT_AVAILABLE_ERROR =
-  'Microphone access not available. Please use HTTPS or a supported browser.';
-
-export const MIC_NOT_SUPPORTED_ERROR =
-  'Microphone not supported. Please use HTTPS or a modern browser.';
-
-export const MIC_SECURE_CONTEXT_ERROR =
-  'Microphone requires HTTPS. Please use a secure connection.';
-