SuperIslandSuperIsland
API Reference

DynamicIsland.system

Read system data — AI usage, notifications, WhatsApp Web state.

DynamicIsland.system

Access system-level data. Individual methods require their own permissions.


AI Usage

system.getAIUsage()

Returns usage data for Codex and Claude. Requires "usage" permission.

const usage = await DynamicIsland.system.getAIUsage();

Response:

{
  codex: {
    remaining: number,     // 0–100 (percentage remaining)
    status: "healthy" | "low" | "blocked",
    resetAt: string,       // ISO date string
  } | null,
  claude: {
    remaining: number,
    status: "healthy" | "low" | "blocked",
    resetAt: string,
  } | null,
}

Example:

async compact() {
  const usage = await DynamicIsland.system.getAIUsage();
  const codexColor = usage.codex?.status === "healthy" ? "#22c55e"
    : usage.codex?.status === "low" ? "#f59e0b" : "#ef4444";

  return View.hstack([
    View.circularProgress(usage.codex?.remaining ?? 0, {
      total: 100, lineWidth: 2, color: codexColor,
    }),
    View.text("Codex", { style: "caption2", color: "#888" }),
  ]);
}

Notifications

system.getLatestNotification()

Returns the most recent notification mirrored to SuperIsland.

const latest = DynamicIsland.system.getLatestNotification();

Response:

{
  appName: string,
  title: string,
  body: string,
  timestamp: number,   // Unix ms
  appIcon?: string,    // Base64 encoded app icon
} | null

system.getRecentNotifications(limit?)

Returns an array of recent notifications.

const recent = DynamicIsland.system.getRecentNotifications(5);
// Returns up to 5 most recent notifications

Example:

expanded() {
  const notifs = DynamicIsland.system.getRecentNotifications(3);

  if (!notifs || notifs.length === 0) {
    return View.text("No recent notifications", { color: "#555" });
  }

  return View.vstack(
    notifs.map((n) =>
      View.hstack([
        View.text(n.appName, { style: "caption", bold: true }),
        View.spacer(),
        View.text(n.title, { style: "caption2", color: "#888", lineLimit: 1 }),
      ])
    ),
    { spacing: 4 }
  );
}

WhatsApp Web

system.getWhatsAppWeb(limit?)

Returns WhatsApp Web state and recent messages.

const state = await DynamicIsland.system.getWhatsAppWeb(5);

Response:

{
  status: "connected" | "connecting" | "qr" | "disconnected",
  qrCode?: string,      // Base64 QR code image (when status === "qr")
  messages: Array<{
    sender: string,
    body: string,
    timestamp: number,
    isGroup: boolean,
  }>,
}

system.startWhatsAppWeb()

Initiates the WhatsApp Web pairing flow (shows QR code).

DynamicIsland.system.startWhatsAppWeb();

system.refreshWhatsAppWebQR()

Refreshes the QR code if it expired.

system.sendWhatsAppWebMessage(recipient, message)

Send a WhatsApp message.

await DynamicIsland.system.sendWhatsAppWebMessage("+1234567890", "On my way!");

On this page