Ways to Use CurrentKey

CurrentKey's AppleScript support opens up a world of automation. Here are some of the most interesting things you can do — many are already in the default starter script that comes with the app.

Power Commands

Scripting commands you can call from any script, Shortcut, or Terminal.

🖼

Custom Icon Alerts

Flash a custom image in the menu bar as a visual notification, for ANY reason.

The display_image command shows a custom icon in CurrentKey's menu bar area (and any assigned Banner). Use it as a glanceable alert — for example, show a red dot when a build fails, or a green check when tests pass. The image stays visible until replaced or dismissed.

tell application "CurrentKey Stats"
    -- Show a custom icon in the menu bar
    display_image "/Users/me/icons/build-fail.png"
end tell

-- Trigger from a CI webhook, shell script, etc.

Script Images guide → Custom Icons blog post →

📊

Query Stats Programmatically

Pull usage data — total time, per-app time, room time — from scripts.

CurrentKey exposes several read-only commands — totaltime_today, timeforapp_today, timeforroom_today, and more — so you can build your own dashboards, log data to a spreadsheet, or trigger alerts when you've spent too long in one app.

tell application "CurrentKey Stats"
    set total to totaltime_today
    set slackTime to timeforapp_today "Slack"
    set devRoom to timeforroom_today "Dev"
end tell

-- Use the values in a notification, log, or webhook
if slackTime > "02:00:00" then
    display notification "Over 2 hrs on Slack today" with title "Heads up"
end if

Full command list →

🧭

Navigate Rooms via Script

Jump to any Room from a script or Shortcut.

The gotoroom command switches to a Room by name. Wire it up to an Apple Shortcut, Stream Deck button, Raycast command, or anything else, for instant workspace switching without touching Mission Control. Combine with getactiveroom to build toggle logic.

-- Jump to a Room by name
tell application "CurrentKey Stats"
    gotoroom "Design"
end tell

-- Toggle between two Rooms
tell application "CurrentKey Stats"
    set current to getactiveroom
    if current = "Dev" then
        gotoroom "Design"
    else
        gotoroom "Dev"
    end if
end tell

Hotkey setup guide → AppleScript docs →

💬 Yes, you can call commands from AppleScript .scpt files, but you can also call commands from your Terminal (including from a Claude Code session or OpenClaw). osascript -e 'tell application "CurrentKey Stats" to gotoroom called "NameOfRoomHere"' is a simple one liner, but you can also issue multi-line commands and handle return values from the Terminal line as well.

Automation Ingredients

Add to your ck.scpt, which fires automatically when you switch Rooms or apps.

🧠

Conditional Room + App Logic

In starter script

Run different actions depending on which Room you're in and which app just activated.

The starter script's appChange handler shows how to combine getactiveroom with the incoming app name to build nested conditional logic. For example, you could mute notifications when Xcode activates in your "Dev" Room but leave them on everywhere else.

-- Called every time the frontmost app changes
on appChange(appName)
    tell application "CurrentKey Stats"
        set activeRoom to getactiveroom
    end tell

    if activeRoom = "Dev" then
        if appName = "Xcode" then
            -- focus mode: mute Slack
            tell application "Slack"
                set do not disturb enabled to true
            end tell
        end if
    end if
end appChange

Brainstorming use cases → AppleScript docs →

🔗

Trigger Apple Shortcuts

In starter script

Fire any Shortcut when you enter a Room — set scenes, toggle settings, and more.

The roomChange handler fires every time you land on a new Room. Use a shell command to invoke any Shortcut by name. This lets you chain entire workflows — toggle Focus modes, set HomeKit scenes, log to a journal — all from a single Room switch.

-- Called every time the active Room changes
on roomChange(roomName)
    if roomName = "Music" then
        do shell script "shortcuts run 'Music Mode'"
    else if roomName = "Work" then
        do shell script "shortcuts run 'Work Focus On'"
    end if
end roomChange

Room Change Alerts guide → AppleScript docs →

🔔

Display Notifications

In starter script

Show a native macOS notification every time you enter a Room.

A simple one-liner inside roomChange pushes a Notification Center alert with the Room name. Great for building spatial awareness when you're deep in full-screen apps and might forget which Room you're on.

on roomChange(roomName)
    display notification "Switched to " & roomName with title "CurrentKey"
end roomChange

Room Change Alerts guide →

🚀

Auto-Launch Apps

In starter script

Automatically open specific apps when you land on a Room.

Use tell application ... activate inside roomChange to bring up the tools you need for each context. Switching to your "Dev" Room can open Xcode and Terminal; switching to "Design" can launch Figma. The apps launch only if they're not already running.

on roomChange(roomName)
    if roomName = "Dev" then
        tell application "Xcode"
            activate
        end tell
        tell application "Terminal"
            activate
        end tell
    end if
end roomChange

Per-Room scripts guide →

🐍

Run Python Scripts

In starter script

Execute shell or Python scripts from a Room change trigger.

AppleScript's do shell script lets you run anything the terminal can — Python, Ruby, curl, you name it. Use it inside roomChange to log Room switches to a file, hit a webhook, or kick off a build script when you enter your "Dev" Room.

on roomChange(roomName)
    if roomName = "Dev" then
        do shell script "/usr/bin/python3 ~/scripts/on_dev_enter.py"
    end if

    -- Log every Room switch to a file
    set ts to (do shell script "date '+%Y-%m-%d %H:%M:%S'")
    do shell script "echo '" & ts & " → " & roomName & "' >> ~/room_log.txt"
end roomChange

Python automation tutorial →

🔊

Custom Sounds per Space

Play a unique sound effect when you enter each Room.

Pair CurrentKey's roomChange trigger with the macOS afplay command (or a dedicated app like Broadcasts) to play a short audio cue on every Room switch. This creates a spatial audio experience — you'll know which workspace you're on without looking.

on roomChange(roomName)
    if roomName = "Music" then
        do shell script "afplay ~/sounds/chime.aiff &"
    else if roomName = "Dev" then
        do shell script "afplay ~/sounds/click.aiff &"
    end if
end roomChange

Custom sounds tutorial →

🎯

Focus Mode per Room

Automatically toggle macOS Focus modes when you switch Rooms.

Combine roomChange with Apple Shortcuts to toggle Focus modes per Room. When you enter "Dev," turn on "Do Not Disturb"; when you enter "Comms," switch to your "Personal" Focus. This keeps your notification settings perfectly synced with your current task context.

on roomChange(roomName)
    if roomName = "Dev" then
        -- "DND On" is a Shortcut that enables Do Not Disturb
        do shell script "shortcuts run 'DND On'"
    else if roomName = "Comms" then
        do shell script "shortcuts run 'DND Off'"
    else
        -- Default: turn off all Focus modes
        do shell script "shortcuts run 'Focus Off'"
    end if
end roomChange

Per-Room scripts guide →

And these are just starting points!

View all AppleScript commands Back to homepage