mach-mono

A monorepo of focused macOS quality-of-life utilities — built on a hardened, plugin-first architecture.

   

---

Design System

This monorepo adheres to a strict Minimalistic Aesthetic.

Core Principles: Clarity, Cohesion, Tech-Forward, Subtlety.

---

What is Mach?

Mach is named after the Mach microkernel — the foundational layer that powers macOS itself. The name reflects the goal: a solid architectural foundation that macOS utilities can be built on top of, fast and reliably.

mach-mono is a monorepo housing a growing suite of native Apple-platform utilities. Each app is a focused SwiftUI product sharing common architectural conventions and — where it earns its keep — shared Swift packages.

Build system: Bazel (Bzlmod) is the primary build system — all targets, tests, and CI run through Bazel. mach-mono.xcworkspace is available for IDE navigation only.

See docs/roadmaps/bazel.md and docs/decisions/0007-native-bazel-builds.md.

Background

This repo heavily relies on Agentic Coding. It grew organically out of curiosity for features and functionality, so code and architectural quality varies. Hardening reliability and improving code quality are the next big steps, but my priority remains on working features—after all, these are just quality-of-life additions.

For me, this is a playground to experiment with monorepo setups, Swift, and open-source practices. I took heavy inspiration from the existing Notch projects listed below, but my goal is to reengineer them significantly. :)

If you plan to explore the codebase or contribute, you'll see the "clanker's" work. Please don't judge the agents—judge me for not guiding them properly. My long-term goal is to make this a truly "AI-ready" repository.

Documentation model

Documentation and agent configuration are layered so facts do not drift across tools:

Layer	Start here
Structured facts (workspace, schemes, products, policies)	repo.yaml
Agent guidelines (architectural rules, conventions, workflows)	docs/AGENT-GUIDELINES.md
Docs hub (architecture, PRDs, ADRs, guides, tooling map)	docs/README.md
Per-app instructions (DDD layout, plugins, code standards)	Apps/machNotch/CLAUDE.md

Tool-specific entrypoints (CLAUDE.md, GEMINI.md, AGENTS.md) only point at the canonical guidelines; they are not separate sources of truth. See Where the overall model is defined in docs/README.md for the full map.

---

Apps

mach.notch — Notch Utility

Transforms the MacBook notch into an interactive, plugin-driven command surface.

machNotch is focused on architectural quality: DDD layer boundaries, a SOLID plugin system, full dependency injection, and zero singletons in views or services. Every feature is a plugin — music, media controls, calendar, habits, pomodoro, shelf, teleprompter, battery, webcam, notifications, clipboard, weather, and more.

• Location: Apps/machNotch/

mach.brief — Daily brief

Configurable daily content (words, facts, quotes, mantras, mood prompts) with optional sinks such as Obsidian. Shares Packages/MachBriefKit. In active development — see docs/prds/machBrief-macOS.md.

• Location: Apps/machBrief/

---

Repository Structure

mach-mono/
├── MODULE.bazel             # Bazel module root (Bzlmod)
├── WORKSPACE.bzlmod         # Workspace marker for Bazel
├── AGENTS.md                # Pointer to canonical AGENT-GUIDELINES.md
├── CLAUDE.md                # Thin Claude Code adapter
├── GEMINI.md                # Thin Gemini CLI adapter
├── repo.yaml                # Canonical structured repo facts
├── .agent/                  # Reusable agent workflows and skills
├── .claude/                 # Claude Code config
├── .cursor/                 # Cursor adapter rules
├── .github/                 # CI/CD workflows, issue templates
├── Apps/
│   ├── machNotch/           # mach.notch — notch utility (primary scheme)
│   └── machBrief/           # mach.brief — in development (see docs/prds)
├── docs/
│   ├── README.md            # Documentation index
│   ├── AGENT-GUIDELINES.md  # Canonical agent behavioral/arch rules
│   ├── architecture/        # System architecture references
│   ├── decisions/           # ADR-style decision records
│   ├── guides/              # Practical guides
│   ├── prds/                # Product requirement docs and implementation plans
│   └── roadmaps/            # Technical roadmaps (incl. Bazel rollout)
├── external/                # Vendored third-party trees consumed by Bazel
├── Packages/                # Shared Swift packages (MacroVisionKit, MachBriefKit, …)
├── resources/               # Demo assets, scripts
└── mach-mono.xcworkspace    # Xcode IDE navigation only (build via Bazel)

Project Architecture

This diagram provides a high-level overview of the monorepo's technical structure:

graph TD
    %% Define Layers
    subgraph BuildOrchestration [Build System]
        BZ[Bazel / Bzlmod]
    end

    subgraph Apps [Applications]
        MN[machNotch]
        MB[machBrief]
    end

    subgraph Packages [Shared Libraries]
        MVK[MacroVisionKit]
        MBK[MachBriefKit]
    end

    subgraph Core [Project Core]
        RY[repo.yaml]
        AG[AGENT-GUIDELINES]
    end

    %% Connections
    BZ --> MN & MB
    
    MN --> MVK
    MB --> MBK

    %% Core references
    MN & MB -.-> RY
    RY -.-> AG

    %% Styling
    style BuildOrchestration fill:#f9f9f9,stroke:#333
    style Apps fill:#f0f8ff,stroke:#333
    style Packages fill:#fff0f5,stroke:#333
    style Core fill:#ffffe0,stroke:#333

Loading

---

Getting Started

Prerequisites

Tool	Why	Install
macOS 26+	Required system version	—
Xcode 26+	Bundled SDKs and toolchain	Mac App Store
Bazelisk	Wraps Bazel, auto-pins to .bazelversion (currently 7.6.1) — no separate Bazel install	brew install bazelisk
Task	Thin wrapper over the canonical Bazel commands (task run, task test, …)	brew install go-task
Apple ID	Code signing — the free tier works (see sideloading guide)	—

