Skip to content

Contributing

Bug fixes, documentation improvements, performance work, focused features, and thoughtful ideas are welcome. This guide covers building OmniWM and submitting a change. For larger changes, open an issue or discussion first so we can agree on direction.

Documentation-only contributions do not require building the app. For website changes, follow the website development guide.

Building OmniWM requires an Apple Silicon Mac running macOS 27, Xcode 27 for the macOS SDK and signing tools, and the Swift toolchain pinned in .swift-version. The released OmniWM app still supports macOS 26.0 or later.

Install Xcode from Apple Developer Downloads, open it, and finish its first-launch setup. In Xcode → Settings → Locations → Command Line Tools, select Xcode 27. The standalone Command Line Tools package is not a substitute for this Xcode installation.

Install swiftly to manage the pinned Swift toolchain.

Click Fork on the OmniWM repository, then clone your fork. Replace YOUR-USERNAME with your GitHub username:

Terminal window
git clone https://github.com/YOUR-USERNAME/OmniWM.git
cd OmniWM
git remote add upstream https://github.com/OmniNull/OmniWM.git
git fetch upstream
git switch -c my-change upstream/main

Use a descriptive branch name in place of my-change. Each contribution should start from main and focus on one problem.

From the repository directory, install and confirm the pinned toolchain:

Terminal window
swiftly install
swift --version

The result must report the Swift 6.5 development snapshot named in .swift-version.

Terminal window
make setup

Setup needs Lix (or another Nix with flakes). It builds the repository’s flake.nix: the pinned, prebuilt GhosttyKit is linked at Frameworks/GhosttyKit.xcframework and checked against its checksum, and the pinned SwiftFormat, SwiftLint, Python, Fish and Nushell are linked at .cache/flake-tools. You do not need to compile GhosttyKit, and no Homebrew installation is required. nix develop opens a shell with the same tools on PATH. With direnv, direnv allow loads that shell whenever you enter the checkout.

Tool versions and download checksums are recorded in Scripts/dev-tools.env, which the flake reads; other packages are pinned by flake.lock. Ghostty’s internal archive pin remains in Scripts/build-metadata.env. Setup preserves an existing framework that does not match the pin and explains the mismatch instead of overwriting it. Setup does not launch OmniWM or change privacy permissions, login items, or CLI links.

4. Optionally Create a Signing Certificate

Section titled “4. Optionally Create a Signing Certificate”

For repeated development, create the local signing certificate below. A stable signing identity helps macOS retain the Dev app’s permissions across rebuilds. It needs no paid Apple Developer membership.

You can skip this and run Dev immediately. Without the certificate, the build uses ad-hoc signing and warns that you may need to grant permissions again after rebuilding.

Terminal window
make run

This builds your checked-out code, packages and signs OmniWM Dev.app, installs it at ~/Applications/OmniWM Dev.app, and opens it. It builds before quitting the running OmniWM copy; if that copy cannot quit, installation stops with an error. Your normal OmniWM app remains installed. Only one copy runs at a time.

On first launch, grant Accessibility and Input Monitoring to OmniWM Dev in the permissions window. Screen Recording is optional for capture-derived visuals such as Overview thumbnails. Dev has its own permissions, separate from your normal app. Follow any restart prompt after granting permissions, then return to the permissions window and click Start OmniWM or Continue Without Screen Recording.

Edit code in your preferred editor, then run make run again to rebuild. You can also launch the installed Dev app from Finder.

For app code changes, run:

Terminal window
make verify
swift test

make verify checks formatting, lint, and the build. It does not run tests. See verification for runtime changes and website checks.

Commit your change, push your branch to your fork, and open a pull request targeting OmniNull/OmniWM:main. A draft PR is welcome when you want early feedback. Explain the problem, the resulting behavior, and what you verified; say what you could not check and why.

Command Result
make setup Check prerequisites and obtain the pinned dependencies.
make doctor Diagnose tools, dependencies, signing, and app paths without changing them.
make hooks Enable the pre-commit hook: SwiftFormat and SwiftLint on staged Swift files, and a warning when a pinned download in Scripts/dev-tools.env is not public yet.
make build Build the app without installing or launching it.
make run Build, sign, install, and switch to Dev; alias for make dev-install.
make use-dev Switch to the installed Dev app without rebuilding.
make use-release Switch back to the normal app at /Applications/OmniWM.app.

If your normal app is elsewhere, set its path when switching:

Terminal window
OMNIWM_RELEASE_APP="$HOME/Applications/OmniWM.app" make use-release

The development commands do not install the normal release. If you need it, follow the installation guide.

