purplemux 0.1.2

package/README.tr.md

@@ -0,0 +1,224 @@
+# purplemux
+
+**Claude Code, birden çok işi aynı anda. Daha hızlı.**
+
+Tüm oturumlarınız tek bir ekranda. Telefonda bile kopuksuz.
+
+<a href="README.md">English</a> | <a href="README.ja.md">日本語</a> | <a href="README.zh-CN.md">简体中文</a> | <a href="README.zh-TW.md">繁體中文</a> | <a href="README.ko.md">한국어</a> | <a href="README.de.md">Deutsch</a> | <a href="README.es.md">Español</a> | <a href="README.fr.md">Français</a> | <a href="README.ru.md">Русский</a> | <a href="README.pt-BR.md">Português (Brasil)</a> | Türkçe
+
+![purplemux](docs/images/screenshot.png)
+
+![purplemux mobile](docs/images/screenshot-mobile.png)
+
+## Kurulum
+
+```bash
+npx purplemux
+```
+
+Tarayıcınızda [http://localhost:8022](http://localhost:8022) adresini açın. Hepsi bu.
+
+> Node.js 20+ ve tmux gerekir. macOS veya Linux.
+
+## Neden purplemux
+
+- **Çoklu oturum panosu** — Tüm Claude Code oturumlarının «çalışıyor / giriş bekliyor» durumunu tek bakışta görün
+- **Rate limit takibi** — 5 saat / 7 gün kalan kullanım ve sıfırlama geri sayımı
+- **Push bildirimleri** — Görev bitince veya giriş gerektiğinde masaüstü ve mobil uyarılar
+- **Mobil ve çoklu cihaz** — Aynı oturuma telefonunuzdan, tabletinizden veya başka bir masaüstünden erişin
+- **Canlı oturum görünümü** — CLI çıktısını kaydırmaya son: ilerleme bir zaman tüneli olarak düzenlenir
+
+Ayrıca
+
+- **Kopmayan oturumlar** — tmux tabanlı. Tarayıcıyı kapatın, her şey yerinde kalır. Tekrar bağlandığınızda sekmeleriniz, panelleriniz ve dizinleriniz tam da bıraktığınız yerde
+- **Kendi sunucunuzda, açık kaynak** — Kod ve oturum verileri makinenizden hiç çıkmaz. Harici sunucu yok
+- **Şifreli uzaktan erişim** — Tailscale üzerinden her yerden HTTPS
+
+## Resmi Remote Control'den farkı
+
+> Resmi Remote Control tek bir oturumun uzaktan kontrolüne odaklanır. Çoklu oturum yönetimi, push bildirimleri ve kalıcı oturumlara ihtiyaç duyduğunuzda purplemux'u kullanın.
+
+## Özellikler
+
+### Terminal
+
+- **Panel bölme** — Yatay / dikey serbest bölme, sürükleyerek yeniden boyutlandırma
+- **Sekme yönetimi** — Çoklu sekme, sürükleyerek sıralama, süreç adına dayalı otomatik başlıklar
+- **Klavye kısayolları** — Bölme, sekme değiştirme, odak hareketi
+- **Terminal temaları** — Koyu / açık mod, çeşitli renk temaları
+- **Çalışma alanları** — Panel düzenini, sekmeleri ve çalışma dizinlerini çalışma alanı bazında kaydedin ve geri yükleyin
+- **Git diff görüntüleyici** — Git diff'leri doğrudan terminal panelinde inceleyin. Side-by-side / Line-by-line geçişi ve sözdizimi vurgulaması
+- **Web tarayıcı paneli** — Geliştirme çıktısını kontrol etmek için terminalin yanında gömülü tarayıcı (Electron)
+
+### Claude Code entegrasyonu
+
+- **Gerçek zamanlı durum** — Çalışıyor / giriş bekliyor göstergeleri ve oturumlar arası geçiş
+- **Canlı oturum görünümü** — Mesajlar, araç çağrıları, görevler, izin istekleri ve thinking blokları
+- **Tek tıkla Resume** — Duraklatılmış oturumu doğrudan tarayıcıdan devam ettirin
+- **Otomatik Resume** — Sunucu başlatıldığında önceki Claude oturumlarını otomatik olarak kurtarır
+- **Hızlı prompt'lar** — Sık kullanılan prompt'ları kaydedin ve tek tıkla gönderin
+- **Mesaj geçmişi** — Önceki mesajları tekrar kullanın
+- **Kullanım istatistikleri** — Token'lar (input / output / cache read / cache write), maliyet, proje bazlı kırılım, günlük AI raporları
+- **Rate limit** — 5 saat / 7 gün kalan kullanım ve sıfırlama geri sayımı
+
+### Mobil ve erişilebilirlik
+
+- **Duyarlı arayüz** — Telefon ve tablette terminal ile zaman tüneli
+- **PWA** — Ana ekrana ekleyin, yerel uygulama hissi yaşayın
+- **Web Push** — Sekme kapalıyken bile bildirim alın
+- **Çoklu cihaz senkronizasyonu** — Çalışma alanı değişiklikleri gerçek zamanlı yansır
+- **Tailscale** — WireGuard ile şifrelenmiş tünel üzerinden dışarıdan HTTPS erişimi
+- **Parola doğrulaması** — scrypt ile hash'leme, dışarı açıldığında bile güvenli
+- **Çok dilli** — 11 dil; aralarında 한국어, English, 日本語, 中文
+
+### AI Ajanları (Beta)
+
+Bağımsız AI ajanları oluşturun, onlara roller ve kişilikler (soul) atayın ve birden fazla sekme üzerinden paralel görevler çalıştırın. Her ajanın kendine ait sohbeti, belleği ve çalışma alanı vardır.
+
+## Desteklenen platformlar
+
+| Platform | Durum | Notlar |
+|---|---|---|
+| macOS (Apple Silicon / Intel) | ✅ | Electron uygulaması dahil |
+| Linux | ✅ | Electron yok |
+| Windows | ❌ | Desteklenmiyor |
+
+## Kurulum ayrıntıları
+
+### Gereksinimler
+
+- macOS 13+ veya Linux
+- [Node.js](https://nodejs.org/) 20+
+- [tmux](https://github.com/tmux/tmux)
+
+### npx (en hızlısı)
+
+```bash
+npx purplemux
+```
+
+### Global kurulum
+
+```bash
+npm install -g purplemux
+purplemux
+```
+
+### Kaynaktan çalıştırma
+
+```bash
+git clone https://github.com/subicura/purplemux.git
+cd purplemux
+pnpm install
+pnpm start
+```
+
+Geliştirme modu:
+
+```bash
+pnpm dev
+```
+
+#### Log seviyesi
+
+Genel seviyeyi `LOG_LEVEL` ile ayarlayın (varsayılan `info`).
+
+```bash
+LOG_LEVEL=debug pnpm dev
+```
+
+Yalnızca belirli modülleri açmak için `modül=seviye` çiftlerini virgülle ayırarak `LOG_LEVELS` içine yazın. Kullanılabilir seviyeler: `trace` / `debug` / `info` / `warn` / `error` / `fatal`.
+
+```bash
+# Sadece Claude Code hook davranışını debug ile izle
+LOG_LEVELS=hooks=debug pnpm dev
+
+# Birden fazla modülü birlikte
+LOG_LEVELS=hooks=debug,status=warn pnpm dev
+```
+
+`LOG_LEVELS` içinde belirtilmeyen modüller `LOG_LEVEL` değerini kullanır.
+
+## Dış erişim (Tailscale Serve)
+
+```bash
+tailscale serve --bg 8022
+```
+
+`https://<machine>.<tailnet>.ts.net` üzerinden erişin. Kapatmak için:
+
+```bash
+tailscale serve --bg off 8022
+```
+
+## Güvenlik
+
+### Parola
+
+İlk erişimde bir parola belirleyin. scrypt ile hash'lenip `~/.purplemux/config.json` içinde saklanır.
+
+Sıfırlamak için `~/.purplemux/config.json` dosyasını silin ve yeniden başlatın — onboarding ekranı tekrar görünecektir.
+
+### HTTPS
+
+Varsayılan protokol HTTP'dir. Dışarı açarken mutlaka HTTPS kullanın:
+
+- **Tailscale Serve** — WireGuard şifrelemesi ve otomatik sertifikalar
+- **Nginx / Caddy** — WebSocket upgrade başlıklarını (`Upgrade`, `Connection`) iletmek zorunludur
+
+### Veri dizini (`~/.purplemux/`)
+
+| Dosya | Açıklama |
+|---|---|
+| `config.json` | Kimlik bilgileri (hash) ve uygulama ayarları |
+| `workspaces.json` | Çalışma alanı düzenleri, sekmeler ve dizinler |
+| `vapid-keys.json` | Web Push VAPID anahtarları (otomatik üretilir) |
+| `push-subscriptions.json` | Push abonelik bilgileri |
+| `hooks/` | Kullanıcı tanımlı hook'lar |
+
+## Mimari
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  Browser                                                    │
+│  ┌───────────┐ ┌───────────┐ ┌──────────┐ ┌─────────────┐   │
+│  │  xterm.js │ │ Timeline  │ │ Status   │ │ Multi-device│   │
+│  │  Terminal │ │           │ │          │ │ Sync        │   │
+│  └─────┬─────┘ └─────┬─────┘ └────┬─────┘ └──────┬──────┘   │
+└────────┼─────────────┼────────────┼──────────────┼──────────┘
+         │ws           │ws          │ws            │ws
+         │/terminal    │/timeline   │/status       │/sync
+         ▼             ▼            ▼              ▼
+┌─────────────────────────────────────────────────────────────┐
+│  Node.js Server (:8022)                                     │
+│  ┌──────────┐  ┌───────────────┐  ┌─────────────────────┐   │
+│  │ node-pty │  │ JSONL Watcher │  │ Status Manager      │   │
+│  │ PTY↔WS   │  │ File watch →  │  │ Process tree +      │   │
+│  │ Binary   │  │ Parse → Send  │  │ JSONL tail analysis │   │
+│  └────┬─────┘  └───────┬───────┘  └──────────┬──────────┘   │
+└───────┼────────────────┼─────────────────────┼──────────────┘
+        ▼                ▼                     ▼
+┌─────────────────────────────────────────────────────────────┐
+│  System                                                     │
+│  tmux (purple socket)         Claude Code                   │
+│  ┌────────┐ ┌────────┐       ┌────────────────────────────┐ │
+│  │Session1│ │Session2│  ...  │ ~/.claude/sessions/        │ │
+│  │ (shell)│ │ (shell)│       │ ~/.claude/projects/        │ │
+│  └────────┘ └────────┘       │   └─ {project}/{sid}.jsonl │ │
+│                              └────────────────────────────┘ │
+└─────────────────────────────────────────────────────────────┘
+```
+
+**Terminal G/Ç** — xterm.js, node-pty'ye WebSocket üzerinden bağlanır; node-pty ise tmux oturumlarına iliştirilir. İkili bir protokol stdin/stdout/resize işlemlerini backpressure kontrolüyle yürütür.
+
+**Durum algılama** — Claude Code olay hook'ları (`SessionStart`, `Stop`, `Notification`) HTTP POST ile anında güncelleme gönderir. Her 5–15 sn'de bir süreç ağacı kontrol edilir ve JSONL dosyalarının son 8 KB'si analiz edilir.
+
+**Zaman tüneli** — `~/.claude/projects/` altındaki JSONL oturum loglarını izler, değişiklikte yeni satırları ayrıştırır ve yapılandırılmış girişleri tarayıcıya akıtır.
+
+**tmux izolasyonu** — Mevcut tmux'unuzdan tamamen ayrı, özel bir `purple` soketi kullanır. Prefix tuşu yok, durum çubuğu yok.
+
+**Otomatik kurtarma** — Sunucu başlatıldığında önceki Claude oturumları `claude --resume {sessionId}` ile geri yüklenir.
+
+## License
+
+[MIT](LICENSE)

package/README.zh-CN.md

@@ -0,0 +1,224 @@
+# purplemux
+
+**Claude Code,多任务同时进行。更快。**
+
+一屏纵览所有会话,在手机上也毫无中断。
+
+<a href="README.md">English</a> | <a href="README.ja.md">日本語</a> | 简体中文 | <a href="README.zh-TW.md">繁體中文</a> | <a href="README.ko.md">한국어</a> | <a href="README.de.md">Deutsch</a> | <a href="README.es.md">Español</a> | <a href="README.fr.md">Français</a> | <a href="README.ru.md">Русский</a> | <a href="README.pt-BR.md">Português (Brasil)</a> | <a href="README.tr.md">Türkçe</a>
+
+![purplemux](docs/images/screenshot.png)
+
+![purplemux mobile](docs/images/screenshot-mobile.png)
+
+## 安装
+
+```bash
+npx purplemux
+```
+
+在浏览器中打开 [http://localhost:8022](http://localhost:8022)。完成。
+
+> 需要 Node.js 20+ 和 tmux。macOS 或 Linux。
+
+## 为什么选择 purplemux
+
+- **多会话仪表盘** — 一眼掌握所有 Claude Code 会话的「运行中 / 等待输入」状态
+- **速率限制监控** — 显示 5 小时 / 7 天剩余额度及重置倒计时
+- **推送通知** — 任务完成或需要输入时,桌面与移动端推送提醒
+- **移动端 & 多设备** — 在手机、平板或其他桌面都能访问同一会话
+- **实时会话视图** — 无需滚动 CLI 输出,进度以时间线形式呈现
+
+此外
+
+- **不中断的会话** — 基于 tmux。关闭浏览器后会话与工作环境依然保留。重新连接时,标签、面板、目录均保持最后状态
+- **自托管 & 开源** — 代码与会话数据仅存在本机,不经任何外部服务器
+- **加密远程访问** — 通过 Tailscale 在任何地点使用 HTTPS 接入
+
+## 与官方 Remote Control 的区别
+
+> 官方 Remote Control 专注于单一会话的远程控制。当你需要多会话管理、推送通知与会话持久化时,请使用 purplemux。
+
+## 功能
+
+### 终端
+
+- **面板分割** — 水平 / 垂直自由分割,可拖拽调整大小
+- **标签管理** — 多标签、拖拽排序、基于进程名的自动标题
+- **键盘快捷键** — 分割、切换标签、焦点移动
+- **终端主题** — 深色 / 浅色模式,多种配色主题
+- **工作区** — 以工作区为单位保存 / 恢复面板布局、标签与工作目录
+- **Git Diff 查看器** — 直接在终端面板中查看 git diff。支持 Side-by-side / Line-by-line 切换与语法高亮
+- **内置浏览器面板** — 在终端旁嵌入浏览器查看开发结果 (Electron)
+
+### Claude Code 集成
+
+- **实时状态** — 运行中 / 等待输入指示,支持在会话间切换
+- **实时会话视图** — 消息、工具调用、任务、权限请求、thinking 区块
+- **一键 Resume** — 直接从浏览器恢复已中断的会话
+- **自动 Resume** — 服务器启动时自动恢复之前的 Claude 会话
+- **快速提示** — 注册常用提示,一键发送
+- **消息历史** — 复用之前的消息
+- **用量统计** — Token (input / output / cache read / cache write)、成本、按项目拆分、每日 AI 报告
+- **速率限制** — 5 小时 / 7 天剩余额度,重置倒计时
+
+### 移动端 & 易用性
+
+- **响应式 UI** — 在手机 / 平板上使用终端与时间线
+- **PWA** — 添加到主屏幕,体验接近原生应用
+- **Web Push** — 关闭标签也能接收通知
+- **多设备同步** — 工作区变更实时同步
+- **Tailscale** — 通过 WireGuard 加密隧道从外部进行 HTTPS 访问
+- **密码认证** — scrypt 哈希,即便对外暴露也安全
+- **多语言支持** — 한국어、English、日本語、中文 等 11 种语言
+
+### AI 代理 (Beta)
+
+创建独立的 AI 代理,为其赋予角色与性格 (soul),通过多标签并行执行任务。每个代理拥有独立的聊天、记忆与工作区。
+
+## 支持的平台
+
+| 平台 | 状态 | 备注 |
+|---|---|---|
+| macOS (Apple Silicon / Intel) | ✅ | 包含 Electron 应用 |
+| Linux | ✅ | 不含 Electron |
+| Windows | ❌ | 不支持 |
+
+## 安装详情
+
+### 前置要求
+
+- macOS 13+ 或 Linux
+- [Node.js](https://nodejs.org/) 20+
+- [tmux](https://github.com/tmux/tmux)
+
+### npx (最快)
+
+```bash
+npx purplemux
+```
+
+### 全局安装
+
+```bash
+npm install -g purplemux
+purplemux
+```
+
+### 从源码运行
+
+```bash
+git clone https://github.com/subicura/purplemux.git
+cd purplemux
+pnpm install
+pnpm start
+```
+
+开发模式:
+
+```bash
+pnpm dev
+```
+
+#### 日志等级设置
+
+整体等级通过 `LOG_LEVEL` (默认 `info`) 调整。
+
+```bash
+LOG_LEVEL=debug pnpm dev
+```
+
+若只想开启特定模块,将 `模块=等级` 对以逗号分隔写入 `LOG_LEVELS`。可用等级: `trace` / `debug` / `info` / `warn` / `error` / `fatal`。
+
+```bash
+# 仅将 Claude Code hook 行为以 debug 追踪
+LOG_LEVELS=hooks=debug pnpm dev
+
+# 同时指定多个模块
+LOG_LEVELS=hooks=debug,status=warn pnpm dev
+```
+
+未在 `LOG_LEVELS` 中指定的模块,将沿用 `LOG_LEVEL`。
+
+## 外部访问 (Tailscale Serve)
+
+```bash
+tailscale serve --bg 8022
+```
+
+通过 `https://<machine>.<tailnet>.ts.net` 访问。关闭:
+
+```bash
+tailscale serve --bg off 8022
+```
+
+## 安全
+
+### 密码
+
+首次访问时设置密码。使用 scrypt 哈希并保存到 `~/.purplemux/config.json`。
+
+要重置,请删除 `~/.purplemux/config.json` 并重启,引导界面会再次出现。
+
+### HTTPS
+
+默认使用 HTTP。对外暴露时请务必启用 HTTPS:
+
+- **Tailscale Serve** — WireGuard 加密 + 自动证书
+- **Nginx / Caddy** — 必须转发 WebSocket 升级头 (`Upgrade`, `Connection`)
+
+### 数据目录 (`~/.purplemux/`)
+
+| 文件 | 说明 |
+|---|---|
+| `config.json` | 认证信息 (哈希) 与应用设置 |
+| `workspaces.json` | 工作区布局、标签、目录 |
+| `vapid-keys.json` | Web Push VAPID 密钥 (自动生成) |
+| `push-subscriptions.json` | 推送订阅信息 |
+| `hooks/` | 用户自定义 hook |
+
+## 架构
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  Browser                                                    │
+│  ┌───────────┐ ┌───────────┐ ┌──────────┐ ┌─────────────┐   │
+│  │  xterm.js │ │ Timeline  │ │ Status   │ │ Multi-device│   │
+│  │  Terminal │ │           │ │          │ │ Sync        │   │
+│  └─────┬─────┘ └─────┬─────┘ └────┬─────┘ └──────┬──────┘   │
+└────────┼─────────────┼────────────┼──────────────┼──────────┘
+         │ws           │ws          │ws            │ws
+         │/terminal    │/timeline   │/status       │/sync
+         ▼             ▼            ▼              ▼
+┌─────────────────────────────────────────────────────────────┐
+│  Node.js Server (:8022)                                     │
+│  ┌──────────┐  ┌───────────────┐  ┌─────────────────────┐   │
+│  │ node-pty │  │ JSONL Watcher │  │ Status Manager      │   │
+│  │ PTY↔WS   │  │ File watch →  │  │ Process tree +      │   │
+│  │ Binary   │  │ Parse → Send  │  │ JSONL tail analysis │   │
+│  └────┬─────┘  └───────┬───────┘  └──────────┬──────────┘   │
+└───────┼────────────────┼─────────────────────┼──────────────┘
+        ▼                ▼                     ▼
+┌─────────────────────────────────────────────────────────────┐
+│  System                                                     │
+│  tmux (purple socket)         Claude Code                   │
+│  ┌────────┐ ┌────────┐       ┌────────────────────────────┐ │
+│  │Session1│ │Session2│  ...  │ ~/.claude/sessions/        │ │
+│  │ (shell)│ │ (shell)│       │ ~/.claude/projects/        │ │
+│  └────────┘ └────────┘       │   └─ {project}/{sid}.jsonl │ │
+│                              └────────────────────────────┘ │
+└─────────────────────────────────────────────────────────────┘
+```
+
+**终端 I/O** — xterm.js 通过 WebSocket 连接 node-pty,node-pty 再接入 tmux 会话。使用二进制协议处理 stdin / stdout / resize 并进行背压控制。
+
+**状态检测** — Claude Code 事件 hook (`SessionStart`、`Stop`、`Notification`) 通过 HTTP POST 立即推送更新。每 5–15 秒轮询一次进程树,并分析 JSONL 文件末尾 8KB。
+
+**时间线** — 监听 `~/.claude/projects/` 下的 JSONL 会话日志,文件变化时解析新行并将结构化条目流式传送到浏览器。
+
+**tmux 隔离** — 使用专用的 `purple` socket,与现有 tmux 完全隔离。无前缀键,无状态栏。
+
+**自动恢复** — 服务器启动时通过 `claude --resume {sessionId}` 恢复之前的 Claude 会话。
+
+## License
+
+[MIT](LICENSE)

package/README.zh-TW.md

@@ -0,0 +1,224 @@
+# purplemux
+
+**Claude Code,多項任務同時進行。更快速。**
+
+一個畫面縱覽所有工作階段,在手機上也毫無中斷。
+
+<a href="README.md">English</a> | <a href="README.ja.md">日本語</a> | <a href="README.zh-CN.md">简体中文</a> | 繁體中文 | <a href="README.ko.md">한국어</a> | <a href="README.de.md">Deutsch</a> | <a href="README.es.md">Español</a> | <a href="README.fr.md">Français</a> | <a href="README.ru.md">Русский</a> | <a href="README.pt-BR.md">Português (Brasil)</a> | <a href="README.tr.md">Türkçe</a>
+
+![purplemux](docs/images/screenshot.png)
+
+![purplemux mobile](docs/images/screenshot-mobile.png)
+
+## 安裝
+
+```bash
+npx purplemux
+```
+
+在瀏覽器中開啟 [http://localhost:8022](http://localhost:8022)。完成。
+
+> 需要 Node.js 20+ 與 tmux。macOS 或 Linux。
+
+## 為什麼選擇 purplemux
+
+- **多工作階段儀表板** — 一眼掌握所有 Claude Code 工作階段的「執行中 / 等待輸入」狀態
+- **速率限制監控** — 顯示 5 小時 / 7 天剩餘額度與重置倒數
+- **推播通知** — 任務完成或需要輸入時,透過桌面與行動裝置推播提醒
+- **行動裝置 & 多裝置** — 在手機、平板或其他桌面都能存取同一工作階段
+- **即時工作階段檢視** — 不必捲動 CLI 輸出,進度以時間軸形式整理呈現
+
+此外
+
+- **不中斷的工作階段** — 以 tmux 為基礎。關閉瀏覽器後工作階段與作業環境依然保留。重新連線時,分頁、窗格、目錄都維持最後狀態
+- **自架 & 開源** — 程式碼與工作階段資料僅存在本機,不經任何外部伺服器
+- **加密遠端存取** — 透過 Tailscale 在任何地方使用 HTTPS 連線
+
+## 與官方 Remote Control 的差異
+
+> 官方 Remote Control 專注於單一工作階段的遠端控制。當你需要多工作階段管理、推播通知與工作階段持久化時,請使用 purplemux。
+
+## 特色
+
+### 終端機
+
+- **窗格分割** — 水平 / 垂直自由分割,可拖曳調整大小
+- **分頁管理** — 多分頁、拖曳排序、依據行程名稱自動命名
+- **鍵盤快速鍵** — 分割、切換分頁、移動焦點
+- **終端機佈景主題** — 深色 / 淺色模式,多種配色佈景主題
+- **工作區** — 以工作區為單位儲存 / 還原窗格配置、分頁與工作目錄
+- **Git Diff 檢視器** — 直接在終端機窗格中檢視 git diff。支援 Side-by-side / Line-by-line 切換與語法高亮
+- **內建瀏覽器窗格** — 在終端機旁嵌入瀏覽器檢視開發結果 (Electron)
+
+### Claude Code 整合
+
+- **即時狀態** — 執行中 / 等待輸入指示,可於工作階段間切換
+- **即時工作階段檢視** — 訊息、工具呼叫、任務、權限請求、thinking 區塊
+- **一鍵 Resume** — 直接從瀏覽器恢復已中斷的工作階段
+- **自動 Resume** — 伺服器啟動時自動還原先前的 Claude 工作階段
+- **快速提示** — 註冊常用提示,一鍵送出
+- **訊息紀錄** — 重複使用先前的訊息
+- **使用量統計** — Token (input / output / cache read / cache write)、成本、依專案分析、每日 AI 報告
+- **速率限制** — 5 小時 / 7 天剩餘額度,重置倒數
+
+### 行動裝置 & 易用性
+
+- **響應式 UI** — 在手機 / 平板上使用終端機與時間軸
+- **PWA** — 加入主畫面,體驗接近原生應用
+- **Web Push** — 關閉分頁仍可接收通知
+- **多裝置同步** — 工作區變更即時同步
+- **Tailscale** — 透過 WireGuard 加密隧道從外部進行 HTTPS 連線
+- **密碼驗證** — scrypt 雜湊,對外暴露也安全
+- **多語系支援** — 한국어、English、日本語、中文 等 11 種語言
+
+### AI 代理 (Beta)
+
+建立獨立的 AI 代理,賦予其角色與性格 (soul),透過多分頁並行執行任務。每個代理擁有獨立的聊天、記憶與工作區。
+
+## 支援的平台
+
+| 平台 | 狀態 | 備註 |
+|---|---|---|
+| macOS (Apple Silicon / Intel) | ✅ | 內含 Electron 應用程式 |
+| Linux | ✅ | 不含 Electron |
+| Windows | ❌ | 不支援 |
+
+## 安裝細節
+
+### 前置需求
+
+- macOS 13+ 或 Linux
+- [Node.js](https://nodejs.org/) 20+
+- [tmux](https://github.com/tmux/tmux)
+
+### npx (最快速)
+
+```bash
+npx purplemux
+```
+
+### 全域安裝
+
+```bash
+npm install -g purplemux
+purplemux
+```
+
+### 從原始碼執行
+
+```bash
+git clone https://github.com/subicura/purplemux.git
+cd purplemux
+pnpm install
+pnpm start
+```
+
+開發模式:
+
+```bash
+pnpm dev
+```
+
+#### 記錄層級設定
+
+整體層級以 `LOG_LEVEL` (預設 `info`) 調整。
+
+```bash
+LOG_LEVEL=debug pnpm dev
+```
+
+若只想開啟特定模組,將 `模組=層級` 組合以逗號分隔寫入 `LOG_LEVELS`。可用層級: `trace` / `debug` / `info` / `warn` / `error` / `fatal`。
+
+```bash
+# 只以 debug 追蹤 Claude Code hook 行為
+LOG_LEVELS=hooks=debug pnpm dev
+
+# 同時指定多個模組
+LOG_LEVELS=hooks=debug,status=warn pnpm dev
+```
+
+未在 `LOG_LEVELS` 中指定的模組,會沿用 `LOG_LEVEL`。
+
+## 外部連線 (Tailscale Serve)
+
+```bash
+tailscale serve --bg 8022
+```
+
+透過 `https://<machine>.<tailnet>.ts.net` 連線。停用:
+
+```bash
+tailscale serve --bg off 8022
+```
+
+## 安全性
+
+### 密碼
+
+首次連線時設定密碼。使用 scrypt 雜湊後儲存於 `~/.purplemux/config.json`。
+
+如需重置,請刪除 `~/.purplemux/config.json` 並重新啟動,引導畫面會再次出現。
+
+### HTTPS
+
+預設使用 HTTP。對外暴露時請務必套用 HTTPS:
+
+- **Tailscale Serve** — WireGuard 加密 + 自動憑證
+- **Nginx / Caddy** — 必須轉送 WebSocket 升級標頭 (`Upgrade`, `Connection`)
+
+### 資料目錄 (`~/.purplemux/`)
+
+| 檔案 | 說明 |
+|---|---|
+| `config.json` | 驗證資訊 (雜湊) 與應用設定 |
+| `workspaces.json` | 工作區配置、分頁、目錄 |
+| `vapid-keys.json` | Web Push VAPID 金鑰 (自動產生) |
+| `push-subscriptions.json` | 推播訂閱資訊 |
+| `hooks/` | 使用者自訂 hook |
+
+## 架構
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  Browser                                                    │
+│  ┌───────────┐ ┌───────────┐ ┌──────────┐ ┌─────────────┐   │
+│  │  xterm.js │ │ Timeline  │ │ Status   │ │ Multi-device│   │
+│  │  Terminal │ │           │ │          │ │ Sync        │   │
+│  └─────┬─────┘ └─────┬─────┘ └────┬─────┘ └──────┬──────┘   │
+└────────┼─────────────┼────────────┼──────────────┼──────────┘
+         │ws           │ws          │ws            │ws
+         │/terminal    │/timeline   │/status       │/sync
+         ▼             ▼            ▼              ▼
+┌─────────────────────────────────────────────────────────────┐
+│  Node.js Server (:8022)                                     │
+│  ┌──────────┐  ┌───────────────┐  ┌─────────────────────┐   │
+│  │ node-pty │  │ JSONL Watcher │  │ Status Manager      │   │
+│  │ PTY↔WS   │  │ File watch →  │  │ Process tree +      │   │
+│  │ Binary   │  │ Parse → Send  │  │ JSONL tail analysis │   │
+│  └────┬─────┘  └───────┬───────┘  └──────────┬──────────┘   │
+└───────┼────────────────┼─────────────────────┼──────────────┘
+        ▼                ▼                     ▼
+┌─────────────────────────────────────────────────────────────┐
+│  System                                                     │
+│  tmux (purple socket)         Claude Code                   │
+│  ┌────────┐ ┌────────┐       ┌────────────────────────────┐ │
+│  │Session1│ │Session2│  ...  │ ~/.claude/sessions/        │ │
+│  │ (shell)│ │ (shell)│       │ ~/.claude/projects/        │ │
+│  └────────┘ └────────┘       │   └─ {project}/{sid}.jsonl │ │
+│                              └────────────────────────────┘ │
+└─────────────────────────────────────────────────────────────┘
+```
+
+**終端機 I/O** — xterm.js 透過 WebSocket 連線至 node-pty,node-pty 再接上 tmux 工作階段。使用二進位協定處理 stdin / stdout / resize 並控制背壓。
+
+**狀態偵測** — Claude Code 事件 hook (`SessionStart`、`Stop`、`Notification`) 透過 HTTP POST 立即推送更新。每 5–15 秒輪詢一次行程樹,並分析 JSONL 檔案末尾 8KB。
+
+**時間軸** — 監聽 `~/.claude/projects/` 下的 JSONL 工作階段記錄,檔案變動時解析新行並將結構化項目串流至瀏覽器。
+
+**tmux 隔離** — 使用專屬的 `purple` socket,與現有 tmux 完全隔離。無前置鍵,無狀態列。
+
+**自動還原** — 伺服器啟動時以 `claude --resume {sessionId}` 還原先前的 Claude 工作階段。
+
+## License
+
+[MIT](LICENSE)