mach.notch

task run is the canonical launch command. It builds with Bazel, signs with your Apple Development cert, installs to ~/Applications/machNotch.app (only when the build actually changed), and opens it. Installing to a stable signed path means macOS keeps the granted TCC permissions across every rebuild — no re-prompting on iteration.

git clone https://github.com/larsboes/mach-mono.git
cd mach-mono

task run         # build → sign → install (if changed) → launch
task kill        # terminate the running instance
task notch:test  # run machNotch tests only

mach.brief

task brief:run    # build → install → launch
task brief:kill   # terminate the running instance
task brief:test   # run MachBriefKit tests only

All tests

task test
# or directly:
bazelisk test //Apps/machNotch:machNotchTests //Packages/MachBriefKit:MachBriefKitTests

IDE (Xcode — navigation only)

open mach-mono.xcworkspace

Xcode is for code navigation and editing only. Build and test via Bazel / Task.

Detailed setup, signing, and troubleshooting

Build only (no install / sign)

If you just want to verify a build compiles, skip task run and call Bazel directly:

bazelisk build //Apps/machNotch:machNotch
bazelisk build //Apps/machBrief:machBrief

Code-signing setup

task run signs the app bundle with Apple Development: <you>. List the identities in your keychain:

security find-identity -v -p codesigning

If you have more than one, update CERT in Taskfile.yml to match the one you want to use. No paid Apple Developer account? The free Apple ID flow works — see the sideloading guide.

First-run permissions

On first launch macOS will prompt for the permissions each plugin needs:

Permission	Used by
Accessibility	Gestures, hover detection, media-key interception
Screen Recording	The notch overlay window itself
Microphone	Teleprompter monitoring
Calendar	Calendar plugin (read-only)
Notifications	Notification mirror plugin

The install sentinel at ~/Library/Caches/com.larsboes.mach/notch_zip_hash skips the install step when the binary hasn't changed, so prompts only fire when there is a real change to the bundle.

Troubleshooting

Symptom	Fix
codesign: no identity found	Pick another cert from security find-identity and update CERT in Taskfile.yml, or follow the sideloading guide for the free-tier flow.
Permissions reset after every rebuild	The binary changed, so the sentinel triggered a re-install. Expect one prompt cycle per real change.
Xcode shows red errors but Bazel builds fine	Trust Bazel — Xcode is for navigation only.
First build is very slow	Bazel is fetching rules_apple / rules_swift toolchains. Subsequent builds reuse the disk cache.
error -600 when opening the app right after task kill	task run already inserts a sleep 1 after kill; re-run if you hit it manually.

What you don't need

No CocoaPods, no Carthage, no SPM at the repo root for development. All targets, tests, and CI run through Bazel + Bzlmod (see ADR 0007). The root Package.swift exists only as input to rules_swift_package_manager.

---

Roadmap

• mach.notch — notch utility (shipped)
• [~] mach.brief — standalone daily brief app + MachBriefKit (in development)
• [~] SystemStats plugin — CPU/GPU/RAM/disk/network rings (in progress)
• mach.window, mach.bar, plus more notch plugins (PreventSleep, ExternalBrightness, ColorPicker, FocusMode, MenuBar) and shared MachUI package

The full, prioritised plan with phases and debt triage lives in docs/prds/machNotch.md. The doc index is at docs/README.md.

---

Requirements

All system requirements, including minimum OS versions (macOS/iOS) and Swift language mode expectations, are centrally defined in repo.yaml.

---

Acknowledgments

mach-mono builds on the shoulders of several exceptional open-source projects:

• boring.notch — the foundational notch utility this fork originated from. The plugin architecture, media integration, shelf, and core notch interaction model all trace back here. An outstanding project by TheBoredTeam.

• Atoll — a feature-rich notch utility that expanded on boring.notch with live activities, lock screen widgets, system stats, and more. A major source of feature inspiration for what this suite aims to become.

• DockDoor — window peeking, alt-tab, and dock enhancements for macOS. Inspiration for the upcoming mach.window app.

• MacroVisionKit — real-time fullscreen and window state detection framework powering the notch's context awareness.

• Stats — reference implementation for macOS system metrics (CPU, GPU, memory, network, disk) via SMC and IOReport bindings.

• SkyLightWindow — private API window rendering techniques.

• KeyboardShortcuts, Defaults, Sparkle, Lottie — essential macOS development libraries used throughout.

---

License

The repo currently mixes licenses — read carefully before forking or vendoring.

Component	License	Target
mach-mono (root) + Apps/machNotch	GPL-3.0 (inherited from boring.notch)	MIT (after the cleansing migration completes)
Apps/machBrief	MIT	—
Packages/MachBriefKit	MIT	—
Packages/MacroVisionKit	MIT	—

Full GPL-3.0 text: LICENSE. Per-package licenses live next to each package.

What GPL-3.0 means for you

• You may use, modify, and redistribute machNotch.
• Distributed binaries must come with source for any modifications, under GPL-3.0.
• Plugins compiled into the machNotch app fall under GPL-3.0 (linking).
• Contributions to machNotch will be GPL-3.0 until the migration described below completes.

The MIT migration

machNotch inherited GPL-3.0 from boring.notch. The long-term plan is to relicense the root and machNotch as MIT once the boring.notch-derived code has been cleanly reimplemented. New apps and packages already start MIT; new clean-slate code in machNotch should be written without copying from upstream so it can be relicensed without further rework.

Decision record: ADR 0003 — License policy. Migration plan: machNotch PRD § License Migration. Current and target license state per component is also tracked machine-readably in repo.yaml.