ai-cli-online

AI-Cli Online

An AI-powered development environment that runs in your browser. Persistent terminal sessions, structured task lifecycle, and autonomous execution — all through a single Node.js process.

Built for running Claude Code, Codex CLI, Gemini CLI, or any other AI CLI over unstable networks. tmux keeps everything alive when connections drop; the browser UI provides planning, annotation, and chat panels alongside the terminal.

npm: https://www.npmjs.com/package/ai-cli-online | GitHub: https://github.com/huacheng/ai-cli-online

中文文档

What It Does

Terminal + Planning + Execution in one screen:

┌─ Tabs ──────────────────────────────────────────────────────┐
│ ┌─ Plan Panel ──────┬─ Terminal ────────────────────────┐   │
│ │ AiTasks/ browser   │                                   │   │
│ │ Markdown viewer    │  $ /ai-cli-task auto my-feature   │   │
│ │ Inline annotations │  ▶ planning...                    │   │
│ │ (insert/delete/    │  ▶ check(post-plan): PASS         │   │
│ │  replace/comment)  │  ▶ executing step 1/4...          │   │
│ │                    │  ▶ executing step 2/4...          │   │
│ │ Mermaid diagrams   │  ...                              │   │
│ │                    ├───────────────────────────────────┤   │
│ │                    │ Chat Editor                        │   │
│ │                    │ Multi-line Markdown + /commands    │   │
│ └────────────────────┴───────────────────────────────────┘   │
└──────────────────────────────────────────────────────────────┘

• Plan Panel — browse AiTasks/ files, annotate documents with 4 annotation types, send structured feedback to AI
• Terminal — full xterm.js with WebGL rendering, binary protocol for ultra-low latency
• Chat Editor — multi-line Markdown editor with slash commands, server-side draft persistence
• All three panels can be open simultaneously, each independently resizable

AI Task Lifecycle

The ai-cli-task plugin provides an 8-skill lifecycle for structured AI task execution:

init → plan → check → exec → check → merge → report
                ↑        ↓
              re-plan ←──┘ (on issues)

Skill	What it does
init	Create task module (AiTasks/<name>/), git branch, optional worktree
plan	Generate implementation plan or process human annotations
check	Evaluate feasibility at 3 checkpoints (post-plan / mid-exec / post-exec)
exec	Execute plan steps with per-step verification
merge	Merge task branch to main with conflict resolution (up to 3 retries)
report	Generate completion report, distill lessons to experience database
auto	Run the full lifecycle autonomously in a single Claude session
cancel	Stop execution, set status to cancelled, optional cleanup

Auto Mode

/ai-cli-task auto my-feature

One command triggers the entire lifecycle. A single Claude session runs plan → check → exec → merge → report internally, sharing context across all steps. A daemon monitors progress via .auto-signal files, enforces timeouts, and detects stalls.

Task Structure

AiTasks/
├── .index.json                  # Module listing
├── .experiences/                # Cross-task knowledge base (by domain type)
│   ├── .summary.md              # Experience file index
│   └── <type>.md
├── .references/                 # External reference materials (collected during plan/exec)
│   ├── .summary.md              # Reference file index
│   └── <topic>.md
└── my-feature/
    ├── .index.json              # Status, phase, timestamps, dependencies (JSON)
    ├── .target.md               # Requirements (human-authored)
    ├── .summary.md              # Condensed context (prevents context overflow)
    ├── .analysis/               # Evaluation history
    ├── .test/                   # Test criteria & results
    ├── .bugfix/                 # Issue history
    ├── .notes/                  # Research findings
    ├── .report.md               # Completion report
    └── .plan.md                 # Implementation plan

Type-Aware Execution

Tasks are classified by domain type (software, dsp, ml, literary, science:physics, etc.). Each type adapts planning methodology, execution tools, and verification criteria. Completed task lessons are stored in .experiences/<type>.md and referenced by future tasks of the same type.

Terminal Features

• Session Persistence — tmux keeps processes alive through disconnects; fixed socket path ensures auto-reconnect after server restarts
• Multi-Tab — independent terminal groups with layout persistence across refreshes
• Split Panes — horizontal / vertical splits, arbitrarily nested
• Binary Protocol — 1-byte prefix frames for terminal I/O, TCP Nagle disabled, WebSocket compression
• WebGL Rendering — 3-10x throughput vs canvas
• Copy & Paste — mouse selection auto-copies; right-click pastes
• Scroll History — capture-pane scrollback with ANSI color preservation
• File Transfer — upload/download files, browse directories, download CWD as tar.gz
• Network Indicator — real-time RTT latency with signal bars
• Auto Reconnect — exponential backoff with jitter

