Applescript Jxa

AppleScript & JXA (JavaScript for Automation)

When to Use

Trigger when automating macOS apps natively: clicking UI elements, typing text, controlling Finder, driving Safari/Chrome, showing dialogs, or integrating shell commands. Use JXA for complex logic; use AppleScript when scripting dictionaries are better documented in AppleScript.

Core Rules

• Run scripts via osascript -e '...' (inline) or osascript script.applescript (file)
• JXA files use .js extension: osascript -l JavaScript script.js
• System Events is required for UI scripting — must enable in System Settings > Privacy > Accessibility
• Prefer JXA for anything requiring loops, data transformation, or API calls
• AppleScript string concatenation uses & not +
• JXA uses standard JS syntax — async is NOT supported; use delay() for pauses

AppleScript Basics

Syntax fundamentals

-- Comments start with --
-- Variables
set myVar to "hello"
set myNum to 42
set myList to {1, 2, 3}

-- String concatenation
set greeting to "Hello, " & "world"

-- Conditionals
if myNum > 10 then
    display dialog "Big number"
else
    display dialog "Small number"
end if

-- Repeat loops
repeat with i from 1 to 5
    log i
end repeat

repeat with item in myList
    log item
end repeat

-- Functions (handlers)
on greet(name)
    return "Hello, " & name
end greet

set result to greet("Example User")

tell blocks

-- Target an application
tell application "Finder"
    set frontWindow to front window
    set folderPath to POSIX path of (target of frontWindow as alias)
end tell

-- Nested tell
tell application "System Events"
    tell process "Finder"
        click menu item "New Folder" of menu "File" of menu bar 1
    end tell
end tell

Running shell commands from AppleScript

set output to do shell script "ls ~/Desktop"
set output to do shell script "echo $HOME" with administrator privileges
set filePath to do shell script "date +%Y-%m-%d"

JXA Basics

Structure

// JXA: run via `osascript -l JavaScript script.js`

function run(argv) {
  // argv is array of CLI arguments
  const app = Application.currentApplication();
  app.includeStandardAdditions = true;

  const result = app.displayDialog("Hello from JXA!", {
    defaultAnswer: "",
    buttons: ["Cancel", "OK"],
    defaultButton: "OK",
  });

  return result.textReturned;
}

Application access

const finder = Application("Finder");
const safari = Application("Safari");
const systemEvents = Application("System Events");

// Activate (bring to front)
finder.activate();

// Check if running
finder.running(); // true/false

Dialogs & Notifications

AppleScript

-- Basic dialog
display dialog "Message here" buttons {"Cancel", "OK"} default button "OK"

-- Input dialog
set userInput to text returned of (display dialog "Enter value:" default answer "")

-- Choose from list
set chosen to choose from list {"Apple", "Banana", "Cherry"} with prompt "Pick one:"

-- File chooser
set chosenFile to POSIX path of (choose file with prompt "Select a file:")

-- Folder chooser
set chosenFolder to POSIX path of (choose folder with prompt "Select folder:")

-- Notification
display notification "Task complete" with title "My Script" subtitle "Step 1"

-- Alert (no input)
display alert "Error occurred" message "Could not connect." as critical

JXA

const app = Application.currentApplication();
app.includeStandardAdditions = true;

// Dialog with input
const result = app.displayDialog("Enter your name:", {
  defaultAnswer: "Example User",
  buttons: ["Cancel", "OK"],
  defaultButton: "OK",
  withTitle: "Input Required",
});
const name = result.textReturned;

// Choose from list
const chosen = app.chooseFromList(["Option A", "Option B", "Option C"], {
  withPrompt: "Select an option:",
  defaultItems: ["Option A"],
});

// Notification
app.displayNotification("Done!", { withTitle: "Script Complete", subtitle: "All steps finished" });

System Events (UI Scripting)

Click a button / menu item

tell application "System Events"
    tell process "Finder"
        -- Click a button
        click button "OK" of window 1

        -- Click menu item
        click menu item "Preferences…" of menu "Finder" of menu bar 1

        -- Type text
        keystroke "hello world"
        keystroke return

        -- Key combos
        key code 0 using {command down}  -- Cmd+A (select all)
        keystroke "c" using {command down}  -- Cmd+C (copy)
        keystroke "v" using {command down}  -- Cmd+V (paste)
        keystroke "z" using {command down, shift down}  -- Cmd+Shift+Z

        -- Click at coordinates
        click at {500, 300}
    end tell
end tell

JXA System Events

const se = Application("System Events");
const proc = se.processes["Finder"];

// Click a button
proc.windows[0].buttons.whose({ name: "OK" })[0].click();

