notchkit
Build macOS notch apps that live in the MacBook camera notch. Handles the hard parts — notch detection, floating panel (NSPanel), hover expa
Open source Repository Open in the app JSON README (API)
About
Build macOS notch apps that live in the MacBook camera notch. Handles the hard parts — notch detection, floating panel (NSPanel), hover expand/collapse animations, the curved NotchShape, and a SwiftUI template with collapsed wings + expanded tray. Clone, edit one file, build. No Xcode project needed.
Details
- Kind
- Plugins
- Topic
- No topic detected
- Publisher
- aishwaryaashok14
- Origin
- marketplace
- Category
- ferramentas
- Stars
- 2
- Last push
- 2026-03-26T09:37:29Z
- Repository state
- ativo
- Language
- Swift
- License
- MIT
- Added
- 2026-08-30 01:48:58
- Updated
- 2026-08-30 01:48:58
- Origin id
aishwaryaashok14/notch-kit/notchkit
README
# NotchKit
An agent skill for building macOS notch apps. Install it once, and any AI coding agent can build a notch app in minutes.
```bash
npx skills add aishwaryaashok14/notch-kit
```
Works with Claude Code, Cursor, Cline, GitHub Copilot, Gemini CLI, Codex, and 40+ other agents.
---
## What is this?
NotchKit is a skill for AI coding agents. It handles the hard parts of building a macOS notch app — panel configuration, notch detection, hover behavior, shape math — so you (or your agent) can focus on the actual app logic.
Install the skill, tell your agent what to build, and it knows how to use NotchKit.
## Install
**Skills.sh (works with 40+ agents):**
```bash
npx skills add aishwaryaashok14/notch-kit
```
**Claude Code plugin:**
```bash
/plugin marketplace add aishwaryaashok14/notch-kit
/plugin install notch-kit@aishwaryaashok14-notch-kit
```
Then tell your agent:
```
Build me a macOS notch app that [describe your app].
Use the notch-kit skill as the foundation.
```
Or use it directly without the skills CLI — paste this into Claude Code, Cursor, or any AI assistant:
```
I want to build a macOS notch app. Use the NotchKit starter kit from
https://github.com/aishwaryaashok14/notch-kit as the foundation.
Clone it, then modify NotchContentView.swift to build [describe your app].
The collapsed view shows content on both sides of the notch camera.
The expanded view is the full tray that appears on hover.
```
## What you get
| File | Purpose |
|------|---------|
| `NotchPanel.swift` | Floating `NSPanel` — non-activating, always on top, transparent, all spaces |
| `NotchShape.swift` | Curved shape matching the MacBook notch (animatable corner radii) |
| `NotchWindow.swift` | Notch detection, hover expand/collapse, clean teardown |
| `NotchContentView.swift` | Template: collapsed wings + expanded tray — **edit this file** |
| `NotchAppDelegate.swift` | Menu bar icon + app lifecycle |
| `build-app.sh` | One command to build a `.app` bundle |
## Quick start
```bash
git clone https://github.com/aishwaryaashok14/notch-kit.git
cd notch-kit
chmod +x build-app.sh
bash build-app.sh
open dist/NotchKit.app
```
You should see a notch bar with "NotchKit" on the left and "Ready" on the right. Hover to expand the tray.
## Build your own notch app
All your UI lives in `NotchKit/NotchContentView.swift`. Two sections to customize:
**Collapsed view** — always visible, on both sides of the camera:
```swift
var collapsedContent: some View {
HStack(spacing: 0) {
// LEFT WING
Text("My App").font(.system(size: 9, design: .monospaced))
Color.clear.frame(width: viewModel.notchWidth - 30) // camera gap
// RIGHT WING
Text("Status").font(.system(size: 9, design: .monospaced))
}
}
```
**Expanded view** — the full tray on hover:
```swift
var expandedContent: some View {
VStack {
Text("Your app content here")
Button("Do something") { /* ... */ }
}
}
```
## Customization
In `NotchWindow.swift`:
```swift
var expandedWidth: CGFloat = 420 // Tray width
var expandedHeight: CGFloat = 240 // Tray height
var wingExtension: CGFloat = 180 // Wing width beyond the notch
```
In `NotchShape.swift` (corner radii):
```
Collapsed: top = 6, bottom = 14
Expanded: top = 19, bottom = 24
```
## Architecture
```
NotchKit/
NotchApp.swift App entry point
NotchAppDelegate.swift Menu bar + lifecycle
NotchPanel.swift NSPanel configuration
NotchShape.swift Curved notch shape (animatable)
NotchWindow.swift Notch detection + expand/collapse
NotchContentView.swift YOUR UI GOES HERE
Info.plist Agent app (no dock icon)
```
## Ideas to build with NotchKit
- Pomodoro timer in the notch
- Now playing music widget
- CPU / memory monitor
- Meeting countdown
- Weather at a glance
- Clipboard history
- Quick notes
- Habit tracker
## How it works under the hood
1. `NotchWindow` detects the notch via `NSScreen.auxiliaryTopLeftArea` and `auxiliaryTopRightArea`
2. A `NotchPanel` (floating `NSPanel` at `.mainMenu + 3` level) is positioned at the notch
3. `NotchTrackingView` handles mouse enter/exit for hover behavior
4. On hover: panel animates to expanded size via `NSAnimationContext`
5. `NotchViewModel.isExpanded` triggers the SwiftUI transition between collapsed and expanded
6. On mouse leave: 0.8s delay, then collapse
7. On quit: `destroy()` closes the panel and removes it — no ghost windows
## Requirements
- macOS 13+
- Swift 5.9+
- No Xcode project needed (Swift Package Manager)
- Works on MacBooks with and without a notch
## Built with NotchKit
- [WalkOS](https://walkos.aishashok.com) — A walking reminder that lives in your MacBook notch ($4.99)
## License
MIT — use it for anything.