A CLI tool for managing multiple ttyd+tmux web terminal sessions.

複数の ttyd+tmux Web ターミナルセッションを管理する CLI ツール。

• Quick Start
• Features
• Use Cases
• Installation
• Usage Patterns
• Commands
• Configuration
• Architecture
• Toolbar Features
• Notifications
• Share Links
• PWA Support
• Caddy Integration
• Development

# Install / インストール
npm install -g ttyd-mux

# Start terminal in current directory / カレントディレクトリでターミナル起動
cd ~/my-project
ttyd-mux up

# Open in browser / ブラウザで開く
# → http://localhost:7680/ttyd-mux/my-project/

# Stop / 停止
ttyd-mux down

That's it! No configuration needed for basic usage.

基本的な利用には設定不要です。

Monitor long-running AI coding sessions (like Claude Code) from anywhere.

Claude Code などの AI コーディングセッションをどこからでも監視。

# On your server / サーバー上で
cd ~/my-ai-project
ttyd-mux up

# Access from phone/tablet / スマホ・タブレットからアクセス
# https://your-server.com/ttyd-mux/my-ai-project/

Access your development environment from any device with a browser.

ブラウザさえあればどのデバイスからでも開発環境にアクセス。

# Start multiple project terminals / 複数プロジェクトを起動
cd ~/project-a && ttyd-mux up
cd ~/project-b && ttyd-mux up

# List all sessions / セッション一覧
ttyd-mux list --url

Predefined sessions for server operations.

サーバー操作用の事前定義セッション。

# ~/.config/ttyd-mux/config.yaml
sessions:
  - name: logs
    dir: /var/log
  - name: docker
    dir: /opt/docker
  - name: admin
    dir: /root

ttyd-mux daemon start --sessions

Share your terminal with team members via browser.

ブラウザ経由でチームメンバーとターミナルを共有。

English: This tool was developed to easily access terminal sessions running AI coding assistants like Claude Code from a web browser. When running long coding sessions with AI assistants on a remote server, you can monitor and interact with them from anywhere through your browser.

日本語: このツールは、Claude Code などの AI コーディングアシスタントを実行しているターミナルセッションに、ブラウザから簡単にアクセスできるようにする目的で開発されました。リモートサーバーで AI アシスタントと長時間のコーディングセッションを実行する際、ブラウザからどこからでも監視・操作できます。

# Install globally with npm
# npm でグローバルインストール
npm install -g ttyd-mux

# Or run directly with npx
# または npx で直接実行
npx ttyd-mux up

• Node.js 18+ (or Bun)
• ttyd: https://github.com/tsl0922/ttyd
• tmux: Terminal multiplexer

# Ubuntu/Debian
sudo apt install ttyd tmux

# macOS (Homebrew)
brew install ttyd tmux

# Check installation / インストール確認
ttyd-mux doctor

ttyd-mux has two main usage patterns:

ttyd-mux には2つの利用パターンがあります：

Start sessions on-demand in any directory. No configuration needed.

設定不要で、任意のディレクトリでその場でセッションを起動。

# Start in your project directory / プロジェクトディレクトリで起動
cd ~/my-project
ttyd-mux up

# Access in browser / ブラウザでアクセス
# http://localhost:7680/ttyd-mux/my-project/

# Check status / 状態確認
ttyd-mux status

# List sessions with URLs / URLと一緒にセッション一覧
ttyd-mux list --url

# Stop / 停止
ttyd-mux down

Define sessions in config.yaml and start them all at once. Ideal for servers.

config.yaml にセッションを定義し、一括起動。サーバー運用に最適。

# ~/.config/ttyd-mux/config.yaml
sessions:
  - name: project-a
    dir: /home/user/project-a
  - name: project-b
    dir: /home/user/project-b

# Start daemon + all predefined sessions / デーモンと全セッションを起動
ttyd-mux daemon start --sessions

# Or select sessions interactively / またはインタラクティブに選択
ttyd-mux daemon start -s

# Stop daemon + all sessions / デーモンと全セッションを停止
ttyd-mux daemon stop --stop-sessions

Configuration files are searched in the following order:

設定ファイルは以下の順序で検索されます：

1. ./ttyd-mux.yaml
2. ./.ttyd-mux.yaml
3. ~/.config/ttyd-mux/config.yaml