// Type text
se.keystroke("hello world");
se.keyCode(36); // Return key

// Key combo: Cmd+A
se.keystroke("a", { using: "command down" });

Finder Automation

tell application "Finder"
    -- Get desktop path
    set desktopPath to POSIX path of (path to desktop)

    -- List files in folder
    set fileList to every file of folder (POSIX file "~/Desktop" as alias)
    repeat with f in fileList
        log name of f
    end repeat

    -- Create new folder
    make new folder at desktop with properties {name: "New Folder"}

    -- Move file
    move file "~/Desktop/file.txt" to folder "~/Documents"

    -- Open folder in new window
    open POSIX file "~/Documents"

    -- Reveal file in Finder
    reveal POSIX file "~/Desktop/report.pdf"
    activate
end tell

Safari Automation (JXA)

const safari = Application("Safari");
safari.activate();

// Get current URL
const url = safari.documents[0].url();
const title = safari.documents[0].name();

// Navigate to URL
safari.documents[0].url = "https://example.com";

// Execute JavaScript in page
const pageTitle = safari.doJavaScript("document.title", { in: safari.documents[0] });
const bodyText = safari.doJavaScript("document.body.innerText", { in: safari.documents[0] });

// Click element via JS
safari.doJavaScript("document.querySelector('#submit-btn').click()", { in: safari.documents[0] });

// Fill form field
safari.doJavaScript("document.querySelector('#email').value = 'test@example.com'", {
  in: safari.documents[0],
});

Chrome Automation (JXA)

const chrome = Application("Google Chrome");
chrome.activate();

const tab = chrome.windows[0].activeTab;

// Get URL and title
const url = tab.url();
const title = tab.title();

// Navigate
tab.url = "https://example.com";

// Execute JS
const result = chrome.execute(tab, { javascript: "document.title" });

// Open new tab
chrome.windows[0].tabs.push(chrome.Tab({ url: "https://google.com" }));

Clipboard Operations

-- AppleScript
set the clipboard to "text to copy"
set clipText to the clipboard

// JXA
const app = Application.currentApplication();
app.includeStandardAdditions = true;

// Set clipboard
app.setTheClipboardTo("text to copy");

// Get clipboard
const clipText = app.theClipboard();

Running from Claude Code (osascript)

# Inline AppleScript
osascript -e 'display notification "Build complete!" with title "Claude Code"'

# Inline JXA
osascript -l JavaScript -e '
  const app = Application.currentApplication();
  app.includeStandardAdditions = true;
  app.displayNotification("Done!", { withTitle: "Claude Code" });
'

# From file
osascript ~/scripts/my-macro.applescript
osascript -l JavaScript ~/scripts/my-script.js

# Pass arguments to JXA
osascript -l JavaScript script.js "arg1" "arg2"
# Access via: function run(argv) { const arg = argv[0]; }

# Capture output in shell
RESULT=$(osascript -e 'return "hello from AppleScript"')
echo $RESULT

Shell Script Integration

-- Run shell, capture output, use in script
set gitStatus to do shell script "cd ~/project && git status --short"
if gitStatus is not "" then
    display dialog "Uncommitted changes:\n" & gitStatus
end if

-- Open terminal and run command
tell application "Terminal"
    activate
    do script "cd ~/project && npm run dev"
end tell

-- Run with admin privileges
do shell script "rm -rf /tmp/cache" with administrator privileges

Practical Examples

Show a clipboard transform notification

osascript -l JavaScript << 'EOF'
const app = Application.currentApplication();
app.includeStandardAdditions = true;
const se = Application("System Events");

// Read clipboard, transform, write back
const clip = app.theClipboard();
const upper = clip.toUpperCase();
app.setTheClipboardTo(upper);
app.displayNotification("Clipboard uppercased!", { withTitle: "Transform" });
EOF

Launch app if not running

if application "Obsidian" is not running then
    tell application "Obsidian" to activate
    delay 2
end if
tell application "Obsidian" to activate

Batch rename files on Desktop

// JXA batch rename
const finder = Application("Finder");
const desktop = finder.desktop;
const files = desktop.files();

files.forEach((file, i) => {
  const name = file.name();
  if (name.startsWith("Screen Shot")) {
    file.name = `screenshot-${String(i).padStart(3, "0")}.png`;
  }
});

Related Skills

• keyboard-maestro — Mac automation orchestration
• shortcuts-skill — Apple Shortcuts automation
• obsidian-automation — Obsidian via AppleScript

GitNexus Index

This skill is indexed by GitNexus for knowledge graph traversal. Index path: /Users/localuser/.claude/skills/applescript-jxa/.gitnexus Last indexed: 2026-05-23