Files

vigdorov 4a91896732 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

3.4 KiB

Raw Blame History

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 | Требования: 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`)

Запуск

npm install
npm start

Dev-порт: нет (только исходящие соединения, подключается к серверу)

Связь с simple-chat

Бэкенд: модуль agent-proxy (WebSocket gateway, REST API, бинарный протокол PTY ввода/вывода)
Фронтенд: маршрут /agent с терминалом xterm.js, управление чатами/сессиями
БД: таблица agent_devices + agent-поля в таблице chats

3.4 KiB Raw Blame History Unescape Escape