Skip to main content
skill CX Codex

os-integrations — Claude Code skill for macOS APIs

The os-integrations Claude Code skill maps macOS APIs to system-level features and their required permissions. It applies when adding global shortcuts, screen capture, or controls for other apps’ windows.

MIT 1,000 installs ★ 1,933 updated 2026-11-05

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add daveebbelaar/bama --skill os-integrations -a claude-code
Open on GitHub

What os-integrations does

The skill matches macOS APIs with features that reach beyond an app’s own window, and names the permissions those features require. Its examples cover menu bar items, floating panels, clipboard access, Spotlight, screenshots, and login launch. Code examples for the integrations are in recipes.md.

It also covers permission requests and checks, along with code signing and install paths. macOS ties Accessibility and Screen Recording grants to the app’s code signature and location. App Sandbox blocks access to Accessibility, event taps, and other apps’ windows.

What it helps with

  • choose a macOS API for a global keyboard shortcut
  • add screen capture with the Screen Recording permission
  • control other apps’ windows through Accessibility
  • set up an app to launch at login

Example prompts for the agent

  • Add a global shortcut to my macOS app and choose the API it needs.
  • Set up screen capture and identify the required permission.
  • Add controls for other apps’ windows using Accessibility.

How to install os-integrations

1Skills CLI (Vercel)

npx skills add daveebbelaar/bama --skill os-integrations -a claude-code

2Manually: put the files in place

~/.claude/skills/os-integrations/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/os-integrations/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about os-integrations

How do I install os-integrations in Claude Code?

Run npx skills add daveebbelaar/bama --skill os-integrations -a claude-code. The skill file is at ~/.claude/skills/os-integrations/SKILL.md.

What does os-integrations do?

It helps select macOS APIs and permissions for native app features such as global shortcuts, screen capture, and control of other apps’ windows.

Why can macOS permissions reset after a rebuild?

macOS associates Accessibility and Screen Recording grants with the code signature and app path. Ad hoc signing requires granting access again after every build.

Source text

SKILL.md · MIT
---
name: os-integrations
description: Deep macOS integrations for a native app, such as global hotkeys, menu bar items, floating panels, window control with Accessibility, screen capture and recording, clipboard, Shortcuts and Spotlight, URL schemes, login items, a CLI, and the permissions each one needs. Use when an app must reach outside its own window or control other apps.
---

# macOS integrations

A Mac app is a set of entry points around the system, not one window. This
skill picks the API for each entry point and the permission it costs.
Code for every row is in [recipes.md](recipes.md).

## Pick the API

| Want | API | Permission |
| --- | --- | --- |
| Global shortcut (key combo) | Carbon `RegisterEventHotKey` | None |
| Hold-to-show (hold Option, press Tab) or key remapping | `CGEvent.tapCreate` event tap | Accessibility |
| Watch keys without changing them (keystroke overlay) | Listen-only event tap | Input Monitoring (`CGRequestListenEventAccess`) |
| List other apps' windows | `CGWindowListCopyWindowInfo` | None (titles need Screen Recording) |
| Menu bar item | `MenuBarExtra` (SwiftUI) or `NSStatusItem` | None |
| Live status in the menu bar (a timer, a sync) | `MenuBarExtra` with a changing label. Live Activities on a Mac only mirror a paired iPhone | None |
| Desktop and Notification Center widgets | WidgetKit extension target (Xcode build, like App Intents) | None |
| Find the app's content in Spotlight | Core Spotlight `CSSearchableIndex` | None |
| Preview the app's own file type in Finder (Space) | Quick Look preview extension | None |
| Menu-bar-only app, no Dock icon | `LSUIElement = YES` in Info.plist | None |
| Spotlight-style panel that keeps the other app in front | `NSPanel` with `.nonactivatingPanel` | None |
| Move and resize other apps' windows | `AXUIElement` (`kAXPositionAttribute`, `kAXSizeAttribute`) | Accessibility |
| Paste into the front app | Write `NSPasteboard`, then post Command-V with `CGEvent` | Accessibility |
| Screenshot | ScreenCaptureKit `SCScreenshotManager` | Screen Recording |
| Window thumbnails | `SCScreenshotManager` with an `SCContentFilter` per window | Screen Recording |
| Screen recording to MP4 | `SCStream` + `SCRecordingOutput` (`AVAssetWriter` when you edit frames) | Screen Recording, Microphone |
| Clipboard history | Poll `NSPasteboard.general.changeCount` | None |
| Text in images | Vision `RecognizeTextRequest` | None |
| Launch at login | `SMAppService.mainApp.register()` | User approves once |
| Links from scripts, Stream Deck, Raycast | `CFBundleURLTypes` + `.onOpenURL` | None |
| Shortcuts app and Spotlight actions | `AppIntent` (App Shortcuts are not supported on macOS). A result or confirmation view is a snippet | None |
| Agent or script reads and changes data | The app binary as a CLI, talking to the running app (`agent-cli` skill) | None |
| A CLI that writes plain files or its own SQLite tells the app to reload | Darwin notification (`notify_post`) | None |
| Keep the Mac awake | `IOPMAssertionCreateWithName` | None |
| System stats | `host_statistics64`, `proc_pid_rusage`, `IOPSCopyPowerSourcesInfo` | None |
| Audio devices | CoreAudio `AudioObjectGetPropertyData` | None |
| Toggle dark mode and other system settings | Apple Events to System Events | Automation |
| Notifications | `UNUserNotificationCenter` | User approves once |
| Dock menu | `applicationDockMenu(_:)` in the app delegate | None |
| Services and Share menu | `NSServices` in Info.plist, `ShareLink` | None |

