ai-cli-online 2.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 CLI-Online Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,170 @@
+# AI-Cli Online
+
+[![npm version](https://img.shields.io/npm/v/ai-cli-online.svg)](https://www.npmjs.com/package/ai-cli-online)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D18-green.svg)](https://nodejs.org/)
+
+A lightweight web terminal for accessing Claude Code (or any CLI) from your browser via xterm.js + tmux.
+
+[**中文文档**](README.zh-CN.md)
+
+## Features
+
+- **Full Web Terminal** — xterm.js with WebGL rendering, binary protocol for ultra-low latency
+- **Session Persistence** — tmux keeps processes alive through disconnects; reconnect and resume instantly
+- **Multi-Tab** — independent terminal groups with layout persistence across browser refreshes
+- **Split Panes** — horizontal / vertical splits, arbitrarily nested
+- **Document Browser** — view Markdown, HTML, and PDF files alongside your terminal
+- **Editor Panel** — multi-line editing with server-side draft persistence (SQLite)
+- **File Transfer** — upload files to CWD, browse and download via REST API
+- **Scroll History** — capture-pane scrollback viewer with ANSI color preservation
+- **Session Management** — sidebar to restore, delete, and rename sessions
+- **Font Size Control** — adjustable terminal font size (A−/A+) with server-side persistence
+- **Network Indicator** — real-time RTT latency display with signal bars
+- **Auto Reconnect** — exponential backoff with jitter to prevent thundering herd
+- **Secure Auth** — token authentication with timing-safe comparison
+
+## Comparison: AI-Cli Online vs OpenClaw
+
+| Dimension | AI-Cli Online | OpenClaw |
+|-----------|--------------|----------|
+| **Positioning** | Lightweight web terminal | AI agent orchestration platform |
+| **Core Use Case** | Browser-based remote terminal access | Multi-channel AI assistant |
+| **Terminal Emulation** | xterm.js + WebGL | None |
+| **Session Persistence** | tmux (survives disconnects) | Gateway in-memory state |
+| **Multi-Tab / Split** | Tabs + arbitrarily nested panes | None |
+| **Message Channels** | WebSocket (single channel) | 16+ (WhatsApp / Telegram / Slack / Discord...) |
+| **Native Apps** | None (pure web) | macOS + iOS + Android |
+| **Voice Interaction** | None | Voice Wake + Talk Mode |
+| **AI Agent** | None built-in (run any CLI) | Pi Agent runtime + multi-agent routing |
+| **Canvas / UI** | Document browser (MD / HTML / PDF) | A2UI real-time visual workspace |
+| **File Transfer** | REST API upload / download | Channel-native media |
+| **Security Model** | Token auth + timing-safe | Device pairing + DM policy + Docker sandbox |
+| **Extensibility** | Shell scripts | 33 extensions + 60+ skills + ClawHub |
+| **Transport** | Binary frames (ultra-low latency) | JSON WebSocket |
+| **Deployment** | Single-node Node.js | Single-node + Tailscale Serve/Funnel |
+| **Tech Stack** | React + Express + node-pty | Lit + Express + Pi Agent |
+| **Package Size** | ~12 MB | ~300 MB+ |
+| **Install** | `npx ai-cli-online` | `npm i -g openclaw && openclaw onboard` |
+
+## Quick Start
+
+### Option 1: npx (Recommended)
+
+```bash
+npx ai-cli-online
+```
+
+### Option 2: Global Install
+
+```bash
+npm install -g ai-cli-online
+ai-cli-online
+```
+
+### Option 3: From Source
+
+```bash
+git clone https://github.com/huacheng/ai-cli-online.git
+cd ai-cli-online
+npm install
+npm run build
+npm start
+```
+
+## Prerequisites
+
+- Node.js >= 18
+- tmux installed (`sudo apt install tmux` or `brew install tmux`)
+
+## Configuration
+
+Create `server/.env`:
+
+```env
+PORT=3001                        # Server port
+HOST=0.0.0.0                     # Bind address
+AUTH_TOKEN=your-secret-token     # Auth token (required for production)
+DEFAULT_WORKING_DIR=/home/user   # Default working directory
+HTTPS_ENABLED=true               # Set to false behind nginx reverse proxy
+TRUST_PROXY=1                    # Set to 1 when behind nginx/reverse proxy
+```
+
+See `server/.env.example` for all available options.
+
+## Architecture
+
+```
+Browser (xterm.js + WebGL) <-- WebSocket binary/JSON --> Express (node-pty) <--> tmux session --> shell
+```
+
+- **Frontend**: React + Zustand + xterm.js (WebGL renderer)
+- **Backend**: Node.js + Express + node-pty + WebSocket + better-sqlite3
+- **Session Manager**: tmux (persistent terminal sessions)
+- **Layout System**: Tabs + recursive tree structure (LeafNode / SplitNode)
+- **Transport**: Binary frames (hot path) + JSON (control messages)
+- **Data Persistence**: SQLite (editor drafts)
+
+### Performance
+
+- **Binary protocol** — 1-byte prefix frames for terminal I/O, eliminating JSON overhead
+- **TCP Nagle disabled** — `setNoDelay(true)` removes up to 40 ms keystroke delay
+- **WebSocket compression** — `perMessageDeflate` (level 1, threshold 128 B), 50-70% bandwidth reduction
+- **WebGL renderer** — 3-10x rendering throughput vs canvas
+- **Parallel initialization** — PTY creation, tmux config, and resize run concurrently
+
+## Project Structure
+
+```
+ai-cli-online/
+├── shared/          # Shared type definitions (ClientMessage, ServerMessage)
+├── server/          # Backend (TypeScript)
+│   └── src/
+│       ├── index.ts      # Main entry (HTTP + WebSocket + REST API)
+│       ├── websocket.ts  # WebSocket <-> PTY relay (binary + JSON)
+│       ├── tmux.ts       # tmux session management
+│       ├── files.ts      # File operations
+│       ├── pty.ts        # node-pty wrapper
+│       ├── db.ts         # SQLite database (draft persistence)
+│       ├── auth.ts       # Auth utilities
+│       └── types.ts      # Type definitions
+├── web/             # Frontend (React + Vite)
+│   └── src/
+│       ├── App.tsx        # Main app component
+│       ├── store.ts       # Zustand state management
+│       ├── components/    # UI components
+│       ├── hooks/         # React hooks
+│       └── api/           # API client
+├── start.sh         # Production start script
+└── package.json     # Monorepo config
+```
+
+## Development
+
+```bash
+# Dev mode (frontend + backend separately)
+npm run dev
+
+# Build
+npm run build
+
+# Production (build + start)
+bash start.sh
+```
+
+### systemd Service + nginx Reverse Proxy
+
+```bash
+sudo bash install-service.sh          # Interactive install (systemd + optional nginx)
+sudo systemctl start ai-cli-online    # Start service
+sudo journalctl -u ai-cli-online -f   # View logs
+```
+
+The install script will:
+1. Create a systemd service for auto-start and process management
+2. Detect nginx and optionally configure reverse proxy (WebSocket support, SSL, `client_max_body_size`)
+3. Auto-set `HTTPS_ENABLED=false` and `TRUST_PROXY=1` in `server/.env` when nginx is enabled
+
+## License
+
+MIT

package/README.zh-CN.md

@@ -0,0 +1,170 @@
+# AI-Cli Online
+
+[![npm version](https://img.shields.io/npm/v/ai-cli-online.svg)](https://www.npmjs.com/package/ai-cli-online)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D18-green.svg)](https://nodejs.org/)
+
+轻量级 Web 终端，通过 xterm.js + tmux 在浏览器中访问 Claude Code（或任意 CLI）。
+
+[**English**](README.md)
+
+## 功能特性
+
+- **完整 Web 终端** — xterm.js + WebGL 渲染，二进制协议实现超低延迟
+- **会话持久化** — tmux 保证断网后进程存活，重连即恢复
+- **Tab 多标签页** — 独立终端分组，布局跨刷新持久化
+- **分屏布局** — 水平/垂直任意嵌套分割
+- **文档浏览器** — 终端旁查看 Markdown / HTML / PDF 文件
+- **编辑器面板** — 多行编辑 + 草稿服务端持久化 (SQLite)
+- **文件传输** — 上传文件到 CWD，浏览/下载通过 REST API
+- **滚动历史** — capture-pane 回看，保留 ANSI 颜色
+- **会话管理** — 侧边栏管理 session（恢复/删除/重命名）
+- **字体大小控制** — 可调节终端字体大小 (A−/A+)，设置服务端持久化
+- **网络指示器** — 实时 RTT 延迟显示 + 信号条
+- **自动重连** — 指数退避 + jitter 防雷群效应
+- **安全认证** — Token 认证 + timing-safe 比较
+
+## 功能对比：AI-Cli Online vs OpenClaw
+
+| 维度 | AI-Cli Online | OpenClaw |
+|------|--------------|----------|
+| **定位** | 轻量 Web 终端 | AI Agent 编排平台 |
+| **核心用途** | 浏览器远程终端访问 | 多渠道 AI 助手 |
+| **终端仿真** | xterm.js + WebGL | 无 |
+| **会话持久化** | tmux（断网存活） | Gateway 内存状态 |
+| **多标签/分屏** | Tab + 任意嵌套分屏 | 无 |
+| **消息渠道** | WebSocket 单通道 | 16+（WhatsApp / Telegram / Slack / Discord...） |
+| **原生应用** | 无（纯 Web） | macOS + iOS + Android |
+| **语音交互** | 无 | Voice Wake + Talk Mode |
+| **AI Agent** | 无内置（运行任意 CLI） | Pi Agent 运行时 + 多 Agent 路由 |
+| **Canvas/UI** | 文档浏览器（MD / HTML / PDF） | A2UI 实时可视化工作区 |
+| **文件传输** | REST API 上传/下载 | 渠道原生媒体 |
+| **安全模型** | Token auth + timing-safe | 设备配对 + DM 策略 + Docker 沙箱 |
+| **可扩展性** | Shell 脚本 | 33 扩展 + 60+ Skills + ClawHub |
+| **传输协议** | 二进制帧（超低延迟） | JSON WebSocket |
+| **部署** | 单机 Node.js | 单机 + Tailscale Serve/Funnel |
+| **技术栈** | React + Express + node-pty | Lit + Express + Pi Agent |
+| **包大小** | ~12 MB | ~300 MB+ |
+| **安装** | `npx ai-cli-online` | `npm i -g openclaw && openclaw onboard` |
+
+## 快速开始
+
+### 方式一：npx 一键启动（推荐）
+
+```bash
+npx ai-cli-online
+```
+
+### 方式二：全局安装
+
+```bash
+npm install -g ai-cli-online
+ai-cli-online
+```
+
+### 方式三：从源码运行
+
+```bash
+git clone https://github.com/huacheng/ai-cli-online.git
+cd ai-cli-online
+npm install
+npm run build
+npm start
+```
+
+## 前提条件
+
+- Node.js >= 18
+- tmux 已安装（`sudo apt install tmux` 或 `brew install tmux`）
+
+## 配置
+
+创建 `server/.env`：
+
+```env
+PORT=3001                        # 服务端口
+HOST=0.0.0.0                     # 绑定地址
+AUTH_TOKEN=your-secret-token     # 认证 Token（生产环境必须设置）
+DEFAULT_WORKING_DIR=/home/user   # 默认工作目录
+HTTPS_ENABLED=true               # nginx 反代时设为 false
+TRUST_PROXY=1                    # nginx 反代时设为 1
+```
+
+完整选项参见 `server/.env.example`。
+
+## 架构
+
+```
+浏览器 (xterm.js + WebGL) <-- WebSocket binary/JSON --> Express (node-pty) <--> tmux session --> shell
+```
+
+- **前端**: React + Zustand + xterm.js（WebGL 渲染）
+- **后端**: Node.js + Express + node-pty + WebSocket + better-sqlite3
+- **会话管理**: tmux（持久化终端会话）
+- **布局系统**: Tab 标签页 + 递归树形结构（LeafNode / SplitNode）
+- **传输协议**: 二进制帧（热路径）+ JSON（控制消息）
+- **数据持久化**: SQLite（编辑器草稿）
+
+### 性能优化
+
+- **二进制协议** — 1 字节前缀帧用于终端 I/O，消除 JSON 序列化开销
+- **TCP Nagle 禁用** — `setNoDelay(true)` 消除最多 40 ms 按键延迟
+- **WebSocket 压缩** — `perMessageDeflate`（level 1，threshold 128 B），带宽减少 50-70%
+- **WebGL 渲染器** — 渲染吞吐量提升 3-10 倍
+- **并行初始化** — PTY 创建、tmux 配置、resize 并行执行
+
+## 项目结构
+
+```
+ai-cli-online/
+├── shared/          # 共享类型定义 (ClientMessage, ServerMessage)
+├── server/          # 后端服务 (TypeScript)
+│   └── src/
+│       ├── index.ts      # 主入口 (HTTP + WebSocket + REST API)
+│       ├── websocket.ts  # WebSocket <-> PTY 双向 relay (二进制 + JSON)
+│       ├── tmux.ts       # tmux 会话管理
+│       ├── files.ts      # 文件操作
+│       ├── pty.ts        # node-pty 封装
+│       ├── db.ts         # SQLite 数据库 (草稿持久化)
+│       ├── auth.ts       # 认证工具
+│       └── types.ts      # 类型定义
+├── web/             # 前端应用 (React + Vite)
+│   └── src/
+│       ├── App.tsx        # 主应用组件
+│       ├── store.ts       # Zustand 状态管理
+│       ├── components/    # UI 组件
+│       ├── hooks/         # React Hooks
+│       └── api/           # API 客户端
+├── start.sh         # 生产启动脚本
+└── package.json     # Monorepo 配置
+```
+
+## 开发
+
+```bash
+# 开发模式（前后端分离）
+npm run dev
+
+# 构建
+npm run build
+
+# 生产模式（构建 + 启动）
+bash start.sh
+```
+
+### systemd 服务 + nginx 反向代理
+
+```bash
+sudo bash install-service.sh             # 交互安装 (systemd + 可选 nginx 反代)
+sudo systemctl start ai-cli-online       # 启动服务
+sudo journalctl -u ai-cli-online -f      # 查看日志
+```
+
+安装脚本会：
+1. 创建 systemd 服务，支持开机自启和进程管理
+2. 检测 nginx 并可选配置反向代理（WebSocket 支持、SSL、`client_max_body_size`）
+3. nginx 启用时自动设置 `HTTPS_ENABLED=false` 和 `TRUST_PROXY=1`
+
+## License
+
+MIT

package/bin/ai-cli-online.mjs

@@ -0,0 +1,89 @@
+#!/usr/bin/env node
+
+import { execFileSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const rootDir = join(__dirname, '..');
+
+// Read version from package.json
+const require = createRequire(import.meta.url);
+const pkg = require(join(rootDir, 'package.json'));
+
+const args = process.argv.slice(2);
+
+// --version
+if (args.includes('--version') || args.includes('-v')) {
+  console.log(pkg.version);
+  process.exit(0);
+}
+
+// --help
+if (args.includes('--help') || args.includes('-h')) {
+  console.log(`
+ai-cli-online v${pkg.version} — Web Terminal for Claude Code
+
+Usage:
+  ai-cli-online            Start the server
+  ai-cli-online --help     Show this help
+  ai-cli-online --version  Show version
+
+Environment variables (or server/.env):
+  PORT                  Server port (default: 3001)
+  HOST                  Bind address (default: 0.0.0.0)
+  AUTH_TOKEN            Authentication token (required for production)
+  HTTPS_ENABLED         Enable HTTPS (default: true)
+  DEFAULT_WORKING_DIR   Default working directory
+
+Prerequisites:
+  - Node.js >= 18
+  - tmux installed (sudo apt install tmux)
+
+More info: ${pkg.homepage || 'https://github.com/huacheng/ai-cli-online'}
+`.trim());
+  process.exit(0);
+}
+
+// Check Node.js version
+const nodeVersion = parseInt(process.versions.node.split('.')[0], 10);
+if (nodeVersion < 18) {
+  console.error(`Error: Node.js >= 18 is required (current: ${process.versions.node})`);
+  process.exit(1);
+}
+
+// Check tmux
+try {
+  execFileSync('tmux', ['-V'], { stdio: 'pipe' });
+} catch {
+  console.error('Error: tmux is not installed.');
+  console.error('Install it with: sudo apt install tmux (Debian/Ubuntu) or brew install tmux (macOS)');
+  process.exit(1);
+}
+
+// Check if built
+const serverEntry = join(rootDir, 'server', 'dist', 'index.js');
+if (!existsSync(serverEntry)) {
+  console.error('Error: Server not built. Run "npm run build" first.');
+  process.exit(1);
+}
+
+// Start server
+const { fork } = await import('node:child_process');
+const child = fork(serverEntry, [], {
+  cwd: join(rootDir, 'server'),
+  stdio: 'inherit',
+});
+
+child.on('exit', (code) => {
+  process.exit(code ?? 0);
+});
+
+// Forward signals
+for (const signal of ['SIGINT', 'SIGTERM']) {
+  process.on(signal, () => {
+    child.kill(signal);
+  });
+}