The installed Dev app has the fixed identity com.barut.OmniWM.dev, which selects its own storage directories even when launched from Finder:

Data Normal app Dev app
Settings ~/.config/omniwm/settings.toml ~/.config/omniwm-dev/settings.toml
Saved state ~/.local/state/omniwm/ ~/.local/state/omniwm-dev/
OmniWM diagnostics ~/.local/state/omniwm/diagnostics/ ~/.local/state/omniwm-dev/diagnostics/

On first installation, the helper copies your normal settings.toml into an independent Dev file. Existing Dev settings are preserved, and later edits are never synchronized. If no normal settings file exists, Dev uses its defaults. Saved state and clipboard history start fresh; they are not copied.

Absolute XDG_CONFIG_HOME and XDG_STATE_HOME values replace the corresponding base directories, with omniwm or omniwm-dev appended. Relative values are ignored. These variables must be available to the app process: a variable set only in a Terminal session is not automatically available to a Finder launch.

Keep Start at Login disabled in Dev. The helper does not change login registration. Dev can still display normal release-update notifications; installing a stable update does not rebuild your development code. Use make run to rebuild Dev.

Both copies use the same IPC socket, so an existing omniwmctl command talks to whichever copy is running. Enable IPC in that copy’s settings when testing CLI commands.

To test the CLI built from your changes, invoke it directly:

Terminal window
"$HOME/Applications/OmniWM Dev.app/Contents/MacOS/omniwmctl" --help

Setup and switching do not change CLI links. Dev’s Install CLI setting can create a link to its bundled CLI when no conflicting link exists; use the embedded path above to leave your normal CLI setup alone.

Create one certificate and reuse it for future builds:

  1. Open Keychain Access using Spotlight and select the login keychain.
  2. Choose Keychain Access → Certificate Assistant → Create a Certificate.
  3. Set Name to OmniWM Dev, Identity Type to Self Signed Root, and Certificate Type to Code Signing.
  4. Click Create, accept the self-signed certificate prompt, and click Done. Keep the certificate and its private key in your login keychain.
  5. Double-click the certificate, expand Trust, and set Code Signing to Always Trust. Close the window and confirm the change if prompted.
  6. Run make doctor, then rebuild with make run.

See Apple’s certificate creation guide and code-signing instructions for background. If macOS asks whether codesign may access this certificate’s private key while building, allow that access.

To use an existing local code-signing identity with another name:

Terminal window
OMNIWM_SIGNING_IDENTITY="Your Certificate Name" make run

Run make format to apply formatting and the required license headers. Run make verify afterward to check formatting, lint, localization catalogs, and an arm64 debug build. The commands use the versions installed by make setup.

Localization checks and synchronization generate compiler metadata with the selected Xcode installation’s default Swift toolchain in .build/localization. This separate incremental build supports localization extraction even when swift on your PATH selects a standalone toolchain that does not emit the metadata.

Every Swift source and test file starts with the two-line GPL-2.0 header enforced by SwiftFormat. Preserve that header. Package.swift keeps its swift-tools-version directive on line one. Keep contributions in Swift, and avoid additional source comments; use clear names and structure.

Use focused regression tests for changed behavior. Runtime changes require the full serial swift test suite, and changes affecting concurrency also require swift test --parallel. Environment-dependent live tests remain opt-in. For motion, focus, layout, and other visible behavior, also describe the manual checks you performed.

CI takes Fish and Nushell from the flake to run the native CLI completion tests. For the same coverage locally, run swift test inside nix develop; tests fail with a message if a shell is missing.

For changes to setup, packaging, development installation, or related tooling, also run make test-dev-tools. This runs the Python development-tooling tests and is included in CI’s Tooling job.

CI also checks that the generated IPC wire encoders match their models. After changing IPC models or the generator, run python3 Scripts/generate_ipc_wire.py --check. If it reports stale files, run python3 Scripts/generate_ipc_wire.py, review the generated diff, and rerun the check.

The optional styles live in styles/, one folder per style. A development build running from .build/ reads them from the checkout. Open Settings > Styles & Widgets > Get Styles, install or replace the style, then choose Use Style. To publish your own repository, follow the style folder guide.

Translations live in the string catalogs. Localizable.xcstrings contains interface text, Commands.xcstrings contains command names, categories, and scopes, InfoPlist.xcstrings contains the macOS permission descriptions, and Shell.xcstrings contains the Default OmniShell widget text; add or edit your language’s localizations entries in those catalogs. Each style in styles/ keeps its own text in flat strings/<locale>.toml tables: en.toml lists the English text, and a language file maps the same English keys to translations. Keep the English keys and source values intact, and translate the meaning in context. English is the fallback for strings without a translation.