Prefer the row with no permission when two rows solve the same job.

## Permissions

- Ask at the moment of use. Explain in one line what breaks without it.
  The exception: an app whose core job needs the permission (a window
  manager needs Accessibility) shows its permissions page on first launch.
- Show the state of every permission on one Settings page, with a button
  that opens the right pane:
  `x-apple.systempreferences:com.apple.preference.security?Privacy_Accessibility`
  (or `Privacy_ScreenCapture`, `Privacy_AllFiles`).
- The user grants it in System Settings, and nothing calls your app back.
  Check every 1 to 2 seconds while a permission is missing or a view that
  shows it is open. Otherwise check every 20 seconds, with a timer
  tolerance. Check once more right when such a view opens.
- Every `NS...UsageDescription` key (camera, microphone, Apple Events)
  must be in Info.plist before the first request, or the app crashes.

## Menu bar items, widgets, and snippets

- A menu bar item shows a menu, unless the feature is too complex for one.
  Its icon is a template image (an SF Symbol works). People can turn it
  off in Settings, and nothing is reachable only through it: the Dock menu
  and the main window offer the same actions. `MenuBarExtra` already works
  with keyboard navigation; an `NSStatusItem` that opens a custom window
  must too (WWDC26-289).
- A widget shows one idea from the app's purpose, with content that
  changes through the day. Sizes small, medium, large, and extra large. On
  the desktop it renders vibrant and nearly gray, so it must read without
  color. Standard margins 16 pt. A click deep-links to the exact place;
  buttons and toggles in it run App Intents. Never a whole app squeezed
  into a widget.
- A snippet is the view an App Intent shows in Spotlight, Siri, or
  Shortcuts: a result (with Done) or a confirmation (Cancel plus a button
  that names the action, never "OK"). At most 400 pt tall, readable in
  light and dark, and clear without the spoken text.
- Badge the Dock icon only with a count of unread notifications.

## Signing keeps grants

macOS stores Accessibility and Screen Recording grants per code signature
and path. To keep them across rebuilds:

- Sign with one stable "Apple Development" certificate. Ad hoc signing asks
  again after every build.
- Install to the same path every time (`/Applications/<App>.app` or
  `~/Applications/<App>.app`).
- No App Sandbox for apps that use Accessibility, event taps, or other
  apps' windows. The sandbox blocks them.
- After an install, refresh Launch Services so the Dock shows the new icon:
  `lsregister -f -R -trusted /Applications/<App>.app` (the tool lives in
  `/System/Library/Frameworks/CoreServices.framework/Frameworks/LaunchServices.framework/Support/`).

If a grant looks on but the API fails, the signature changed. Remove the
app from the list in System Settings, add it again, restart the app.

## Make every feature reachable three ways

Each feature gets: a menu item with a shortcut, a URL
(`<app>://action/<name>`), and an App Intent. The same action enum backs all
three, so a new action shows up everywhere at once. App Intent enum titles
must be literals, so they can drift from menu titles: add a self-test check
that they match. The URL also lets
`test-mac-app` drive the feature from a script.

Done when every entry point in the brief's "System hooks" works from a
clean install, and Settings shows the state of every permission it needs.

© daveebbelaar · MIT · daveebbelaar/bama

Similar skills

All skills for Backend and APIs →

From the same set21

The whole set →
performance performance — a skill for Claude Code that measures CPU, memory, and energy usage in macOS apps. It identifies causes of freezes and helps offload tasks from the main thread to the GPU. CX Codex +1 1,000installs improve-architecture The improve-architecture Claude Code skill reviews a macOS Swift codebase and plans refactors that preserve existing behavior. It activates before a major feature, at a milestone, or when bugs keep returning in one area. CX Codex +1 1,000installs app-brief The app-brief skill for Claude Code and Cursor generates a one-page docs/BRIEF.md file for a new macOS app before writing code. CX Codex +1 1,000installs design-from-app design-from-app — a Claude Code skill that rebuilds any app interface as a native SwiftUI design kit using reference screenshots. CX Codex +1 1,000installs layout-grid layout-grid is a Claude Code skill that enforces grid and alignment rules in macOS SwiftUI apps. It runs when building custom UI components or after layout changes. CX Codex +1 1,000installs user-stories Turns app briefs, research, or screen indexes into prioritized user stories with checkable acceptance criteria. It runs after app-brief or clone, or when asked to plan features and choose what to build first. CX Codex +1 1,000installs swift-swiftui The swift-swiftui Claude Code skill sets Swift 6 and SwiftUI practices for macOS apps. It activates while writing, reviewing, or debugging Swift code, including concurrency and Sendable errors. CX Codex +1 1,000installs design-kit design-kit — a skill for Claude Code and Cursor builds a custom macOS SwiftUI design system with tokens and components. Runs when you need a brand look or custom controls. CX Codex +1 1,000installs

Project sponsors

Companies that keep this analytics open