Overview

Adanotch extensions are lightweight, secure TypeScript programs that place their own custom view right beside your MacBook's notch in the compact area and inside the full island card when expanded. A hardware monitor, live weather glance, pending GitHub pull requests, pomodoro timer, or status panel for your servers can be built in minutes.

const { activity, ui, system } = AdanotchKit;

activity({
  async update() {
    const { cpuPercent } = await system.stats();
    return {
      compact: { leading: ui.icon("cpu"), trailing: ui.text(`${cpuPercent}%`) },
      expanded: ui.ring(cpuPercent, { label: "CPU" }),
    };
  },
});

1-Minute QuickstartCopy Anchor Link

Get your first extension up and running in just three steps:

adanotch --help

adanotch init my-widget --name "My First Widget"
cd my-widget
npm install

npm run watch   # Rebuilds dist/index.js on file changes
adanotch dev    # Loads into Adanotch and live-reloads on save

Two Views: Compact & Expanded IslandCopy Anchor Link

Adanotch extensions provide two distinct user interface surfaces:

compact: {
  leading: ui.icon("cloud.sun.fill", { tone: "accent" }),
  trailing: ui.text("21°", { style: "mono" })
}

Architecture & Core PrinciplesCopy Anchor Link

The Adanotch extension ecosystem is designed around speed, battery efficiency, and strict security:

• Native SwiftUI Rendering: No HTML, CSS, or DOM overhead. Your extension returns a lightweight JSON node tree that Adanotch renders using native SwiftUI on macOS. Enjoy smooth 120 FPS ProMotion animations with zero webview overhead.
• Isolated JavaScriptCore Process: Every extension runs in its own process, isolated from the main Adanotch application. If an extension crashes or hangs, only its process restarts—the island never freezes.
• Strict Permission Model: Extensions can only access resources explicitly declared in manifest.json and approved by the user: system stats, domain-scoped network requests, clipboard, calendar, and media events.
• macOS Integration: Full support for SF Symbols, system Dark Mode tones, Keychain-secured credentials, and native global shortcuts.

Templates & Popular Use-CasesCopy Anchor Link

Explore ready-to-use patterns and use them directly as starting points:

Building with AI Coding AgentsCopy Anchor Link

Adanotch provides a first-class developer experience with AI coding tools like Claude Code, Codex, Antigravity CLI, and Cursor.

With the bundled SKILL.md rules inside the extension project, prompt your AI assistant naturally:

# In your terminal or Cursor/Claude chat:
"Write an Adanotch extension that tracks MacBook battery health and remaining charging time"

The AI agent will generate compliant manifest.json permissions, src/index.ts, and test suites based on adanotch.d.ts. You can verify your extension instantly using npm test and adanotch lint.

Quick Reference GuidesCopy Anchor Link

Frequently Asked QuestionsCopy Anchor Link