HStudio Web CLI

Browser-based IDE with ClaudeCode integration. Launch from command line using hstudio.

Also includes Admin Dashboard for managing AI Studio backend.

Quick Start

# Install globally
npm install -g hstudio-web-cli

# Start the IDE editor (default port 8181)
hstudio

# Start the Admin Dashboard (default port 9191)
hstudio --admin

# Or specify custom port
hstudio --port 8080 --cwd /path/to/project
hstudio --admin --port 9200 --api-target http://localhost:9000

Browser will automatically open.

Architecture

HStudio Web uses a single-port architecture for each mode:

┌─────────────────────────────────────────────────────────┐
│                    Browser (Vue3)                        │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐  │
│  │   Editor    │    │   Terminal  │    │  AI Panel   │  │
│  └─────────────┘    └─────────────┘    └─────────────┘  │
└──────────────────────────┬──────────────────────────────┘
                           │
         http://localhost:8181 (IDE mode)
         http://localhost:9191 (Admin mode)
                           │
┌──────────────────────────┼──────────────────────────────┐
│              Node.js Server (Express + WebSocket)        │
│                                                          │
│  IDE Mode (port 8181):                                   │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐  │
│  │ Static Files│    │  WebSocket  │    │  PTY Terminal│ │
│  │  (web/)     │    │   (/ws)     │    │  File System │ │
│  └─────────────┘    └─────────────┘    └─────────────┘  │
│                                                          │
│  Admin Mode (port 9191):                                 │
│  ┌─────────────┐    ┌─────────────┐                      │
│  │ Static Files│    │ API Proxy   │                      │
│  │  (admin/)   │    │ (/aiApi)    │                      │
│  └─────────────┘    └─────────────┘                      │
└─────────────────────────────────────────────────────────┘

Directory Structure

npm-web-dist/
├── bin/hcli-web.js      # CLI 入口
├── server/              # IDE 后端服务 (~2 MB)
├── web/                 # IDE 前端 (~30 MB)
├── adminServer/         # Admin 后端服务 (~1 MB)
├── admin/               # Admin 前端 (~3 MB)
├── package.json
└── README.md

Installation

npm install -g hstudio-web-cli

Usage

IDE Mode

# Default start (port 8181, current directory)
hstudio

# Custom port
hstudio --port 3000

# Specify working directory
hstudio --cwd /path/to/project

# Don't auto-open browser
hstudio --no-open

Admin Mode

# Start admin dashboard (port 9191)
hstudio --admin

# Custom port and API target
hstudio --admin --port 9200 --api-target http://localhost:9000

# Don't auto-open browser
hstudio --admin --no-open

Legacy Command (Alias)

hcli-web is also available as an alias for backward compatibility:

hcli-web --port 3000 --cwd /path/to/project
hcli-web --admin --api-target http://localhost:9000

Local Development Mode

cd npm-web-dist

# IDE mode (port 8181)
npm start

# Admin mode (port 9191)
npm start -- --admin

# With options
npm start -- --port 3000 --cwd /path/to/project
npm start -- --admin --api-target http://localhost:9000

Options

| Option | Description | Default | |--------|-------------|---------| | --port <number> | Server port | IDE: 8181, Admin: 9191 | | --cwd <path> | Working directory for file operations | Current directory | | --admin | Launch admin dashboard instead of IDE | false | | --api-target <url> | Backend API server URL (for admin mode) | http://xxx.xxx.xxx.xxx:9000 | | --no-open | Don't auto-open browser | false | | --help, -h | Show help message | - | | --version, -v | Show version number | - |

Environment Variables

| Variable | Description | Default | |----------|-------------|---------| | API_TARGET | Backend API server URL (same as --api-target) | http://xxx.xxx.xxx.xxx:9000 |

Features

IDE Mode

• File Management: Browse, edit, create files and directories
• Terminal: Full terminal support with PTY (bash, zsh, etc.)
• Project Launch: Run npm run dev and preview in browser
• AI Integration: Claude Code and Gemini CLI support
• Git Integration: Status, commit, push, pull, branch management
• Settings: Persistent settings across sessions
• Dual Mode: IDE mode (with file tree) and Solo mode (terminal only)

Admin Mode

• User Management: View and manage users
• Project Management: Track statistics and analytics
• Dashboard: Visual charts with ECharts
• API Proxy: All /aiApi requests proxied to backend server

Requirements

• Node.js >= 18
• Claude CLI (optional): npm install -g @anthropic-ai/claude-code
• Gemini CLI (optional): npm install -g @google/gemini-cli

API Endpoints

IDE Mode

• GET / - Web IDE frontend (index.html)
• GET /health - Health check, returns {status: "ok", version: "..."}
• WS /ws - WebSocket connection for all operations

Admin Mode

• GET / - Admin dashboard frontend
• GET /aiApi/* - Proxied to backend API server

Build

在 aiStudio 目录执行：

npm run dist:web

会依次执行：

1. 构建 IDE 前端 (vite)
2. 构建 IDE 后端 (tsc)
3. 复制 server 到 npm-web-dist
4. 构建 Admin 前端和后端

Browser Support

Works in modern browsers:

• Chrome 90+
• Firefox 90+
• Safari 14+
• Edge 90+

Troubleshooting

Port already in use

# Use a different port
hstudio --port 3000
hstudio --admin --port 9200

WebSocket connection failed

• Check if server is running: curl http://localhost:8181/health
• Check WebSocket URL in browser console

Terminal not working

• Ensure node-pty is installed correctly
• Check if bash/zsh is available on your system

File operations failed

• Check directory permissions for --cwd path
• Ensure you're running server with correct cwd

Admin API proxy failed

• Check if backend server is running
• Verify --api-target URL is correct
• Check backend server logs

License

MIT

Author

wuhaihao