# ~/.config/ttyd-mux/config.yaml

# URL path prefix / URLパスのプレフィックス
base_path: /ttyd-mux

# Base port for ttyd sessions / ttydセッションのベースポート
base_port: 7600

# Daemon HTTP port / デーモンのHTTPポート
daemon_port: 7680

# Listen addresses (default: IPv4 + IPv6 localhost)
listen_addresses:
  - "127.0.0.1"
  - "::1"

# Proxy mode: "proxy" (default) or "static"
# - proxy: All traffic goes through daemon (supports toolbar)
# - static: Sessions accessed directly via Caddy (lower latency)
proxy_mode: proxy

# Hostname for Caddy integration
hostname: example.com

# Toolbar settings (proxy mode only)
toolbar:
  font_size_default_mobile: 32
  font_size_default_pc: 14
  font_size_min: 10
  font_size_max: 48

# Predefined sessions for static usage / 静的利用のためのセッション定義
sessions:
  - name: project-a
    dir: /home/user/project-a
  - name: project-b
    dir: /home/user/project-b

                                    ┌─────────────────┐
                                    │   ttyd :7601    │
                                    │ (-b /ttyd-mux/  │
┌─────────┐      ┌──────────────┐   │    project-a)   │
│  Caddy  │──────│  ttyd-mux    │───┼─────────────────┤
│         │      │  daemon      │   │   ttyd :7602    │
│ :443    │      │  :7680       │   │ (-b /ttyd-mux/  │
└─────────┘      │              │   │    project-b)   │
                 │  - Portal    │   └─────────────────┘
                 │  - Proxy     │
                 │  - Toolbar   │
                 │  - API       │
                 └──────────────┘

• Caddy: Forwards external requests to ttyd-mux / 外部からのリクエストを ttyd-mux に転送
• ttyd-mux daemon: Portal + reverse proxy + toolbar injection / ポータル + プロキシ + ツールバー注入
• ttyd: Web terminal for each session (runs tmux) / 各セッションの Web ターミナル（tmux を起動）

                 ┌──────────────┐   ┌─────────────────┐
                 │ Static HTML  │   │   ttyd :7601    │
┌─────────┐      │ (portal)     │   │    project-a    │
│  Caddy  │──────┼──────────────┼───┼─────────────────┤
│         │      │              │   │   ttyd :7602    │
│ :443    │      │              │   │    project-b    │
└─────────┘      └──────────────┘   └─────────────────┘

• Lower latency (no intermediate proxy) / 低レイテンシ（中間プロキシなし）
• Static portal (no daemon needed at runtime) / 静的ポータル（実行時デーモン不要）
• No toolbar support / ツールバー非対応

Each session consists of three independent processes:

各セッションは3つの独立したプロセスで構成されています：

ttyd-mux daemon (manages sessions)
    │
    └── ttyd (web terminal server)
            │
            └── tmux session (terminal multiplexer)

What happens when stopping:

停止時の挙動：

• By default, tmux sessions persist even when ttyd or daemon is stopped

• Restarting with ttyd-mux up reconnects to existing tmux session

• Use --kill-tmux flag to fully terminate tmux sessions

• デフォルトでは tmux セッションは ttyd やデーモンを停止しても残ります

• ttyd-mux up で再起動すると既存の tmux セッションに再接続します

• --kill-tmux フラグで tmux セッションも完全に終了できます

In proxy mode, ttyd-mux injects a toolbar for improved input experience:

プロキシモードでは、入力体験向上のためツールバーが注入されます：

• IME Input: Text field with virtual keyboard support / 日本語 IME 対応テキスト入力
• Touch Pinch Zoom: Two-finger pinch to resize font / 2本指ピンチでフォントサイズ変更
• Double-tap Enter: Double-tap to send Enter key / ダブルタップで Enter 送信
• Scroll Buttons: PgUp/PgDn for scrollback / スクロールバック用ボタン
• Minimize Mode: Collapse toolbar for more terminal space / ツールバー最小化

• Ctrl+Scroll Zoom: Mouse wheel with Ctrl key / Ctrl+マウスホイールでサイズ変更
• Trackpad Pinch Zoom (Mac): Two-finger pinch gesture / トラックパッドピンチ
• Ctrl+J Toggle: Show/hide toolbar / ツールバー表示切替
• Ctrl+Shift+F: Open search bar / 検索バーを開く

