{"id":34694781,"url":"https://github.com/monotykamary/openmux","last_synced_at":"2026-04-30T07:00:54.894Z","repository":{"id":328506588,"uuid":"1111726709","full_name":"monotykamary/openmux","owner":"monotykamary","description":"A simpler multiplexer, built with OpenTUI.","archived":false,"fork":false,"pushed_at":"2026-04-26T20:21:44.000Z","size":7585,"stargazers_count":73,"open_issues_count":1,"forks_count":8,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-04-26T22:09:01.291Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/openmux","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/monotykamary.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-12-07T14:22:00.000Z","updated_at":"2026-04-26T20:21:49.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/monotykamary/openmux","commit_stats":null,"previous_names":["monotykamary/openmux"],"tags_count":280,"template":false,"template_full_name":null,"purl":"pkg:github/monotykamary/openmux","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/monotykamary%2Fopenmux","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/monotykamary%2Fopenmux/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/monotykamary%2Fopenmux/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/monotykamary%2Fopenmux/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/monotykamary","download_url":"https://codeload.github.com/monotykamary/openmux/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/monotykamary%2Fopenmux/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32457110,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-29T22:27:22.272Z","status":"online","status_checked_at":"2026-04-30T02:00:05.929Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-12-24T22:31:22.143Z","updated_at":"2026-04-30T07:00:54.832Z","avatar_url":"https://github.com/monotykamary.png","language":"TypeScript","funding_links":[],"categories":["Table of Contents"],"sub_categories":[],"readme":"# openmux\n\n[![GitHub Release](https://img.shields.io/github/v/release/monotykamary/openmux)](https://github.com/monotykamary/openmux/releases)\n[![codecov](https://codecov.io/gh/monotykamary/openmux/graph/badge.svg)](https://codecov.io/gh/monotykamary/openmux)\n\nA terminal multiplexer with master-stack layout (Zellij-style), built with:\n\n- **Bun** - Fast JavaScript runtime\n- **OpenTUI** - Terminal UI library with SolidJS reconciler\n- **SolidJS** - Reactive UI framework\n- **zig-pty** - PTY support for Bun (pure Zig implementation)\n- **libghostty-vt** - Native terminal emulation (VT parser/state)\n\n![openmux screenshot](assets/openmux-screenshot.png)\n\n## Features\n\n- Master-stack tiling layout (like Zellij)\n- i3-gaps style gaps and borders\n- Vim-style `hjkl` navigation\n- Tmux-style `Ctrl+b` prefix key\n- 9 workspaces with isolated pane layouts\n- Session persistence and management\n- Detach/attach (leave sessions running in background)\n- Pane zoom (fullscreen focused pane)\n- Aggregate view for browsing/filtering PTYs across workspaces\n- Mouse tracking (click to focus, tabbed pane switching)\n- Scrollback support with mouse wheel and scrollbar\n- Kitty graphics protocol support (image rendering, pixel sizing, SSH-aware offloading)\n\n## Installation\n\n\u003e ⚠️ **Important Update Note for v0.3.0 Users**\n\u003e \n\u003e openmux v0.3.0 contains a quirky bug that prevents `openmux update` from working correctly.\n\u003e If you're on v0.3.0, please update manually using one of the following methods:\n\u003e\n\u003e ```bash\n\u003e # Option 1: Reinstall via install script\n\u003e curl -fsSL https://raw.githubusercontent.com/monotykamary/openmux/main/scripts/install.sh | bash\n\u003e\n\u003e # Option 2: Update via package manager\n\u003e bun update -g openmux\n\u003e # or\n\u003e npm update -g openmux\n\u003e ```\n\n### Quick Install (curl)\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/monotykamary/openmux/main/scripts/install.sh | bash\n```\n\n### npm / bun\n\n```bash\nnpm install -g openmux\n# or\nbun add -g openmux\n```\n\n### From Source\n\n```bash\ngit clone https://github.com/monotykamary/openmux.git\ncd openmux\nbun install\nbun run build --install\n```\n\n### GitHub Releases\n\nDownload prebuilt binaries from [GitHub Releases](https://github.com/monotykamary/openmux/releases).\n\nAvailable platforms:\n\n- macOS (Apple Silicon)\n- Linux (x64 / arm64)\n\n## Usage\n\n```bash\nopenmux\n```\n\nFor development:\n\n```bash\nbun start      # Run from source\nbun dev        # Run with watch mode\n```\n\n## CLI\n\nopenmux ships a headless-style CLI that talks to the running UI for pane/layout\noperations and uses on-disk session metadata for session listing/creation.\n\n```bash\nopenmux --help\nopenmux pane --help\nopenmux pane capture --help\n```\n\nExamples:\n\n```bash\nopenmux session list --json\nopenmux session create dev\nopenmux attach --session dev\nopenmux update\nopenmux update --yes\nopenmux pane split --direction vertical --workspace 2\nopenmux pane send --pane focused --text \"npm test\\n\"\nopenmux pane capture --pane focused --lines 200 --format ansi\n```\n\nNotes:\n\n- Pane commands require a running UI (control socket available).\n- `pane send` supports C-style escapes like `\\n`, `\\t`, `\\xNN`, `\\uXXXX`.\n- See [`docs/guides/cli.md`](docs/guides/cli.md) for the full spec and exit codes.\n\n## Architecture (High Level)\n\n```\n┌─────────────────────────┐\n│  Host Terminal (TTY)    │\n└────────────┬────────────┘\n             │ input/output\n             v\n┌─────────────────────────┐\n│ openmux UI (client)     │  Solid + OpenTUI\n└────────────┬────────────┘\n             │ shim protocol (detach/attach)\n             v\n┌─────────────────────────┐\n│ shim server (background)│\n└────────────┬────────────┘\n             │ PTY I/O + emulation\n             v\n┌─────────────────────────┐\n│ zig-pty + libghostty-vt │\n└─────────────────────────┘\n```\n\n## Keyboard Shortcuts\n\n### Normal Mode (Alt shortcuts - no prefix needed)\n\n- `Alt+h/j/k/l` - Navigate panes\n- `Alt+m` - Enter move mode\n- `Alt+n` - New pane\n- `Alt+s` - Open session picker\n- `Alt+t` - Open template overlay\n- `Alt+g` - Open aggregate view (browse all PTYs)\n- `Alt+f` - Open search\n- `Alt+p` - Open command palette\n- `Alt+[` / `Alt+]` - Cycle layout mode (vertical → horizontal → stacked)\n- `Alt+z` - Toggle zoom (fullscreen focused pane)\n- `Alt+x` - Close pane\n- `Alt+-` - Split pane horizontally\n- `Alt+\\` - Split pane vertically\n- `Alt+1-9` - Switch to workspace 1-9\n\n### Mouse\n\n- `Click` - Focus pane\n- `Click tab` - Switch to stacked pane (in stacked mode)\n- `Scroll wheel` - Scroll through terminal history (when not in alternate screen apps like vim)\n- `Click scrollbar` - Jump to position in scrollback\n- `Drag scrollbar` - Scroll through history by dragging\n\n### Prefix Mode (Ctrl+b, 2s timeout)\n\n- `1-9` - Switch to workspace 1-9\n- `n` or `Enter` - New pane\n- `h/j/k/l` - Navigate panes\n- `m` - Enter move mode\n- `\\` - Split pane vertically\n- `-` - Split pane horizontally\n- `v` - Set layout mode: vertical\n- `H` - Set layout mode: horizontal\n- `t` - Set layout mode: stacked (tabbed)\n- `T` - Open template overlay\n- `x` - Close pane\n- `z` - Toggle zoom\n- `s` - Open session picker\n- `g` - Open aggregate view (browse all PTYs)\n- `/` - Open search\n- `:` - Open command palette\n- `]` or `p` - Paste from clipboard\n- `` ` `` - Toggle console overlay\n- `q` - Quit openmux\n- `d` - Detach (leave session running in background)\n- `Esc` - Exit prefix mode\n\n### Move Mode\n\n- `h/j/k/l` - Move focused pane west/south/north/east\n- `Esc` - Exit move mode\n\n### Search Mode\n\n- `Ctrl+n` - Next match\n- `Ctrl+p` - Previous match\n- `Enter` - Confirm selection and jump\n- `Esc` - Cancel search\n- `Backspace` - Delete last character\n\n### Command Palette\n\n- `↑` / `↓` - Navigate commands\n- `Enter` - Execute selected command\n- `Esc` - Close command palette\n- `Backspace` - Delete last character\n\n### Template Overlay\n\n**Apply Tab:**\n- `↑` / `↓` - Navigate templates\n- `Enter` - Apply selected template\n- `Tab` - Switch to save tab\n- `Ctrl+x` / `Ctrl+d` - Delete template\n- `Esc` - Close overlay\n\n**Save Tab:**\n- `Enter` - Save current layout as template\n- `Tab` - Switch to apply tab\n- `Backspace` - Delete last character\n- `Esc` - Close overlay\n\n### Aggregate View\n\n**List:**\n- `↑` / `↓` - Navigate PTYs\n- `Enter` - Preview selected PTY\n- `Tab` - Jump to selected PTY and close view\n- `Alt+a` - Toggle scope (all workspaces vs current)\n- `Alt+x` - Kill selected PTY\n- `Backspace` - Delete last filter character\n- `Alt+Esc` - Close aggregate view\n\n**Preview:**\n- `Alt+Esc` - Return to list\n- `Alt+f` - Open search in preview\n- `Alt+x` - Kill current PTY\n- Full keyboard/mouse support for terminal interaction\n\n**Search (in preview):**\n- `Ctrl+n` - Next match\n- `Ctrl+p` - Previous match\n- `Enter` - Jump to match\n- `Esc` - Exit search\n- `Backspace` - Delete last character\n\n**Prefix (in preview):**\n- `q` - Quit openmux\n- `d` - Detach\n- `Esc` - Return to list\n- `/` - Open search\n\n### Session Picker\n\n**List Tab:**\n- `↑` / `↓` - Navigate sessions\n- `Enter` - Select or create session\n- `Ctrl+n` - Create new session\n- `Ctrl+r` - Rename session\n- `Ctrl+x` / `Ctrl+d` - Delete session\n- `Backspace` - Delete last filter character\n- `Esc` - Close picker\n\n**Rename Tab:**\n- `Enter` - Confirm new name\n- `Esc` - Cancel rename\n- `Backspace` - Delete last character\n\n### Confirmation Dialog\n\n- `h` / `←` or `l` / `→` - Focus confirm/cancel\n- `Tab` - Toggle between confirm/cancel\n- `Enter` - Confirm\n- `Esc` - Cancel\n\n### Vim Mode (Overlays, opt-in)\n\nEnable via the command palette (\"Toggle overlay vim mode\"), or in `config.toml`:\n\n```toml\n[keyboard]\nvimMode = \"overlays\"\nvimSequenceTimeoutMs = 1000\n```\n\nWhen enabled, overlays open in normal mode:\n\n- `j/k` - Navigate lists\n- `gg` / `G` - Jump to first/last item\n- `Enter` - Confirm/preview\n- `q` - Close overlay\n- `i` - Enter insert mode\n- `Esc` - Return to normal mode\n- Search overlays: `n` / `N` for next/prev match\n\n## Concepts\n\n### Why openmux (vs tmux / zellij)\n\n- **Single-client steal/lock**: predictable attach semantics; new client wins and old client detaches.\n- **UI binary swap**: update the UI without touching running PTYs (shim stays alive).\n- **UI-first architecture**: SolidJS/OpenTUI enables richer overlays and layout evolution.\n- **PTY state snapshots**: fast attach with immediate state restore (no full redraw pipeline).\n- **Emulator ownership**: aggregate previews, scrollback caching, and search are first-class.\n- **Lower client CPU**: shim does emulation; client focuses on rendering updates.\n\n### Workspaces\n\nLike i3/sway, openmux supports multiple workspaces (1-9). Each workspace has its own layout tree of panes. The status bar shows populated workspaces dynamically - empty workspaces don't appear unless active.\n\n### Layout Modes (Zellij-style)\n\nEach workspace has a layout mode that determines how panes are arranged:\n\n- **Vertical** (`│`): Main pane on left, stack panes split vertically on right\n- **Horizontal** (`─`): Main pane on top, stack panes split horizontally on bottom\n- **Stacked** (`▣`): Main pane on left, stack panes tabbed on right (only active visible)\n\n### Sessions\n\nSessions persist your workspace layouts and pane working directories. Sessions are auto-saved to `~/.config/openmux/sessions/` and can be switched via the session picker (`Alt+s` or `Ctrl+b` then `s`).\n\n### Configuration\n\nopenmux loads `~/.config/openmux/config.toml` (or `$XDG_CONFIG_HOME/openmux/config.toml`). If the file is missing, a full default config is generated on startup. Deleting the file and restarting openmux will regenerate it.\n\nConfig changes are hot-reloaded while openmux is running (layout, theme, and keybindings update live).\n\nSee [`docs/guides/config.md`](docs/guides/config.md) for the full generated config.\n\nEnvironment variables override the config file for layout values:\n\n- `OPENMUX_WINDOW_GAP`\n- `OPENMUX_MIN_PANE_WIDTH`\n- `OPENMUX_MIN_PANE_HEIGHT`\n- `OPENMUX_STACK_RATIO` (maps to `layout.defaultSplitRatio`)\n\nTo unbind a keybinding, set its value to `null` or `\"unbind\"`.\n\n### Detach / Attach\n\nUse `Ctrl+b d` to detach and leave the background shim running. Reattach by launching `openmux` again. Detach/attach uses a single-client lock; a new client steals the lock and the previous client detaches.\n\n### Aggregate View\n\nA fullscreen overlay (`Alt+g` or `Ctrl+b` then `g`) that lets you browse all PTYs across all workspaces in one place. Features:\n\n- **Card-style PTY list** showing directory, process name, and git branch\n- **Interactive terminal preview** with full input support (keyboard + mouse)\n- **Filter by typing** to search by process name, directory, or git branch\n- Navigate with arrow keys (or `j/k` in overlay vim mode), `Enter` to interact, `Prefix+Esc` to return to list\n\n## Development Status\n\nCurrent status:\n\n- [x] Master-stack layout with gaps\n- [x] OpenTUI component layer\n- [x] Keyboard navigation system\n- [x] PTY integration\n- [x] libghostty-vt native terminal emulation\n- [x] Workspaces (1-9)\n- [x] Layout modes (vertical/horizontal/stacked)\n- [x] Session persistence\n- [x] Pane zoom\n- [x] Mouse support\n- [x] Scrollback support\n- [x] Aggregate view (PTY browser)\n- [x] Attach/detach (steal + lock)\n- [x] Configurable keybindings\n- [x] Configurable settings and colors\n- [x] Kitty graphics protocol support\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmonotykamary%2Fopenmux","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmonotykamary%2Fopenmux","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmonotykamary%2Fopenmux/lists"}