awesoMux

Who & Why

awesoMux is a native macOS 15+ terminal built with Swift and SwiftPM. It combines vertical sidebar tabs with agent-aware session UX in a single-window native app.

Architecture (summary)

• Stack: Swift + AppKit/SwiftUI on macOS 15+, libghostty C API for the terminal backend (linked via GhosttyKit + GhosttyKitLinker; build artifacts staged under .build/ghostty).
• Layout: SwiftPM executable awesoMux, AwesoMuxCore for testable session/agent logic, DesignSystem for shared UI surfaces, GhosttyKit modulemap/shim pointing at packaged Ghostty headers/libs.
• Window model: single window, vertical sidebar of sessions/tabs.
• Persistent sessions: the bundled amx backend, built from Interactive-Buffoonery/zmx, our fork of neurosnap/zmx (MIT).
• Agent surface: We currently support Claude Code, Codex, OpenCode, Pi, and Grok. Don't see your agent? Feel free to open a request or a PR. See CONTRIBUTING.md.
• License: MIT.

Full target diagram, persistence, and agent/notification model: docs/architecture.md. Keyboard reference: docs/shortcuts.md. Managed Linux SSH destinations offer to install a static helper for activity and file handoffs: docs/remote-linux-helper.md. Named remote sessions need amx or zmx on the remote host: docs/remote-session-persistence.md.

Managed SSH programs that honor BROWSER can open web links in your Mac’s default browser after confirmation. Setup, permissions, and limits: Remote browser forwarding.

Named agent setups

Settings > Agents lets you save multiple named launch setups for each provider. Choose an absolute executable path and add each literal argument separately; use a wrapper executable for environment variables or credentials, and keep secrets out of the saved arguments. Enabled setups appear in the command palette and open a new tab in the active local pane's directory. Reorder, disable, or remove setups without changing the provider's shared local status hook.

Setup launches support sh, bash, zsh, dash, ksh, and fish. Remote panes and remote default workspace groups are rejected because these paths refer to local files. The current directory must pass the existing startup directory checks, including user ownership. Launches require shell integration and the default Ghostty confirm-close-surface = true setting to detect when the prompt is ready. Wrappers should launch the real provider executable so its existing runtime recognition and status hooks continue to identify the provider.

Markdown document panes

awesoMux can open local Markdown files right next to your terminal, so you can read, review, and mark up notes without losing sight of the agent doing the work.

Remote Markdown links open read-only snapshots over OpenSSH. Declared SSH panes use their declared destination and managed connection. A relative terminal link asks you to choose a remote base directory or enter a full /… or ~/… path; the app does not infer a trustworthy remote directory from the local daemon.

In an ordinary terminal running SSH, choose an independent file-read alias from ~/.ssh/config and confirm the exact destination and resolved path. This reads one file without converting the terminal into a managed workspace. Terminal SSH flags, nested connections, and wrappers are not recreated. OpenSSH owns credentials; the app does not request or store them. Every later Refresh, Markdown link, or new file read requires another confirmation.

For filenames in ordinary SSH output, use File → Set Remote File Context… (also in the command palette). Choose an OpenSSH config alias, an optional user, and a fixed /… or ~/… project directory. The path bar displays Remote files: destination · directory, with Edit and Clear controls. Setting it makes no connection. Click a Markdown filename to read a snapshot after confirming the exact destination and resolved path. Bare filenames do not gain a hover underline. The chosen directory stays fixed: an unobserved remote cd or nested SSH command cannot update it, so edit the context when either changes. Context is runtime-only and is not inherited by restored, reopened, duplicated, or split panes.

Restored remote Markdown shows the saved copy until you click Refresh. To fetch declared snapshots automatically over SSH at launch, enable Settings → General → Refresh remote Markdown on launch (off by default). Automatic refresh reuses snapshots written less than a minute ago; Refresh always fetches. Snapshots requiring confirmation always restore from cache, even when launch refresh is enabled.

Markdown panes are meant to support the terminal, not replace it: each workspace still keeps at least one terminal pane open. You can open .md and .markdown files up to 2 MiB.

Entry points:

• File > Open Markdown File… (⌘O) opens a file panel seeded from the active pane's working directory when available.
• The command palette exposes the same Open Markdown File… command.
• View Files in the command palette opens the Markdown browser in the existing document panel, or creates that right-hand panel from a local terminal.
• Local Markdown links from terminal output, and Markdown links clicked inside another document pane, route back into awesoMux as document panes.

The review workflow is file-backed. A document can carry one whole-document note plus any number of inline annotations. Selecting rendered text and adding an inline annotation writes a <mark>...</mark><!-- AMX id=... by=... --> marker pair into the Markdown file; the whole-document note is one own-line AMX marker. awesoMux renders the highlight and comment in the pane and live reloads when the file changes. Send to Agent stages a plain-English nudge in the adjacent terminal prompt without pressing Return for you; the user reviews and sends it. An agent resolves an annotation by setting status=resolved, which keeps the marker in the file so the change stays verifiable. Legacy USER COMMENT markers are still readable and keep their original remove-on-complete lifecycle. See docs/plan-annotations.md for the full marker grammar, intents, and threaded replies.

Install

Requires macOS 15+ on Apple Silicon. Releases are Developer ID signed and notarized.

brew tap interactive-buffoonery/tap
brew install --cask awesomux

Or grab the latest awesoMux-<version>.dmg from Releases, open it, and drag awesoMux.app to Applications. Download the matching .sha256 file and verify the DMG before opening it:

VERSION=0.14.0
shasum -a 256 -c "awesoMux-$VERSION.dmg.sha256"

