OpenMUX

Native macOS terminal workspace for developers.

Fast, flexible, scriptable, and terminal-first.

Website · Docs · Get Started · Configuration · Plugins · Development

---

What OpenMUX is

OpenMUX is a native macOS terminal workspace. It gives you workspaces, tabs, split panes, pane-local tab stacks, persistent shell sessions, themes, a local CLI, hooks, plugins, and extension panes.

The goal is simple: keep the terminal powerful, inspectable, and open to your workflow.

What works today

OpenMUX is a beta, but the core workflow is usable:

• native AppKit shell with a terminal-first layout
• workspaces, top-level tabs, split panes, and pane-local tabs
• persistent shell sessions with direct typing, paste, resize, command injection, and bounded scrollback restore
• local omux CLI and JSON-RPC control plane
• external hook system, official hook registry, and omux events
• fuzzy-search theme picker and token-based themes
• plugin command discovery, extension panes, native menu contributions, and official plugin registry
• explicit keyboard-correctness work for ISO layouts, Option behavior, dead keys, compose input, and IME-sensitive flows

Start here

Quick install from the latest GitHub Release:

curl -fsSL https://github.com/finger-gun/omux/releases/latest/download/openmux-install.sh | bash

User docs:

• Getting started - install, first launch, CLI setup, workspaces, panes, themes, hooks, plugins, and the release installer script.
• Configuration and themes - ~/.omux/config.toml, themes, terminal settings, keybindings, and plugin config.
• Hooks - executable user hooks, registry installs, hook payloads, and automation examples.
• Plugins - bundled plugins, registry installs, and plugin management.
• Plugin ecosystem - how to create external plugin commands, extension panes, and menu contributions.

Contributor docs:

• Developer quick start - local setup, Makefile workflow, and validation commands.
• Development notes - module boundaries and runtime bridge details.
• Releasing - package and GitHub Release flow.
• Manifesto - product principles and architectural guardrails.

Common user commands

Install the bundled CLI from the app:

/Applications/OpenMUX.app/Contents/MacOS/omux install-cli

Then use it to control the running app:

omux help
omux open ~/projects/my-project
omux list --full
omux split right
omux run --focused -- "git status"
omux theme
omux plugins
omux events

The CLI talks to the running app over a local Unix socket. UI actions and CLI commands target the same live workspaces and shell sessions.

Configuration

OpenMUX stores user configuration in:

~/.omux/config.toml

Create a starter config:

omux config init
omux config doctor
omux config open
omux config reload

User-owned files live under ~/.omux/:

Path	Purpose
~/.omux/config.toml	User configuration.
~/.omux/themes/	Custom themes.
~/.omux/hooks/	User hook handlers.
~/.omux/plugins/	External plugin commands.
~/.omux/installed/	Receipts for registry-installed hooks and plugins.
~/.omux/generated/ghostty/	OpenMUX-managed generated terminal config.

Plugins

OpenMUX has two plugin and automation surfaces:

1. Bundled plugins can be toggled with omux plugins.
2. User plugins are executable commands discovered from ~/.omux/plugins/.

Plugins can create extension panes with omux extension-pane, listen through hooks, call back into the public CLI, and contribute native menu items. Hooks are executable event handlers under ~/.omux/hooks/.

Official registries:

Registry	Repository
Hooks	https://github.com/finger-gun/omux-hooks
Plugins	https://github.com/finger-gun/omux-plugins

Discover registry packages with omux hooks discover and omux plugins discover. See Hooks for the hook system, Plugin ecosystem for the plugin contract, and Plugin index for bundled and registry-hosted plugins.

Status

OpenMUX is in beta. The foundations are in place, but some areas are still evolving: runtime transcript quality, layout restore polish, pane-stack ergonomics, plugin capabilities, and release packaging.

For current direction, see Roadmap.

Contributing

Please read Developer quick start, Development notes, CONTRIBUTING, and CODE OF CONDUCT before opening a pull request.

License

OpenMUX is released under Apache-2.0. See LICENSE.

---

Build your terminal workspace, not someone else's.

openmux.fingergun.dev · A Finger Gun project.