Preserve each format argument’s type when translating. You may reorder arguments with positional forms such as %2$@ and %1$lld; a %lld count cannot become %@. Plural branches may omit a count when the wording does not need it. make verify checks format arguments, including plural forms, before a translation is accepted. To preview length and direction issues, use Xcode’s localization pseudolanguages or change the app language in macOS settings.

If you change localized Swift source text, run make localization-sync to build and update the catalogs from compiler-extracted strings, then review the catalog diff. make verify fails when source and catalogs differ. For translation-only changes, edit the catalogs directly and run make verify and make test-dev-tools. This SwiftPM repository has no Xcode project for XLIFF export and import; contribute the catalog files directly. See Apple’s string catalog guide for the catalog format and plural variations.

Before adding the first translation for a new language, translate every desktop string in all four catalogs and have a fluent speaker review the result in the packaged app. Add its cardinal plural categories to PLURAL_CATEGORIES in Scripts/localization.py, then run python3 Scripts/localization.py completeness --locales fr de with the locale codes you are adding; this optional audit requires a nonblank string marked translated for every nonempty key and each required plural branch. A partial catalog activates that language for macOS users as soon as it ships. After a language is established, newly added strings may temporarily fall back to English while translations catch up.

Website changes use the checks in Website Development: npm run reference:check, npm run check, and npm run build from website/. Small documentation-only changes do not need app builds or Swift tests.

GitHub’s OmniWM CI workflow reports Tooling (flake check, formatting, lint, generated IPC files and make test-dev-tools), Verify (make arc-audit, which fails on any retain, release or allocation in the exercised OmniWMShellCore workload, then localization and build) and Tests (the serial Swift suite) separately. It doesn’t run when a change only touches docs/, website/ or top level Markdown files; website changes get the Website workflow instead. On a pull request that only changes Python under Scripts/ or Tests/DevToolingTests/ (with or without docs), Tests is skipped, since Tooling already tests those. Tests are initially advisory while the hosted environment is established; a failing test still needs an explanation. On a first contribution, a maintainer may need to approve the workflow run before checks start. A pending approval does not mean you did something wrong.

Start with make doctor and the first error reported by the failing command.

  • Wrong Swift version: from the repository directory, run swiftly install and check swift --version against .swift-version. Ensure swiftly’s bin directory is on PATH. Use make doctor to check the Swift toolchain and selected Xcode installation separately.
  • Missing dependencies: run make setup. If an existing GhosttyKit fails its checksum, move your custom framework aside before running setup again; the helper will not replace it for you.
  • Permissions requested again: check the signing identity with make doctor, rebuild with the same valid certificate, and grant Dev’s permissions again when prompted. Stable and Dev permissions are separate.
  • Switching stops because OmniWM is still running: quit that copy from its menu, then retry. The helper does not force-kill it or install over a running copy.
  • Normal app not found: install the release or supply OMNIWM_RELEASE_APP as shown above.
  • Keep changes focused. Explain the current problem and why your approach solves it; refactors need a concrete reason.
  • Include verification results, including any checks you could not run. Add screenshots, recordings, or CLI examples when useful.
  • Update documentation when behavior, configuration, workflows, or interfaces change.
  • Create your change branch from main and target main. There is no permanent develop branch.
  • Contributor PRs are normally integrated with merge commits so their commit history and authorship remain intact. You do not need to squash or perfect your history before asking for review.

Reviewed development lands on main; published releases come from version tags. Merging a PR does not itself update users’ installed apps. Work that merges to main outside a PR, such as a release branch, needs a name ending in -release so the same CI runs on every push to it.

Releases use the OmniWM release workflow, dispatched from main in two runs: prepare with the version number, then publish with the prepare run ID and final release notes. Preparation requires BarutSRB’s approval of the release-signing environment. Publication requires a separate BarutSRB approval of release-publish, after reviewing the exact artifact ID, release commit, asset checksums, and final notes in the validation job summary. The publish job downloads that same artifact by ID.

Each prepare run first resolves the newest commit on Ghostty’s upstream main and builds that exact revision in a separate job with no Apple credentials and a read-only repository token. It uses the released Zig version declared by that Ghostty revision, verifies the official compiler download, and runs zig build -Doptimize=ReleaseFast -Demit-macos-app=false -Dxcframework-target=native on Apple Silicon. There is no scheduled update. The source revision, compiler, build arguments, and framework checksums are saved as provenance.

