DesktopRenamer exposes a local API using macOS Distributed Notifications. This allows external applications and scripts to query the current desktop space name, number, and UUID, or retrieve a list of all renamed spaces.

1. Open DesktopRenamer.
2. Go to Settings → General → Advanced.
3. Ensure Enable API is toggled ON.

All communication happens via DistributedNotificationCenter.

Request the details of the currently active space.

• Post Notification: com.michaelqiu.DesktopRenamer.GetActiveSpace
• Listen For: com.michaelqiu.DesktopRenamer.ReturnActiveSpace
• Response UserInfo Payload:

  {
    "spaceName": "Coding",     // String
    "spaceNumber": 1,          // Number (Int)
    "spaceUUID": "UUID-..."    // String (or "FULLSCREEN")
  }

Request a list of all configured spaces.

• Post Notification: com.michaelqiu.DesktopRenamer.GetSpaceList
• Listen For: com.michaelqiu.DesktopRenamer.ReturnSpaceList
• Response UserInfo Payload:

  {
    "spaces": [
      {
        "spaceName": "General",
        "spaceNumber": 1,
        "spaceUUID": "..."
      },
      {
        "spaceName": "Music",
        "spaceNumber": 2,
        "spaceUUID": "..."
      }
    ]
  }

If you are building another Mac app or a Swift script:

import Foundation

let center = DistributedNotificationCenter.default()

// 1. Define the observer
class SpaceObserver {
    init() {
        center.addObserver(
            self,
            selector: #selector(receiveSpaceInfo(_:)),
            name: NSNotification.Name("com.michaelqiu.DesktopRenamer.GetActiveSpace"),
            object: nil,
            suspensionBehavior: .deliverImmediately
        )
    }

    @objc func receiveSpaceInfo(_ note: Notification) {
        guard let info = note.userInfo else { return }
        print("Space Name: \(info["spaceName"] ?? "Unknown")")
        print("Space #: \(info["spaceNumber"] ?? 0)")
    }

    func requestUpdate() {
        center.postNotificationName(
            NSNotification.Name("com.michaelqiu.DesktopRenamer.GetActiveSpace"),
            object: nil,
            userInfo: nil,
            deliverImmediately: true
        )
    }
}

// 2. Run it
let observer = SpaceObserver()
observer.requestUpdate()
RunLoop.main.run()

Useful for scripting or integration with tools like Alfred/Raycast extensions.

import Foundation
from AppKit import NSObject, NSApplication, NSApp

REQUEST_NOTE = "com.michaelqiu.DesktopRenamer.GetActiveSpace"
RESPONSE_NOTE = "com.michaelqiu.DesktopRenamer.ReturnActiveSpace"

class Handler(NSObject):
    def callback_(self, notification):
        info = notification.userInfo()
        print(f"Space: {info['spaceName']} (#{info['spaceNumber']})")
        # Exit after receiving (optional)
        NSApp.terminate_(None)

dist_center = Foundation.NSDistributedNotificationCenter.defaultCenter()
handler = Handler.new()

# Register Listener
dist_center.addObserver_selector_name_object_(
    handler,
    "callback:",
    RESPONSE_NOTE,
    None
)

# Send Request
print("Requesting space info...")
dist_center.postNotificationName_object_userInfo_deliverImmediately_(
    REQUEST_NOTE,
    None,
    None,
    True
)

# Start Loop
NSApplication.sharedApplication()
NSApp.run()

Perfect for displaying the space name in your own custom menu bar or HUD.

local apiRequest = "com.michaelqiu.DesktopRenamer.GetActiveSpace"
local apiResponse = "com.michaelqiu.DesktopRenamer.ReturnActiveSpace"

-- 1. Setup Listener
local watcher = hs.distributednotifications.new(function(name, object, userInfo)
    if name == apiResponse then
        print("Current Space: " .. userInfo.spaceName)
        hs.alert.show("Space: " .. userInfo.spaceName)
    end
end, apiResponse)

watcher:start()

-- 2. Function to trigger request
function getSpaceName()
    hs.distributednotifications.post(apiRequest)
end

-- Bind to a hotkey (e.g., Cmd+Opt+Control+S)
hs.hotkey.bind({"cmd", "alt", "ctrl"}, "S", getSpaceName)

• No Response?

  • Check if Enable API is ON in DesktopRenamer settings.
  • Ensure your script keeps running (RunLoop). Distributed notifications are asynchronous; if your script exits immediately after sending the request, it won't receive the response.
  • Ensure you set deliverImmediately: true (or equivalent) in your sender code.

• Sandbox Issues:

  • If you are calling this from a strictly sandboxed application (like one from the Mac App Store), DistributedNotificationCenter might be blocked unless specific entitlements are present. Scripts and non-sandboxed apps (like Hammerspoon) work by default.