Shoji

tmux の Web UI。ブラウザ（特にスマホ）から tmux ペインの閲覧・操作ができる。

Tailscale 等の VPN 経由で iPhone から自宅の tmux セッションを操作する用途を想定。

特徴

• tmux セッション/ウィンドウ/ペインをツリー構造で一覧表示
• 各ペインのターミナル内容をプレビュー表示
• xterm.js によるリアルタイムターミナルレンダリング（ANSI カラー対応）
• WebSocket による 100ms ポーリングでリアルタイム更新
• スマホ向けの特殊キー・Ctrl キーツールバー
• QR コード表示でスマホから簡単接続
• トークンベースの認証

必要環境

• Bun v1.0+
• tmux が起動中であること

インストール

npm install -g shoji-terminal

使い方

tmux セッションが動いているマシンで:

shoji

起動すると QR コードが表示される。スマホでスキャンしてブラウザでアクセス。

オプション

-p, --port <number>   ポート番号 (デフォルト: 3274)
--host <address>       バインドアドレス (デフォルト: 0.0.0.0)

開発

# 依存関係インストール
bun install

# 開発サーバー起動（サーバー + クライアント HMR）
bun run dev

# ビルド
bun run build

アーキテクチャ

src/
├── server/          # Bun + Hono サーバー
│   ├── index.ts     # エントリーポイント（Bun.serve + QR コード表示）
│   ├── app.ts       # Hono アプリ（REST API + 静的ファイル配信）
│   ├── auth/        # トークン認証
│   ├── routes/      # API ルート（/api/sessions, /api/panes/:id/preview）
│   ├── tmux/        # tmux コマンドラッパー（capture-pane, send-keys 等）
│   └── ws/          # WebSocket ハンドラ + PaneStreamManager
├── client/          # React 19 SPA
│   ├── components/  # PaneList, TerminalView, SpecialKeys
│   ├── hooks/       # useAuth, useWebSocket, usePaneStream
│   └── pages/       # HomePage, PanePage
└── shared/          # クライアント・サーバー共有の型定義
    └── protocol.ts  # WebSocket メッセージ型

技術スタック

• サーバー: Bun, Hono, WebSocket
• クライアント: React 19, xterm.js, Tailwind CSS v4, react-router v7
• ビルド: Vite

ライセンス

MIT