Preparation installs that framework on its disposable runner, runs make verify and both serial and parallel Swift tests against it, and includes its new source and binary pins in the release commit. An upstream build or compatibility failure stops preparation. Publication reuses the tested framework without checking upstream again. It restores the prepared ZIP before dependency setup, then verifies the public download before pushing the new pins to main. Ordinary make setup continues downloading the prebuilt framework for its checkout; contributors do not need Zig.

Both environments must allow only the main branch, list BarutSRB as their sole required reviewer, and disable administrator bypass. Leave Prevent self-review off so BarutSRB can also approve a personally dispatched run. The workflow checks this configuration before preparation and again before publication; missing or weakened protection stops the run. Repository administrators remain able to change environment settings, so administrator access must remain trusted.

Store these secrets in Settings → Environments → release-signing for stable releases and canary-signing for canary builds, with no repository-level duplicates:

  • APPLE_DEVELOPER_ID_CERT_P12_BASE64 and APPLE_DEVELOPER_ID_CERT_PASSWORD: the Developer ID certificate and its export password, produced with base64 -i cert.p12 | pbcopy.
  • APPLE_NOTARY_KEY_ID, APPLE_NOTARY_ISSUER_ID, and APPLE_NOTARY_KEY_P8: the App Store Connect API key ID, issuer ID, and raw .p8 contents (pbcopy < AuthKey_XXXX.p8). A normal trailing newline is accepted.

The release-publish environment contains no Apple secrets. Two optional repository variables override defaults: OMNIWM_RELEASE_SIGNING_IDENTITY (default Developer ID Application: Oliver Nikolic (VF8LDJRGFM)) and OMNIWM_RELEASE_NOTARIZE_PROFILE (default OmniWM-Notarize).

The prepare summary prints the gh workflow run command for publication because the web form cannot take multi-line notes. Download and launch the prepared app on a desktop before approving publication. Pass skip_app_launch only when the runner cannot launch the GUI; signature, notarization, and quarantine checks still run. Prepared artifacts expire after 30 days. If main moves before publication, prepare again. Retry an interrupted publish with the same prepare run and identical notes. Publication creates the tag and release before pushing main; a competing push or remote failure can still require manual recovery.

Local releases via Scripts/omniwm_release.py use your own keychain and notarization profile.

For canaries, configure canary-signing with no required reviewers and a selected-branches deployment policy allowing only main.

The daily OmniWM canary workflow skips a build when the checked-out commit is already contained in a stable or canary tag, or when only documentation changed since the newest ancestor tag. For this check, documentation means root-level .md files and everything under docs/ or website/; Markdown elsewhere, including bundled issue-report prompts under Sources/, still counts as an app change. Documentation-only commits are also omitted from canary release notes. The manual force option bypasses both skip checks.

When a build is needed, the workflow requires the latest OmniWM CI push run on main to pass, including both Verify and Tests. It starts from the actual checkout rather than the scheduled event’s commit, before dependency setup or importing Apple credentials. Documentation-only pushes don’t start CI, so it uses the newest commit that has a run, looking from the checked-out commit down through documentation-only commits to the first app commit. A failed or unfinished run there, or no run at all, stops the canary; wait for CI to pass and rerun the workflow. The manual force option cannot bypass CI.

The Main branch protection ruleset blocks branch deletion and force-pushes. Keep those protections and do not grant GitHub Actions an Always bypass. The release workflow uses a normal fast-forward push and rejects additional blocking rules before publication, even when its token could bypass them. Required checks or pull-request-only updates need a release flow that publishes an already-reviewed version commit; do not bypass those rules to keep the current flow working.

Re-enable OmniWM CI and confirm Verify and Tests on hosted runners. For an existing PR, use Actions → OmniWM CI → Run workflow and enter its PR number to test its merge with the base branch. A manual run provides logs; it does not replace the PR’s required check. Updating the PR branch triggers its normal PR checks. Approve first-time fork runs when needed.

Include a trace file when useful, especially for bug reports. Open Settings → Troubleshooting, click Start Recording, reproduce the bug, then click Stop & Save Recording and attach the saved .log file.

Report a Bug… in the status-bar menu opens the in-app report form. Recording or selecting trace and crash evidence is optional; on submit OmniWM prepares a fresh diagnostic .log with whatever you selected, reveals it for attaching, and opens a pre-filled GitHub issue.

Before attaching a diagnostic, review it: the file can contain OmniWM settings, application and window titles, and title-based App Rule matchers.

With IPC enabled, captures can also be scripted using the CLI: capture start trace, capture stop, and capture status.

The prompt that rewrites bug reports into GitHub issues lives in plain Markdown. See docs/issue-report-prompt.md for the files, constraints, and verification steps.

If you are unsure about something, open an issue or ask in your pull request. Questions and early feedback are welcome.