MacDynamicIsland - GitLite

KO | EN

gitlite — search

#video #privacy #ai-agents #kubernetes #list #rust #markdown #rag #command-line #pdf

MacDynamicIsland

(★ 21)

A native macOS Dynamic Island utility with quick notes, clipboard history, app management, screenshots and notch interactions.

File Explorer

ZIP Download

- - overview.png
  - readme-hero.png
- Info.plist
- build_app.sh
- build_dmg.sh
- make_dmg_background.swift
- make_icon.swift
- probe_notch.swift
- test_font_size_blur.sh
- test_font_size_resize.sh
- - AppDelegate.swift
  - AppSettings.swift
  - AppsView.swift
  - ClipboardManager.swift
  - ClipboardView.swift
  - ClockNoteView.swift
  - FloatingIconController.swift
  - FloatingScreenshotController.swift
  - HairMirrorView.swift
  - IslandPalette.swift
  - main.swift
  - MainView.swift
  - MenuBarIconController.swift
  - NotchOverlayController.swift
  - NotesSaver.swift
  - SavedNotesHistory.swift
  - ScreenshotService.swift
.gitignore
Package.swift
README.md
README.zh-CN.md

# Use via CDN

jsDelivr

jsDelivr serves any public GitHub repository as a CDN with zero setup. Pick a version and a file to get a ready-to-paste link and snippet.

Version

File

Link

Example

Command Glossary

Commands referenced in this DOCs, explained below.

🔍

`swift`

View Details ▼

Create, run, and build Swift projects.

swift repl

Start a REPL (interactive shell):

swift {{file.swift}}

Execute a program:

swift package init

Start a new project with the package manager:

🔍

`xcode-select`

View Details ▼

Switch between different versions of Xcode and the included developer tools.
Also used to update the path to Xcode if it is moved after installation.

xcode-select --install

Install Xcode's command-line tools:

xcode-select --switch {{path/to/Xcode.app/Contents/Developer}}

Select a given path as the active developer directory:

xcode-select --switch {{path/to/Xcode_file.app}}

Select a given Xcode instance and use its developer directory as the active one:

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

**English** | [简体中文](README.zh-CN.md)

Current version: **1.2.7 (build 20)**

<p align="center">
  <img src="docs/images/readme-hero.png" alt="MacDynamicIsland interface preview" width="720">
</p>

MacDynamicIsland is a native macOS utility that combines a compact desktop dashboard, clipboard history, quick screenshots, an always-on-top image workspace, quick notes, running-app shortcuts, and a hairstyle mirror. It runs as an `LSUIElement` app without a normal Dock icon.

The interface uses a clean white, light-gray, and black visual system with a monochrome mountain-and-star app icon.

## Download and install