Getting started

Want to help us develop awesoMux? Here's how you can get started:

git clone --recursive https://github.com/Interactive-Buffoonery/awesomux.git
cd awesomux

If you cloned without submodules:

git submodule update --init --recursive

To create an isolated feature branch and worktree, initialize its submodules, and launch an agent TUI from it:

./script/new-worktree.sh

The script prompts for a branch name and your choice of Pi, Claude Code, Codex, OpenCode, or Grok, then creates the checkout under the sibling awesomux-worktrees directory. Pass the branch and TUI directly for non-interactive use, or add --no-launch to prepare the worktree without starting an agent:

./script/new-worktree.sh --tui codex feature/my-change
./script/new-worktree.sh --no-launch feature/my-other-change

Host tools: zig must be on PATH the first time (or anytime) Ghostty libraries need to be built; script/build_ghostty_xcframework.sh drives that step. Xcode's Metal Toolchain must also be installed so Ghostty can compile its Metal shaders:

xcodebuild -downloadComponent MetalToolchain

If Xcode exposes the downloaded compiler through a separate Metal toolchain, the Ghostty build script selects it automatically.

SwiftPM builds and bundles the macOS app (no Xcode project required for daily dev):

./script/build_and_run.sh

The script builds Ghostty artifacts when missing, runs swift build, stages dist/awesoMux.app, copies Ghostty share resources into the bundle, ad-hoc signs, and launches the app. To replace the local daily-driver copy in ~/Applications and launch that installed bundle:

./script/build_and_run.sh --install

For terminal color/theme regressions, run the gated diagnostic launch, install the current bundle, and then capture a probe from inside the installed app:

./script/build_and_run.sh --terminal-diagnostics
./script/build_and_run.sh --install
script/terminal-color-probe.sh --label awesomux-installed-open --claude

The diagnostic loop is documented in docs/debugging/terminal-color-diagnostics.md. Ghostty integration notes live in docs/ghostty-integration.md.

Default keyboard shortcuts (workspace, panes, floating panel) are listed in docs/shortcuts.md. Release planning and checklists live in docs/releasing.md.

Local preflight

awesoMux uses a local preflight before merging. Run it before pushing or merging app changes:

./script/preflight.sh

For a headless session, ./script/preflight.sh --checks-only runs every guard and test while omitting the final staged-app build, signing, and launch verification. Report it as checks-only validation, with native verification still pending. The full gate remains ./script/preflight.sh.

If you do not run this before opening a PR, please note that in your PR.

To run the tests without the rest of the preflight:

./script/test.sh all                          # zmx plus the full Swift suite
./script/test.sh zmx                          # the vendored zmx unit suite
./script/swift-test.sh --filter SomeTests     # one suite, by type name

./script/test.sh all takes no other arguments — it routes the full run through the zmx suite and isolated Swift shards so it cannot stall on the libdispatch thread limit. Run zmx through this wrapper instead of passing a relative vendor/zmx/build.zig path to Zig 0.16; that form gives translate-c a relative build root and aborts before compilation.

--filter matches Swift identifiers — a suite's type name or a test's function name — and not the display strings in @Suite("…") or @Test("…"). So --filter AboutWindowInfoTests and --filter creditNamesUnique both work, while --filter "Credit names are unique" matches nothing. On the pinned toolchain a filter that matches nothing prints warning: No matching test cases were run, reports 0 tests, and still exits 0 — so a typo'd filter looks exactly like a pass. Check the reported test count, not the exit status.

The preflight runs the fast source, formatting, licensing, and automation guards, then the full zmx and Swift test suite (./script/test.sh all), followed by a build that stages, ad-hoc signs, and launch-verifies dist/awesoMux.app. Maintainers can request advisory hosted native validation for an exact pull-request SHA with /ci; the full local preflight remains the strongest pre-PR gate. Required checks, native scopes, trust boundaries, and troubleshooting are documented in docs/ci.md.

Format only the Swift files you intentionally changed, then inspect the diff:

./script/format.sh Sources/AwesoMuxCore/Example.swift Tests/AwesoMuxCoreTests/ExampleTests.swift
git diff --check
./script/format.sh --lint

The wrapper excludes vendored and generated sources. Write mode requires explicit first-party file paths and rewrites only the lines those files changed from the base ref — a file with no tracked history is formatted whole, and one with no changed lines is left untouched. --lint does not modify files and reports formatter findings on the same changed lines. Both modes use merge-base origin/main HEAD, or the FORMAT_LINT_BASE override CI sets. Swift and swift-format versions are pinned and their update procedure is documented in docs/toolchain.md.

You can also run the contrast gate alone when iterating on design-system tokens or sidebar chrome:

./script/swift-test.sh --filter SidebarTintContrastTests

Maintainers can manually run this focused test on macOS via .github/workflows/tint-contrast.yml. Pull requests do not allocate a native runner for this workflow.

Contributing

awesoMux welcomes contributions. We are pro-AI for coding, when it includes a human in the loop. See CONTRIBUTING.md for the project expectations around pull requests, AI disclosure, and local validation.

Start with CONTEXT.md for orientation and the project glossary, and AGENTS.md for the rules that apply to both human and AI contributors — where to look before changing an area, the GPL source firewall, and the code-style conventions. Claude Code and Codex both read AGENTS.md automatically.

Please also see the project's Code of Conduct, security policy, and third-party notices.

We do not believe in using AI for creative endeavours. All images for awesoMux are created by a real, human artist. Thank you to Amanda Wood for creating our app icon!

License

MIT.