WinTerm Bridge

中文文档 | English

WinTerm Bridge is a lightweight web-based terminal that connects your browser to tmux sessions over WebSocket. Access your terminal from anywhere - desktop or mobile.

Features

• One-Line Install - Get started in seconds with a single command
• Interactive Setup - Configure port, PIN, and command name during installation
• Web-Based Terminal - Full terminal emulation powered by xterm.js
• tmux Integration - Seamlessly manage and connect to tmux sessions
• AI Session Monitor - LLM-powered terminal analysis with status tags (supports OpenAI-compatible APIs)
• AI Auto-Reply - Intelligent automatic responses to terminal prompts with safety controls
• Workflow Logging - Per-session event logs for debugging and auditing AI actions
• Email Notifications - Get alerts when sessions need input or complete tasks
• OSC 52 Clipboard - Copy selected text directly to system clipboard via tmux
• Mobile Friendly - Responsive UI with workflow logs, AI status display, and touch support
• Secure Access - PIN-based authentication (6-12 alphanumeric) with JWT tokens
• Session Persistence - Mark sessions to survive server restarts
• Auto-Start Service - Service starts automatically when you run hiwb
• Cross-Platform - Works on Linux, WSL, and macOS

Quick Start

One-Line Install

# Download and run interactively (recommended)
curl -fsSL https://raw.githubusercontent.com/Cucgua/winterm-bridge/main/scripts/install.sh -o install.sh && bash install.sh

# Or with default settings (non-interactive)
curl -fsSL https://raw.githubusercontent.com/Cucgua/winterm-bridge/main/scripts/install.sh | bash

Install Options

--cmd-name NAME    # Custom command name (default: hiwb)
--port PORT        # Service port (default: 8345)
--pin PIN          # Access PIN code (default: 123456)
--install-dir DIR  # Install directory (default: /usr/local/bin)
--from-source      # Build from source instead of downloading binary
--version VERSION  # Specific version (default: latest)
--no-service       # Skip systemd service installation

Example

curl -fsSL https://raw.githubusercontent.com/Cucgua/winterm-bridge/main/scripts/install.sh | bash -s -- \
  --cmd-name wb \
  --port 9000 \
  --pin 888888

Usage

CLI Commands

Note: hiwb is the default command name. You can customize it during installation with --cmd-name. All examples below use the default name.

# Enter terminal (auto-starts service if not running)
hiwb

# Enter with custom session name
hiwb myproject

# List all sessions
hiwb -l

# Show service status
hiwb -i

# Service management
hiwb -s    # start
hiwb -S    # stop
hiwb -r    # restart

# Kill a session
hiwb -k myproject

# Uninstall
hiwb --uninstall

# Show help
hiwb -h

Command Reference

Command	Description
hiwb	Enter terminal (auto-starts service)
hiwb <name>	Create/connect to named session
hiwb -l	List all winterm sessions
hiwb -i	Show service status and connection info
hiwb -s	Start service
hiwb -S	Stop service
hiwb -r	Restart service
hiwb -k <name>	Kill specified session
hiwb --uninstall	Uninstall (prompts to keep config)
hiwb -h	Show help

Web Access