Annotation System

The Plan panel provides 4 annotation types for structured AI feedback:

Type	Icon	Description
Insert	+	Add content at a specific location
Delete	−	Mark text for removal
Replace	↔	Substitute old text with new
Comment	?	Ask questions or leave notes

Annotations are persisted (localStorage + SQLite) and sent to the AI as structured JSON. The plan skill processes them — triaging by impact, applying changes, and updating task files.

Quick Start

Option 1: npx (Recommended)

npx ai-cli-online

Option 2: Global Install

npm install -g ai-cli-online
ai-cli-online

Option 3: From Source

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:

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)
  ├── Plan Panel (annotation editor)
  ├── Chat Editor (Markdown + /commands)
  └── Terminal View (WebGL renderer)
        │
        ↕ WebSocket binary/JSON + REST API
        │
Express Server (Node.js)
  ├── WebSocket ↔ PTY relay
  ├── tmux session manager
  ├── File transfer API
  ├── SQLite (drafts, annotations, settings)
  └── Route modules (sessions, files, editor, settings)
        │
        ↕ PTY / tmux sockets
        │
tmux sessions → shell → Claude Code / AI agents
  └── AiTasks/ lifecycle (init/plan/check/exec/merge/report/auto)

• Frontend: React + Zustand + xterm.js (WebGL)
• Backend: Node.js + Express + node-pty + WebSocket + better-sqlite3
• Session Manager: tmux (persistent terminal sessions)
• Layout: Tabs + recursive split tree (LeafNode / SplitNode)
• Transport: Binary frames (hot path) + JSON (control messages)
• Task System: 8-skill plugin with state machine, dependency gates, and experience database

Project Structure

ai-cli-online/
├── shared/              # Shared type definitions
├── server/src/
│   ├── index.ts         # Main entry (middleware + routes + server)
│   ├── websocket.ts     # WebSocket ↔ PTY relay (binary + JSON)
│   ├── tmux.ts          # tmux session management
│   ├── files.ts         # File operations + path validation
│   ├── pty.ts           # node-pty wrapper
│   ├── db.ts            # SQLite database
│   ├── auth.ts          # Auth utilities
│   ├── middleware/       # Auth middleware
│   └── routes/          # REST API routes (sessions, files, editor, settings)
├── web/src/
│   ├── App.tsx           # Main app (Login / TabBar / Terminal / Theme)
│   ├── store/            # Zustand store (modular slices)
│   ├── components/
│   │   ├── TerminalPane.tsx              # 2D grid layout (Plan + Terminal + Chat)
│   │   ├── TerminalView.tsx              # xterm.js terminal
│   │   ├── PlanPanel.tsx                 # Plan annotation panel
│   │   ├── PlanAnnotationRenderer.tsx    # Markdown + inline annotations
│   │   ├── PlanFileBrowser.tsx           # AiTasks/ file browser
│   │   ├── MarkdownEditor.tsx            # Chat editor
│   │   └── ...
│   ├── hooks/            # React hooks (WebSocket, file stream, resize, etc.)
│   └── api/              # Typed API client modules
├── bin/                  # npx entry point
├── start.sh              # Production start script
└── install-service.sh    # systemd + nginx installer

Development

# Dev mode (frontend + backend separately)
npm run dev

# Build
npm run build

# Production (build + start)
bash start.sh

systemd Service + nginx Reverse Proxy

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:

• Create a systemd service for auto-start and process management
• Detect nginx and optionally configure reverse proxy (WebSocket support, SSL, client_max_body_size)
• Auto-set HTTPS_ENABLED=false and TRUST_PROXY=1 in server/.env when nginx is enabled

Security

• Token authentication with timing-safe comparison
• Symlink traversal protection on all file operations
• Unauthenticated WebSocket connection limits
• TOCTOU download guard (streaming size check)
• CSP headers (frame-ancestors, base-uri, form-action)
• Rate limiting (configurable read/write thresholds)

License

MIT