[Download MacDynamicIsland 1.2.7 for macOS (.dmg)](https://github.com/chenjieliefu/MacDynamicIsland/releases/download/v1.2.7/MacDynamicIsland-1.2.7.dmg)

Open the downloaded DMG, then drag `MacDynamicIsland.app` onto the **Applications** folder shown in the installer window. No source build is required.

The current release uses a local signature and is not notarized with an Apple Developer ID. If macOS blocks the first launch, open **System Settings → Privacy & Security** and choose **Open Anyway**.

## Highlights

### Two-page panel

The panel is intentionally limited to two pages:

- **Mac Island:** a single bento-style dashboard with a vertical hairstyle mirror, clock, running apps, quick note, screenshot shortcuts, and horizontal clipboard history.
- **Settings:** all preferences fit on one page without vertical scrolling. Launch at login, notch entry, floating entry, menu bar icon, clipboard retention, screenshots, and Quit are arranged in an airy grid.

The physical notch, floating entry, and menu bar icon all open the same panel. The full allocated area of each top tab is clickable, including its blank space.

### Hairstyle reference and camera mirror

- Import a hairstyle reference image and keep it available across launches.
- The image fills the fixed portrait frame; drag it inside the frame to choose which part remains visible after cropping.
- The crop position is saved automatically.
- Click the reference image to open the front camera as a mirror.
- While the mirror is open, click the small reference thumbnail to replace the image.
- The reference image can also be replaced or removed from its corner controls.

Camera access is requested only when the mirror is opened.

### Clipboard and quick screenshots

- Automatically records copied text and images.
- Click an item to copy it again; the row shows **Copied** for about 1.3 seconds.
- Image rows provide a pin action. After pinning, the same row-level feedback area shows **Pinned** for about 1.3 seconds; nothing is drawn over the pinned image itself.
- Hover actions allow copying, pinning, and deletion without expanding the row.
- Region, window, and full-screen screenshot buttons are available from the home page and Settings.
- Retention can be set to 1, 7, or 30 days, or forever. Storage is capped at 500 text entries and 50 images.

Deleted image files are moved to the Trash when possible.

### Always-on-top image workspace

Screenshots and pinned clipboard images open above other applications.

- Drag the toolbar to move the window.
- Drag the image edge to resize while preserving the image aspect ratio.
- Use the toolbar zoom buttons, mouse wheel, or two-finger magnification gesture to zoom.
- Resize cursors change at image and text-box edges.
- The toolbar stays outside the image and never covers image content.

### Multiple text boxes

- Add multiple transparent text boxes over a pinned image.
- Default placeholder text and entered text use red consistently.
- Each selected text box has eight aligned resize handles and its own small delete button.
- Drag the border to move a text box; enlarged hit areas make moving and resizing more responsive.
- The toolbar trash button deletes all text boxes.
- Font sizes from 8 to 200 are supported. A size is committed on Return, checkmark, focus loss, Done, background click, or text-box switch.
- The selected font size remains stable while moving, resizing the text box, or resizing the pinned image window.
- Rich text supports mixed font sizes, line breaks, and ten text colors.

The repository includes regression checks for font-size persistence during focus changes and resizing.

### Notes and running apps

- Quick-note drafts are saved locally while typing.
- Notes can be exported to Apple Notes and reopened from local saved history.
- Running applications appear in a compact icon grid.
- Hover an app tile to reveal a close button; protected desktop/system processes are not treated like ordinary apps.

## Entry points

- **Physical notch:** left-click opens the panel; right-click opens the function menu.
- **Floating entry:** draggable, position-aware, and hidden temporarily during screenshots.
- **Menu bar icon:** follows menu bar visibility and available space so it does not cover other icons.

Each entry point can be enabled or disabled independently in Settings.

## Requirements

- macOS 12.0 or later.
- A notch-equipped MacBook is required only for the physical-notch entry.
- Xcode or Xcode Command Line Tools are required to build from source.

## Run from source

```bash
swift run
```

## Build the app

```bash
chmod +x scripts/build_app.sh
./scripts/build_app.sh
```

The packaged application is created at `dist/MacDynamicIsland.app`. Copy it to `/Applications` before enabling Launch at Login.

To create the drag-to-Applications installer image:

```bash
./scripts/build_dmg.sh
```

The DMG is created at `dist/MacDynamicIsland-<version>.dmg`. Node.js and npm are required for this packaging step.

## Regression checks

```bash
scripts/test_font_size_blur.sh
scripts/test_font_size_resize.sh
```

These checks verify that an applied font size survives focus loss and the lightweight snapshot used during resizing.

## Permissions

1. **Screen Recording:** required for region, window, and full-screen screenshots.
2. **Camera:** required only for the hairstyle mirror.
3. **Automation → Notes:** required only when exporting a quick note to Apple Notes.
4. **Login Items:** used when Launch at Login is enabled.

Clipboard monitoring, the floating entry, and the notch overlay require no additional permission.

## Project structure

```text
MacDynamicIsland/
├── Package.swift
├── Resources/Info.plist
├── scripts/
│   ├── build_app.sh
│   ├── build_dmg.sh
│   ├── make_dmg_background.swift
│   ├── make_icon.swift
│   ├── probe_notch.swift
│   ├── test_font_size_blur.sh
│   └── test_font_size_resize.sh
└── Sources/MacDynamicIsland/
    ├── AppDelegate.swift
    ├── AppSettings.swift
    ├── AppsView.swift
    ├── ClipboardManager.swift
    ├── ClipboardView.swift
    ├── ClockNoteView.swift
    ├── FloatingIconController.swift
    ├── FloatingScreenshotController.swift
    ├── HairMirrorView.swift
    ├── IslandPalette.swift
    ├── MainView.swift
    ├── MenuBarIconController.swift
    ├── NotchOverlayController.swift
    ├── NotesSaver.swift
    ├── SavedNotesHistory.swift
    ├── ScreenshotService.swift
    └── main.swift
```

## Local data

- Notes, clipboard metadata, crop position, and preferences: `~/Library/Preferences/com.local.macdynamicisland.settings.plist`
- Screenshots: `~/Library/Application Support/MacDynamicIsland/Screenshots/`
- Hairstyle reference image: `~/Library/Application Support/MacDynamicIsland/ReferenceImages/`

## Troubleshooting

- If screenshots are black or contain only the wallpaper, grant Screen Recording permission and restart the app.
- If the camera cannot open, allow MacDynamicIsland under System Settings → Privacy & Security → Camera.
- If Launch at Login does not work, install the packaged app in `/Applications` first.
- If Apple Notes export fails, allow MacDynamicIsland to control Notes under Privacy & Security → Automation.