Get notified when something happens in your terminal sessions.

ターミナルセッションで何かが起きたときに通知を受け取れます。

Receive browser push notifications even when the tab is closed.

タブを閉じていてもブラウザのプッシュ通知を受け取れます。

Setup / 設定:

1. Click the bell icon (🔔) in the toolbar / ツールバーのベルアイコンをクリック
2. Allow notifications when prompted / 通知を許可
3. Notifications are sent on terminal bell (\a) / ターミナルベル（\a）で通知

Use cases / 活用例:

# Notify when command completes / コマンド完了時に通知
long-running-command; echo -e '\a'

# Or use bell directly / または直接ベルを使用
sleep 300 && printf '\a'

Configure patterns to trigger notifications:

通知トリガーのパターンを設定:

# ~/.config/ttyd-mux/config.yaml
notifications:
  triggers:
    - type: bell  # Terminal bell (default)
    - type: pattern
      pattern: "ERROR|FAILED"
      flags: "i"

Share read-only access to your terminal sessions.

ターミナルセッションへの読み取り専用アクセスを共有できます。

# Share current session for 1 hour (default)
# 現在のセッションを1時間共有（デフォルト）
ttyd-mux share

# Share specific session for 24 hours
# 特定のセッションを24時間共有
ttyd-mux share my-session --expires 24h

# Share with custom expiry
# カスタム有効期限で共有
ttyd-mux share --expires 30m   # 30 minutes
ttyd-mux share --expires 7d    # 7 days

# List active shares / アクティブな共有一覧
ttyd-mux share list

# Revoke a share / 共有を取り消し
ttyd-mux share revoke <token>

• Read-only: Viewers can see but not interact / 閲覧のみ、操作不可
• Time-limited: Links expire automatically / 自動的に期限切れ
• Revocable: Cancel access anytime / いつでもアクセス取り消し可能

ttyd-mux supports Progressive Web App (PWA) for a native app-like experience:

ttyd-mux はネイティブアプリのような体験のため PWA に対応しています：

• Fullscreen Mode: No browser address bar / アドレスバーなしのフルスクリーン
• Home Screen Icon: Add to home screen on iOS/Android / ホーム画面にアイコン追加
• Auto Reconnect: Automatically reloads when returning from background / バックグラウンドから復帰時に自動再接続

Android (Chrome):

1. Open portal page / ポータルページを開く
2. Menu → "Add to Home screen" / メニュー → 「ホーム画面に追加」

iOS (Safari):

1. Open portal page / ポータルページを開く
2. Share → "Add to Home Screen" / 共有 → 「ホーム画面に追加」

# Add route / ルートを追加
ttyd-mux caddy setup --hostname example.com

# Check configuration / 設定を確認
ttyd-mux caddy status

# Remove route / ルートを削除
ttyd-mux caddy remove --hostname example.com

# Show snippet for copy-paste / コピペ用スニペットを表示
ttyd-mux caddy snippet

handle /ttyd-mux/* {
    reverse_proxy 127.0.0.1:7680
}

For external access, configure authentication in Caddy:

外部公開時は Caddy で認証を設定：

example.com {
    # Basic authentication
    basicauth /ttyd-mux/* {
        user $2a$14$... # bcrypt hash
    }

    handle /ttyd-mux/* {
        reverse_proxy 127.0.0.1:7680
    }
}

See docs/caddy-setup.md for details, including OAuth setup.

~/.config/ttyd-mux/
  config.yaml           # Configuration file / 設定ファイル

~/.local/state/ttyd-mux/
  state.json            # Running session state / 実行中セッションの状態
  ttyd-mux.sock         # Daemon communication socket / デーモン通信用ソケット

# Clone repository
git clone https://github.com/cuzic/ttyd-mux.git
cd ttyd-mux

# Install dependencies
bun install

# Run in development / 開発実行
bun run src/index.ts <command>

# Test / テスト
bun test                  # Unit tests
bun run test:e2e          # E2E tests (Playwright)

# Type check / 型チェック
bun run typecheck

# Lint / リント
bun run check

# Build / ビルド
bun run build

Issues and Pull Requests are welcome!

Issue や Pull Request を歓迎します！

See CLAUDE.md for development guidelines.

MIT