feat: xterm.js + node-pty architecture for Claude CLI web terminal

Complete rewrite from tmux + JSONL parsing to a clean PTY-based approach. The proxy spawns Claude CLI in a pseudo-terminal via node-pty and relays terminal I/O as binary WebSocket frames to the simple-chat backend, which forwards them to the browser where xterm.js renders a full terminal. - node-pty PTY manager with 50KB replay buffer per session - Binary frame protocol with chatId multiplexing - WebSocket client with auto-reconnection and heartbeat - Directory listing and session listing for the web UI - README with setup instructions Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-22 00:24:29 +03:00
commit 4a91896732
17 changed files with 6146 additions and 0 deletions
--- a/CLAUDE.md
+++ b/CLAUDE.md
@ -0,0 +1,73 @@
+# Claude CLI Proxy — Веб-клиент для Claude Code CLI
+
+## Назначение
+
+Локальное приложение, которое подключает Claude Code CLI к веб-интерфейсу simple-chat. Управляет PTY-процессами (node-pty), транслирует ввод/вывод терминала через WebSocket. Фронтенд отображает терминал через xterm.js.
+
+**Это локальное приложение.** Запускается на машине разработчика, не деплоится в k3s.
+
+## Статус
+
+Активная разработка. Работает в связке с simple-chat (модуль agent-proxy).
+
+## Архитектура
+
+```
+simple-chat (frontend)          simple-chat (backend)          claude-cli-proxy (local)
+   xterm.js terminal  ←─WS─→  agent-proxy gateway  ←──WS──→  PtyManager
+                                    │                              │
+                                    │                         node-pty processes
+                                    │                           ├── claude (chat 1)
+                                    │                           ├── claude --resume <id> (chat 2)
+                                    │                           └── ...
+                                    │
+                               REST API + DB (agent_devices, chats)
+```
+
+Подробности: [ARCHITECTURE.md](ARCHITECTURE.md) | Требования: [REQUIREMENTS.md](REQUIREMENTS.md)
+
+## Технологический стек
+
+| Компонент | Технология |
+|-----------|-----------|
+| Runtime | Node.js + TypeScript |
+| WebSocket | ws |
+| PTY | node-pty |
+| Frontend terminal | xterm.js (в simple-chat) |
+| Запуск | `npm start` → `tsx src/main.ts` |
+| Общие конфиги | @vigdorov/eslint-config (node), @vigdorov/prettier-config, @vigdorov/typescript-config (node) |
+
+## Структура
+
+```
+src/
+├── main.ts                 # Точка входа, класс ClaudeCliProxy
+├── config.ts               # Загрузка .env (PROXY_TOKEN, SERVER_URL)
+├── connection/
+│   ├── ws-client.ts        # WebSocket-клиент с переподключением
+│   └── protocol.ts         # Типы WS-сообщений, бинарный протокол (общие с бэкендом)
+└── pty/
+    └── manager.ts          # Создание/удаление/resize PTY-процессов через node-pty
+```
+
+## Конфигурация (.env)
+
+| Переменная | Описание |
+|-----------|----------|
+| `PROXY_TOKEN` | Токен авторизации (из настроек simple-chat) |
+| `SERVER_URL` | WebSocket URL бэкенда (`ws://localhost:3000/ws/agent-proxy` или `wss://ai-chat.vigdorov.ru/ws/agent-proxy`) |
+
+## Запуск
+
+```bash
+npm install
+npm start
+```
+
+## Dev-порт: нет (только исходящие соединения, подключается к серверу)
+
+## Связь с simple-chat
+
+- Бэкенд: модуль `agent-proxy` (WebSocket gateway, REST API, бинарный протокол PTY ввода/вывода)
+- Фронтенд: маршрут `/agent` с терминалом xterm.js, управление чатами/сессиями
+- БД: таблица `agent_devices` + agent-поля в таблице `chats`