1. Run hiwb to start the service and enter terminal
2. Open the URL shown in the terminal (e.g., http://192.168.1.100:8345)
3. Enter the PIN code
4. Select a session or create a new one

Platform Support

Platform	Status	Notes
Linux (x64)	✅	Full support
Linux (ARM64)	✅	Raspberry Pi, etc.
WSL2	✅	Recommended for Windows users
macOS (Intel)	✅	Full support
macOS (Apple Silicon)	✅	Full support

Architecture

┌─────────────────┐      WebSocket       ┌─────────────────┐
│                 │  ◄─────────────────► │                 │
│  Browser        │                      │  WinTerm Bridge │
│  (xterm.js)     │      REST API        │  (Go Server)    │
│                 │  ◄─────────────────► │                 │
└─────────────────┘                      └────────┬────────┘
                                                  │ PTY
                                                  ▼
                                         ┌─────────────────┐
                                         │      tmux       │
                                         │    sessions     │
                                         └─────────────────┘

Configuration

Configuration files are located in ~/.config/winterm-bridge/:

~/.config/winterm-bridge/
├── runtime.json     # Runtime config (port, PIN, AI, Email, etc.)
├── tmux.conf        # tmux configuration
├── fonts/           # Custom fonts directory
└── server.log       # Service log

AI Monitor Configuration

The AI Monitor uses LLM to analyze terminal output and provide status tags. Configure it via Web UI or directly in runtime.json:

{
  "ai_monitor": {
    "enabled": true,
    "endpoint": "https://dashscope.aliyuncs.com/compatible-mode/v1",
    "api_key": "sk-xxx",
    "model": "qwen-turbo",
    "lines": 50,
    "interval": 30,
    "extra_params": "{\"max_tokens\": 500}"
  }
}

Field	Description	Default
enabled	Enable AI monitoring	false
endpoint	OpenAI-compatible API endpoint	Aliyun DashScope
api_key	API key	-
model	Model name	qwen-turbo
lines	Terminal lines to analyze	50
interval	Analysis interval (seconds)	30
extra_params	Custom API parameters (JSON)	-

Status Tags:

• 完毕 - Command finished, prompt ready
• 进行 - Command running, output in progress
• 需确认 - Waiting for y/n or Enter
• 需输入 - Waiting for password or input
• 需选择 - Menu selection required
• 错误 - Error occurred
• 等待 - Long idle, no output

Auto-Reply Configuration

Auto-reply allows the AI to automatically respond to terminal prompts. Configure via Web UI or runtime.json:

{
  "auto_config": {
    "model": "",
    "context_lines": 150,
    "confidence_min": 0.7,
    "cooldown_ms": 3000,
    "goal": "Accept default options, skip confirmations",
    "allow_tags": ["需确认", "需选择"],
    "deny_keywords": ["rm", "delete", "format", "sudo"],
    "extra_params": ""
  }
}

Field	Description	Default
model	Decision model (empty = use AI Monitor model)	-
context_lines	Terminal lines for decision context	150
confidence_min	Minimum confidence to execute action	0.7
cooldown_ms	Cooldown between actions (ms)	3000
goal	User-defined strategy/goal for AI	-
allow_tags	Tags that allow auto-reply	["需确认", "需选择"]
deny_keywords	Blocked keywords in actions	["rm", "delete", "format", "sudo"]
extra_params	Custom API parameters (JSON)	-

Email Notification Configuration

Get email alerts when sessions need attention:

{
  "email": {
    "enabled": true,
    "smtp_host": "smtp.example.com",
    "smtp_port": 587,
    "username": "user@example.com",
    "password": "password",
    "from_address": "user@example.com",
    "to_address": "notify@example.com",
    "notify_delay": 60,
    "notify_tags": ["需确认", "需输入", "需选择", "错误"]
  }
}

Field	Description	Default
enabled	Enable email notifications	false
smtp_host	SMTP server host	-
smtp_port	SMTP server port	587
username	SMTP username	-
password	SMTP password	-
from_address	Sender email address	-
to_address	Recipient email address	-
notify_delay	Delay before sending (seconds)	60
notify_tags	Tags that trigger notifications	["需确认", "需输入", "需选择", "错误"]

Upgrade & Reinstall

To upgrade, simply run the install script again:

curl -fsSL https://raw.githubusercontent.com/Cucgua/winterm-bridge/main/scripts/install.sh | bash

Config Preservation Policy:

• Existing runtime.json config is preserved on reinstall
• Only explicitly specified parameters will override (e.g., --port 9000)
• Fonts directory and tmux config are never deleted
• Uninstall will prompt before deleting config directory

tmux Configuration

The installer automatically generates a tmux configuration file at ~/.config/winterm-bridge/tmux.conf with optimized settings:

# Enable mouse/touch scrolling
set -g mouse on

# Disable right-click context menu
unbind -n MouseDown3Pane

# Increase history buffer
set -g history-limit 50000

# Allow different clients to use different window sizes
setw -g aggressive-resize on

# Reduce command delay
set -s escape-time 0

# Scroll 2 lines at a time (default is 5)
bind -T copy-mode WheelUpPane send -N 2 -X scroll-up
bind -T copy-mode WheelDownPane send -N 2 -X scroll-down
bind -T copy-mode-vi WheelUpPane send -N 2 -X scroll-up
bind -T copy-mode-vi WheelDownPane send -N 2 -X scroll-down

You can customize this file after installation. The installer will ask before overwriting an existing configuration.

tmux Version Requirements:

• Minimum: tmux 2.1+ (recommended for full feature support)
• The installer will automatically check and warn if your tmux version is older

Fonts Configuration

The installer creates a fonts directory at ~/.config/winterm-bridge/fonts/.

Usage:

1. Place font files (.ttf, .otf) in this directory
2. Fonts are automatically loaded to ~/.local/share/fonts/winterm-bridge/ on service start

Recommended Fonts:

• Nerd Fonts - Programming fonts with icons
  • FiraCode Nerd Font
  • JetBrainsMono Nerd Font
  • Hack Nerd Font

Build from Source

Prerequisites

• Go 1.22+
• Node.js 18+
• tmux

Build

# Clone the repository
git clone https://github.com/Cucgua/winterm-bridge.git
cd winterm-bridge

# Use build script
./scripts/build.sh

# Or build manually
cd frontend && npm install && npm run build && cd ..
cd backend && go build -o winterm-bridge ./cmd/server

Build All Platforms

./scripts/build.sh --all

Project Structure

winterm-bridge/
├── backend/
│   ├── cmd/server/
│   │   ├── main.go          # Entry point
│   │   └── static/          # Embedded frontend assets
│   └── internal/
│       ├── api/             # REST API handlers
│       ├── auth/            # PIN & JWT authentication
│       ├── config/          # Configuration management
│       ├── pty/             # PTY management & WebSocket
│       ├── session/         # Session registry & persistence
│       └── tmux/            # tmux client wrapper
├── frontend/
│   └── src/
│       ├── routes/
│       │   ├── desktop/     # Desktop UI components
│       │   └── mobile/      # Mobile UI components
│       └── shared/          # Shared components & utilities
└── scripts/
    ├── install.sh           # One-line installer
    ├── build.sh             # Build script
    └── idea-context-server-1.0.0.zip  # IntelliJ IDEA MCP plugin

API Reference

Method	Endpoint	Description
POST	/api/auth	Authenticate with PIN
GET	/api/auth/validate	Validate JWT token
GET	/api/sessions	List all sessions
POST	/api/sessions	Create new session
DELETE	/api/sessions/{id}	Delete session
POST	/api/sessions/{id}/attach	Get WebSocket attachment token
POST	/api/sessions/{id}/persist	Mark session as persistent
DELETE	/api/sessions/{id}/persist	Remove persistence
GET	/api/sessions/{id}/settings	Get session settings (notify + persist)
POST	/api/sessions/{id}/notify	Enable notification for session
DELETE	/api/sessions/{id}/notify	Disable notification for session
GET	/api/ai/config	Get AI monitor configuration
POST	/api/ai/config	Update AI monitor configuration
POST	/api/ai/test	Test AI API connection
GET	/api/ai/summaries	Get AI summaries for all sessions
GET	/api/email/config	Get email notification configuration
POST	/api/email/config	Update email notification configuration
POST	/api/email/test	Send test email
WS	/ws?token={token}	Terminal WebSocket connection

Tech Stack

Frontend

• React 18 + TypeScript
• Vite
• xterm.js + WebGL addon
• Tailwind CSS
• Zustand

Backend

• Go 1.22
• gorilla/websocket
• creack/pty

IDEA Plugin

An IntelliJ IDEA plugin (idea-context-server) is included in scripts/idea-context-server-1.0.0.zip. It provides an MCP (Model Context Protocol) server that exposes the currently active file in IDEA to AI coding assistants.

Installation:

1. Open IntelliJ IDEA → Settings → Plugins → ⚙️ → Install Plugin from Disk
2. Select scripts/idea-context-server-1.0.0.zip
3. Restart IDEA

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• xterm.js - Terminal emulator for the web
• tmux - Terminal multiplexer