# HStudio Web CLI

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

## Quick Start

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

# Start the editor (default port 8181)
hstudio

# Or specify custom port
hstudio --port 8080 --cwd /path/to/project
```

Browser will automatically open http://localhost:8181

## Architecture

HStudio Web uses a **single-port architecture**:

```
┌─────────────────────────────────────────────────────────┐
│                    Browser (Vue3)                        │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐  │
│  │   Editor    │    │   Terminal  │    │  AI Panel   │  │
│  └─────────────┘    └─────────────┘    └─────────────┘  │
└──────────────────────────┬──────────────────────────────┘
                           │
         http://localhost:PORT (same port)
                           │
┌──────────────────────────┼──────────────────────────────┐
│              Node.js Server (Express + WebSocket)        │
│  ┌─────────────┐    ┌────┴────────┐    ┌─────────────┐  │
│  │ Static Files│    │  WebSocket  │    │  API Routes │  │
│  │  (web/)     │    │   (/ws)     │    │  (/health)  │  │
│  └─────────────┘    └─────────────┘    └─────────────┘  │
│                           │                              │
│  ┌─────────────┐    ┌────┴────────┐    ┌─────────────┐  │
│  │  PTY Terminal    │ File System │    │ Git/AI/CLI  │  │
│  └─────────────┘    └─────────────┘    └─────────────┘  │
└─────────────────────────────────────────────────────────┘
```

- **Frontend**: Served as static files by Express on the same port
- **WebSocket**: Real-time communication via `/ws` endpoint
- **Backend**: All operations (file system, terminal, AI) handled by Node.js server

## Installation

```bash
npm install -g hstudio-web-cli
```

## Usage

### Global CLI Commands

```bash
# 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

# Show help
hstudio --help
```

### Legacy Command (Alias)

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

```bash
hcli-web --port 3000 --cwd /path/to/project
```

### Local Development Mode

```bash
cd npm-web-dist

# Default start (port 8181)
npm start

# With options
npm start -- --port 3000 --cwd /path/to/project
```

## Options

| Option | Description | Default |
|--------|-------------|---------|
| `--port <number>` | Server port (frontend + backend + WebSocket) | 8181 |
| `--cwd <path>` | Working directory for file operations | Current directory |
| `--no-open` | Don't auto-open browser | false |
| `--help, -h` | Show help message | - |

## Features

- **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)

## 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

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

## Browser Support

Works in modern browsers:
- Chrome 90+
- Firefox 90+
- Safari 14+
- Edge 90+

## Troubleshooting

### Port already in use
```bash
# Use a different port
hstudio --port 3000
```

### 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

## License

MIT

## Author

wuhaihao
