Claude Code and Codex, many tasks at once. Faster.
Every session on a single screen. Uninterrupted, even on your phone.
English | 简体中文
npx purplemux@latestOpen http://localhost:8022 in your browser. Done.
Requires Node.js 20+ and tmux. macOS or Linux.
Prefer a native app? Grab the macOS Electron build from the latest release (.dmg for Apple Silicon & Intel).
Deploying from source (agent-friendly guide): see DEPLOYMENT.md.
- Multi-session dashboard — See working/needs-input status for every Claude Code, Codex, Pi, and omp session at a glance
- Pi & omp support — Native panels for pi-coding-agent and Oh My Pi; chat timelines, session lists, countdown timers, and
--resume/--sessionrelaunch all work in-tab - Session-follows-tab — Switch tabs and the chat pane immediately shows the right session; in-app
/resume(TUI, no cmdline args) is tracked viasession_before_switchhooks, and session detection prefers explicit flags over cwd heuristics - Rate limit monitoring — 5-hour / 7-day remaining usage with reset countdown
- Push notifications — Desktop and mobile alerts when a task finishes or needs input
- Mobile & multi-device — Reach the same session from a phone, tablet, or another desktop
- Live session view — No more scrolling CLI output. Progress is organized as a timeline
Plus
- Uninterrupted sessions — Built on tmux. Close the browser and everything stays put. Reconnect and your tabs, panels, and directories are exactly where you left them
- Self-hosted & open source — Code and session data never leave your machine. No external servers
- Encrypted remote access — HTTPS from anywhere via Tailscale
The official Remote Control focuses on single-session remote control. Use purplemux when you need multi-session management, push notifications, and persistent sessions.
- Split panels — Horizontal / vertical splits, drag to resize
- Tab management — Multiple tabs, drag to reorder, auto titles from process names
- Keyboard shortcuts — Splits, tab switching, focus movement
- Terminal themes — Dark / light mode, multiple color themes
- Workspaces & groups — Save and restore panel layouts, tabs, and working directories. Organize workspaces into groups with drag-and-drop
- Git workflow — Side-by-side / line-by-line diff with syntax highlighting, inline hunk expansion, and a paginated history tab. Fetch / pull / push from the panel with ahead/behind indicators — if sync fails (dirty worktree, conflicts), Ask Claude or Codex in one click
- Web browser panel — Embedded browser for checking dev output (Electron). Drive it from the
purplemuxCLI and switch viewports with a built-in device emulator - Agent tabs — Start Claude, Codex, or a combined session list from the new-tab menu
- Real-time status — Working / needs-input indicators with session switching
- Live session view — Messages, tool calls, tasks, permission prompts, thinking blocks
- Codex tabs — Launch Codex CLI sessions with the same tmux-backed persistence as Claude
- Session list — Browse and resume recent Claude and Codex sessions from one combined view
- One-click resume — Restart a paused Claude or Codex session directly from the browser
- Auto resume — Recover previous Claude sessions on server start
- Quick prompts — Register frequently used prompts and send with one click
- Attachments — Drop images into the chat input, or attach files to insert their paths. Works on mobile
- Message history — Reuse previous messages
- Usage analytics — Claude + Codex tokens, cost, per-project breakdowns, and daily AI reports
- Rate limits — 5-hour / 7-day remaining usage with reset countdown for supported providers
purplemux can attach to a Codex runtime started by GPTWork instead of creating a second Codex process. Set GPTWork to use the tmux transport:
GPTWORK_CODEX_TUI_TRANSPORT=tmuxBoth applications use the isolated tmux -L purple server. GPTWork writes a manifest under .gptwork/codex-sessions/manifests/; when purplemux opens the matching pt-gptwork-* session, it reads the native Codex session binding and attaches to the existing PTY. The native history remains in ~/.codex/sessions/**/*.jsonl.
GPTWork and purplemux may both send prompts or corrections. A shared filesystem lease serializes each short write so input cannot interleave; it does not assign exclusive ownership to either application. If the browser disconnects or GPTWork restarts, the next client reattaches the persisted tmux session. purplemux does not run codex resume for an existing binding, and removing a shared tab does not kill GPTWork's tmux session. New GPTWork TUI flows create no subagents unless the task entrypoint or user prompt explicitly requests them.
See docs/SHARED-CODEX.md for the setup and troubleshooting flow.
- Responsive UI — Terminal and timeline on phones and tablets
- PWA — Add to home screen for a native-app feel
- Web Push — Receive notifications even after closing the tab
- Multi-device sync — Workspace changes reflected in real time
- Tailscale — HTTPS access from outside via a WireGuard-encrypted tunnel
- Password authentication — scrypt hashing, safe even when exposed externally
- Multilingual — 11 languages including 한국어, English, 日本語, 中文
| Platform | Status | Notes |
|---|---|---|
| macOS (Apple Silicon / Intel) | ✅ | Electron app included |
| Linux | ✅ | No Electron |
| Windows | ❌ | Not supported |
Required for Claude tabs. Install Claude Code and sign in before starting a Claude tab:
curl -fsSL https://claude.ai/install.sh | bash
# or, with Homebrew latest channel
brew install --cask claude-code@latestOptional for Codex tabs. Install Codex CLI and sign in before starting a Codex tab:
npm i -g @openai/codex
# or
brew install --cask codexnpx purplemux@latestnpm install -g purplemux
purplemuxpurplemux tab create -w WS -t codex-cli -n "fix auth"
purplemux tab create -w WS -t agent-sessionsgit clone git@github.com:9018/purplemux.git
cd purplemux
pnpm install
pnpm startDevelopment mode:
pnpm devSet the overall level with LOG_LEVEL (default info).
LOG_LEVEL=debug pnpm devTo enable specific modules only, list module=level pairs in LOG_LEVELS, separated by commas. Available levels: trace / debug / info / warn / error / fatal.
# Trace only Claude Code hook behavior at debug
LOG_LEVELS=hooks=debug pnpm dev
# Multiple modules at once
LOG_LEVELS=hooks=debug,status=warn pnpm devModules not listed in LOG_LEVELS fall back to LOG_LEVEL.
tailscale serve --bg 8022Access at https://<machine>.<tailnet>.ts.net. To disable:
tailscale serve --bg off 8022Set a password on first access. It is hashed with scrypt and stored in ~/.purplemux/config.json.
To reset, delete ~/.purplemux/config.json and restart — the onboarding screen will appear again.
The default is HTTP. Always use HTTPS when exposing the app externally:
- Tailscale Serve — WireGuard encryption with automatic certificates
- Nginx / Caddy — Must forward WebSocket upgrade headers (
Upgrade,Connection)
| File | Description |
|---|---|
config.json |
Authentication (hashed) and app settings |
workspaces.json |
Workspace layouts, tabs, directories |
vapid-keys.json |
Web Push VAPID keys (auto-generated) |
push-subscriptions.json |
Push subscription data |
hooks/ |
User-defined hooks |
┌─────────────────────────────────────────────────────────────┐
│ 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) Agent CLIs │
│ ┌────────┐ ┌────────┐ ┌────────────────────────────┐ │
│ │Session1│ │Session2│ ... │ Claude Code │ │
│ │ (shell)│ │ (shell)│ │ ~/.claude/projects/*.jsonl │ │
│ └────────┘ └────────┘ │ Codex │ │
│ │ ~/.codex/sessions/*.jsonl │ │
│ └────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
Terminal I/O — xterm.js connects to node-pty via WebSocket; node-pty attaches to tmux sessions. A binary protocol handles stdin/stdout/resize with backpressure control.
Status detection — Agent event hooks deliver instant updates via HTTP POST. Claude Code uses SessionStart, Stop, and Notification; Codex uses SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop, and PermissionRequest. Polling every 5–15s inspects process trees and analyzes the last 8KB of JSONL files.
Timeline — Watches JSONL session logs under ~/.claude/projects/ and ~/.codex/sessions/, parses new lines on change, and streams structured entries to the browser.
tmux isolation — Uses a dedicated purple socket, completely separate from your existing tmux. No prefix key, no status bar.
Auto recovery — On server start, restores previous Claude sessions via claude --resume {sessionId}. Codex sessions can be resumed from the session list or with codex resume {sessionId}.