[feat:global] terminal mode and unit testing

.env.example

@@ -1,6 +1,3 @@
-# Anthropic API key for billing usage stats (optional — local logs work without it)
-ANTHROPIC_API_KEY=
-
 # Path to the claude binary (defaults to claude from PATH)
 CLAUDE_BIN=claude
 

.github/workflows/claude-code-webui-ci.yml

@@ -42,3 +42,11 @@ jobs:
       - name: Build backend
         working-directory: backend
         run: npm run build
+
+      - name: Test backend
+        working-directory: backend
+        run: npm test
+
+      - name: Test frontend
+        working-directory: frontend
+        run: npm test

CLAUDE.md

@@ -43,7 +43,6 @@ cp .env.example backend/.env
 
 | Variable | Default | Description |
 |---|---|---|
-| `ANTHROPIC_API_KEY` | — | Optional; enables billing data in Usage view |
 | `CLAUDE_BIN` | `claude` | Path to the `claude` binary |
 | `PORT` | `9998` | Backend listen port |
 | `HOST` | `0.0.0.0` | Backend listen address |
@@ -69,22 +68,30 @@ The Makefile's `dev-backend` target and `run.sh` both conditionally set `NODE_EX
 | Method | Path | Handler | Description |
 |---|---|---|---|
 | GET | `/api/account` | `routes/account.ts` | Account info + claude version |
-| GET | `/api/usage` | `routes/usage.ts` | Usage stats (local logs + optional billing API) |
+| GET | `/api/usage` | `routes/usage.ts` | Usage stats (local logs) |
 | GET/POST | `/api/sessions` | `routes/sessions.ts` | List sessions, create session |
 | POST | `/api/sessions/:id/stop` | `routes/sessions.ts` | Stop active session |
 | GET/POST | `/api/settings` | `routes/settings.ts` | Persistent key-value settings (SQLite-backed) |
 | GET | `/health` | `server.ts` | Health check |
-| WS | `/ws/session/:id` | `ws/session.ts` | PTY I/O over WebSocket |
+| WS | `/ws/session/:id` | `ws/session.ts` | Chat PTY I/O over WebSocket |
+| WS | `/ws/terminal/:id` | `ws/terminal.ts` | Terminal PTY I/O over WebSocket |
+| DELETE | `/api/sessions/:id` | `routes/sessions.ts` | Delete session (DB + `~/.claude/projects/` file) |
 
 ### Settings route
 
-`routes/settings.ts` stores app settings in the SQLite `settings` table. Currently the only key is `bypass_permissions` (default `true`). Only keys in the `ALLOWED` set are accepted — add new keys there before using them.
+`routes/settings.ts` stores app settings in the SQLite `settings` table. Keys: `bypass_permissions` (default `true`) and `session_mode` (default `'terminal'`). Only keys in the `ALLOWED` set are accepted — add new keys there before using them.
+
+### Session modes
+
+Two modes are supported per session, stored in the `sessions.mode` column:
+- **`chat`** — structured JSON streaming via `/ws/session/:id`; messages stored in `messages` table
+- **`terminal`** — raw PTY via `/ws/terminal/:id`; scrollback persisted in `sessions.terminal_scrollback` (256 KB circular buffer, flushed to SQLite on activity with a 500 ms debounce)
 
 ### Frontend data flow
 
 - `useDashboard.ts` fetches account + usage + sessions in parallel with a 60s auto-refresh
-- `SessionContext.tsx` holds the active session state; `useWebSocket.ts` manages the WS connection with exponential-backoff reconnect
-- `TerminalDrawer.tsx` wraps xterm.js and is **never unmounted** — it is CSS-toggled (display: none) to preserve terminal state across view switches
+- `SessionContext.tsx` holds the active session state (including `mode`); `useWebSocket.ts` manages the chat WS connection; `useTerminalSession.ts` manages the terminal WS connection
+- `TerminalSession.tsx` and `TerminalDrawer.tsx` are **never unmounted** — both are CSS-toggled (`display: none`) to preserve xterm scroll buffer across navigation
 
 ### Syntax highlighting
 
@@ -102,7 +109,7 @@ docker-compose up
 # Dashboard at http://localhost:8080
 ```
 
-`docker-compose.yml` mounts `~/.claude` (read-only) and `~/projects` (read-write) from the host.
+`docker-compose.yml` mounts `~/.claude` (read-write — required for session deletion) and `~/projects` (read-write) from the host.
 
 ## Systemd service (Linux)
 

Makefile

@@ -1,4 +1,4 @@
-.PHONY: dev dev-backend dev-frontend build lint install clean run service-install service-uninstall service-test
+.PHONY: dev dev-backend dev-frontend build lint test install clean run service-install service-uninstall service-test
 
 # Fedora / RHEL hosts lack the Google Trust Services intermediate CA that
 # Anthropic's API uses.  Set NODE_EXTRA_CA_CERTS only when the bundle exists
@@ -23,6 +23,10 @@ lint:
 	cd backend && npm run lint
 	cd frontend && npm run lint
 
+test:
+	cd backend && npm test
+	cd frontend && npm test
+
 install:
 	cd backend && npm install
 	cd frontend && npm install

README.md

@@ -4,16 +4,16 @@
 [![Docker](https://img.shields.io/badge/docker-ghcr.io-blue)](https://github.com/adeotek/claude-code-webui/pkgs/container/claude-code-webui)
 [![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
 
-A browser-based UI for [Claude Code](https://claude.ai/code) — manage sessions, track token usage, and chat with Claude from any device on your network.
+A browser-based UI for [Claude Code](https://claude.ai/code) — manage sessions, track token usage, and interact with Claude from any device on your network.
 
 ## Features
 
 - **Session management** — create, resume, rename, and delete Claude Code sessions
-- **Real-time chat** — markdown rendering with syntax-highlighted code blocks
-- **Terminal drawer** — integrated xterm.js terminal that persists across view switches
-- **Usage dashboard** — daily token usage graph with optional Anthropic billing data
+- **Terminal mode** — full interactive xterm.js terminal connected directly to Claude Code (default)
+- **Chat mode** — structured message view with markdown rendering and syntax-highlighted code blocks
+- **Usage dashboard** — daily token usage graph
 - **Account overview** — Claude version, authentication status, and model info
-- **Persistent history** — session messages and token counts stored in SQLite
+- **Persistent history** — session messages, token counts, and terminal scrollback stored in SQLite
 
 ## Quick Start
 
@@ -55,7 +55,7 @@ docker-compose up
 
 Open **http://localhost:8080**.
 
-`docker-compose.yml` mounts `~/.claude` (read-only) and `~/projects` (read-write) from the host. To build the image locally instead of pulling from the registry:
+`docker-compose.yml` mounts `~/.claude` (read-write — required for session deletion) and `~/projects` (read-write) from the host. To build the image locally instead of pulling from the registry:
 
 ```bash
 docker build -t claude-code-webui .
@@ -72,7 +72,6 @@ cp .env.example backend/.env
 
 | Variable | Default | Description |
 |---|---|---|
-| `ANTHROPIC_API_KEY` | — | Optional — enables billing data in the Usage view |
 | `CLAUDE_BIN` | `claude` | Path to the `claude` binary |
 | `PORT` | `9998` | Backend listen port |
 | `HOST` | `0.0.0.0` | Backend listen address |