Developer API & Integrations

Overview & Architecture

Snapframe is architected from the ground up to be a programmable desktop layer. While traditional macOS window managers are purely static, Snapframe combines custom grid layouts with a background coordination daemon.

The application runs a lightweight HTTP server implemented in native Swift using Apple’s Network.framework (NWListener). It consumes less than 12 MB of RAM and responds to local POST requests in under 2 milliseconds.

Quickstart (30 seconds)

Make sure Snapframe is running on your Mac. Open Terminal and send your first status ping to any active application window:

curl http://localhost:8999/overlay \
  -d '{"app": "Finder", "status": "Copying 42 files", "progress": 0.5}'

Snapframe matches the window, attaches the floating status bar, and smoothly animates the progress meter.

Local Daemon (:8999)

The daemon listens on default port 8999. You can change this port in Snapframe Preferences → Developer Settings if needed. It includes standard Cross-Origin Resource Sharing (CORS) headers, allowing browser-based tools, Chrome DevTools extensions, and local web applications to post updates seamlessly.

POST /overlay Endpoint

The core API endpoint for updating floating Snap Bars. You can target windows by application name, macOS bundle identifier, or process ID (PID).

Request Parameters (JSON Body)

Developer API & Upload Support

Any script, CI tool, CLI, or browser extension can update the progress bar instantly via the local HTTP server. Here are the canonical examples for file copies and browser uploads:

1. Finder File Copy Progress

Update the Finder window when copying, transferring, or extracting archives via rsync, cp, or custom backup scripts:

BASHCopy

curl localhost:8999/overlay \
  -d '{"app": "Finder", "status": "Copying 260 MB of 840 MB", "progress": 0.31}'

Live Finder Overlay

FinderCopying 260 MB of 840 MB31%

2. Google Chrome Upload Progress

Stream upload progress from web applications, S3 multipart uploads, or browser extensions:

BASHCopy

curl localhost:8999/overlay \
  -d '{"app": "Google Chrome", "status": "Uploading presentation.pdf (45 MB of 100 MB)", "progress": 0.45}'

Live Chrome Overlay

ChromeUploading presentation.pdf (45 MB of 100 MB)45%

Theme & Size Adaptive Styling

Snap Bars support multiple visual themes engineered for optimal contrast against light and dark macOS window headers. You can pass the "theme" property to explicitly override the app default:

Adaptive Density Sizes

Snap Bars adapt to three density profiles depending on your workspace density preferences:

• Small (12pt): Minimalist footprint showing just app name and primary stat.
• Medium (20pt, Default): Balanced layout with live dot, progress meter, and telemetry.
• Large (28pt): Expanded display for long agent thoughts, multi-line diff status, or token quotas.

Click-Through Transparency & AXUIElement

Snapframe overlays are built using native macOS NSPanel instances with ignoresMouseEvents = true. Every mouse click, drag, scroll, or hover passes cleanly through to the application underneath.

Window tracking uses native Accessibility APIs (kAXWindowMovedNotification and kAXWindowResizedNotification) so the bar stays glued to its window with zero lag during Space switches, window minimize/maximize, and multi-monitor movement.

AI Agents & Telemetry

When running multi-agent coding sessions with tools like Claude, Codex, or Antigravity, keeping track of active thinking states and remaining token context is crucial.

Post agent states directly as your workflow executes steps:

curl localhost:8999/overlay \
  -d '{
    "app": "Claude",
    "status": "Writing migration · src/db/schema.ts",
    "tokens": {"used": 54200, "total": 200000},
    "theme": "graphite"
  }'

Code Snippets & SDKs

TypeScript / Node.js Helper

export async function updateSnapBar({
  app,
  status,
  progress,
  theme,
  tokens,
}: {
  app: string;
  status: string;
  progress?: number;
  theme?: "yellow" | "blue" | "graphite" | "green" | "amber";
  tokens?: { used: number; total: number };
}) {
  try {
    await fetch("http://localhost:8999/overlay", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ app, status, progress, theme, tokens }),
    });
  } catch {
    // Graceful fallback if Snapframe is not running
  }
}

Python Helper (for AI agents & scripts)

import requests

def update_overlay(app: str, status: str, progress: float = None, theme: str = None):
    """Update Snapframe window overlay status bar."""
    payload = {"app": app, "status": status}
    if progress is not None:
        payload["progress"] = progress
    if theme is not None:
        payload["theme"] = theme
    try:
        requests.post("http://localhost:8999/overlay", json=payload, timeout=0.3)
    except Exception:
        pass

Browser Extension Content Script

// Forward XHR / Fetch upload progress to Snapframe Chrome bar
function hookUploadProgress(xhr, filename) {
  xhr.upload.addEventListener("progress", (e) => {
    if (e.lengthComputable) {
      const pct = e.loaded / e.total;
      const mbLoaded = (e.loaded / 1048576).toFixed(1);
      const mbTotal = (e.total / 1048576).toFixed(1);

      fetch("http://localhost:8999/overlay", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({
          app: "Google Chrome",
          status: `Uploading ${filename} (${mbLoaded} MB of ${mbTotal} MB)`,
          progress: pct,
          theme: "blue"
        })
      }).catch(() => {});
    }
  });
}

Extending App Compatibility

Snapframe can attach overlays to any macOS application that has an active window. By default, it resolves windows using the standard application name.

If you have customized application builds, multiple profiles, or command-line wrappers, target the window using its exact macOS Bundle Identifier:

# Find an app's bundle identifier via Terminal:
osascript -e 'id of app "Finder"'
# -> com.apple.finder

osascript -e 'id of app "Claude"'
# -> com.anthropic.claude

Then pass "bundleId" in your API call:

curl localhost:8999/overlay \
  -d '{"bundleId": "com.anthropic.claude", "status": "Reviewing codebase", "theme": "graphite"}'

Versioning & Changelog

Snapframe follows semantic versioning (MAJOR.MINOR.PATCH). All local API endpoints maintain backward compatibility.