OpenMUX

Native macOS terminal workspace for developers.

Fast, flexible, scriptable, and terminal-first.

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

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, bundled plugins, registry-installed plugins, and extension panes.

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

OpenMUX is built for developers who want a terminal workspace that stays native, scriptable, and inspectable instead of turning into a browser shell or a closed workflow product.

• Terminal first: workspaces, split panes, pane-local tabs, shell history isolation, bounded scrollback restore, and keyboard-first navigation are core product behavior.
• Open by design: the local omux CLI, JSON-RPC control plane, hooks, and event stream are public surfaces, not private implementation details.
• AI-friendly, not AI-first: OpenMUX includes local agent tooling and Agent Sessions, but the terminal remains the product and automation remains user-controlled.
• Native and hackable: the app shell is AppKit-first, plugin and hook surfaces are plain local executables, and user-owned configuration stays in ~/.omux/.

OpenMUX is still in beta, but the main features are already broad and stable.

Quick install from the latest GitHub Release:

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

This installs OpenMUX.app and links the bundled omux CLI at ~/.local/bin/omux.

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, local agent settings, and plugin config.
• Agent Sessions - search, resume, monitor, and delete locally indexed coding-agent sessions from built-in and plugin-provided adapters.
• 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.

If you installed the app without the CLI, link the bundled command 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 agent
omux agent -p "Summarize README.md into a short next-action list for a new contributor."
omux theme
omux agent-sessions open
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.

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/:

OpenMUX has two plugin and automation surfaces:

1. Bundled plugins, such as Markdown Preview and AI Status, 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/.

omux agent is a local assistant for quick automation, repo inspection, and simple OpenMUX control.

• Modes: omux agent opens an ephemeral full-screen REPL by default. Use omux agent -p "..." for one-shot mode that prints a single plain-text response to stdout; non-interactive use requires -p.
• Interactive features: The REPL supports multi-turn chat, streaming output, inline tool activity, status/footer telemetry, and host-handled slash commands such as /help, /tools, /stats, /compact, /handoff, and /exit.
• File, history, and plugin access: Both modes can read recent terminal history from OpenMUX, run non-interactive omux subcommands through built-in tools, read or grep files under the current working directory, and load plugin-defined tools from installed manifest plugins.
• Flags and security: Use --verbose to print progress such as session startup and tool calls to stderr. Use --allow-read-anywhere to let the read-file tool open any readable local path; grep remains scoped to the current working directory. Use --enabled-tools read_file,agenttools.webpage or --enabled-tools none to narrow tools for one invocation. External plugin-defined agent tools default to a 120-second host timeout, configurable with [agent].external_tool_timeout_seconds.

Official registries:

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.

Registry-hosted Agent Sessions plugins can extend support beyond the bundled adapters. Current examples include OpenCode, KiloCode, and OMP.

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.

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

OpenMUX is released under Apache-2.0. See LICENSE.