app.process - Process Management API

Manage and monitor system processes.

Process Information

app.process.list()

Get a list of all running application processes.

Returns: array - Array of process information

local processes = app.process.list()
for _, p in ipairs(processes) do
    app.log.info(p.name .. " (PID: " .. p.pid .. ")")
end

-- Each process contains:
-- {
--     pid = 1234,
--     name = "Safari",
--     bundleId = "com.apple.Safari",     -- optional
--     path = "/Applications/Safari.app", -- optional
--     executable = "/Applications/Safari.app/Contents/MacOS/Safari",  -- optional
--     isActive = true,
--     isHidden = false,
--     activationPolicy = "regular"  -- "regular" | "accessory" | "prohibited"
-- }

app.process.info(pid)

Get detailed information for a specific PID.

Parameters:

• pid (number) - Process ID

Returns: table|nil - Process information or nil

local info = app.process.info(1234)
if info then
    app.log.info("Process name: " .. info.name)
    app.log.info("Launch time: " .. (info.launchDate or "Unknown"))
    app.log.info("Is active: " .. tostring(info.isActive))
    app.log.info("Is terminated: " .. tostring(info.isTerminated))
    app.log.info("Owns menu bar: " .. tostring(info.ownsMenuBar))
end

app.process.current()

Get current process information.

Returns: table - Current process information

local current = app.process.current()
app.log.info("PID: " .. current.pid)
app.log.info("Process name: " .. current.name)
app.log.info("Hostname: " .. current.hostName)
app.log.info("User: " .. current.userName)
app.log.info("System uptime: " .. current.systemUptime .. " seconds")

-- Returns:
-- {
--     pid = 1234,
--     name = "FinderSyncExt",
--     arguments = {...},      -- Command line arguments
--     environment = {...},    -- Environment variables
--     hostName = "MacBook-Pro.local",
--     userName = "username",
--     systemUptime = 123456.789
-- }

Process Search

app.process.find(name)

Find processes by name. Matches application name or Bundle ID (case-insensitive, partial match).

Parameters:

• name (string) - Process name or Bundle ID

Returns: array - Array of matching process information

local safaris = app.process.find("Safari")
-- Returns all processes whose name or Bundle ID contains "safari"

local chromes = app.process.find("com.google.Chrome")
-- Can also search by Bundle ID

app.process.findByPath(path)

Find processes by path. Matches application path or executable path (partial match).

Parameters:

• path (string) - Application path

Returns: array - Array of matching process information

local apps = app.process.findByPath("/Applications/")
-- Returns all application processes under /Applications/

app.process.isRunning(name)

Check if a process with the specified name is running. Exact match on application name or Bundle ID (case-insensitive).

Parameters:

• name (string) - Process name or Bundle ID

Returns: boolean

if app.process.isRunning("Safari") then
    app.log.info("Safari is running")
end

if app.process.isRunning("com.apple.Safari") then
    app.log.info("Safari is running")
end

app.process.pidOf(name)

Get the PID of a process with the specified name. Exact match on application name or Bundle ID (case-insensitive).

Parameters:

• name (string) - Process name or Bundle ID

Returns: number|nil - PID or nil

local pid = app.process.pidOf("Safari")
if pid then
    app.log.info("Safari PID: " .. pid)
end

Process Control

app.process.kill(pid)

Terminate the process with the specified PID. Attempts graceful termination first, then forces termination if that fails.

Parameters:

• pid (number) - Process ID

Returns: boolean - Whether successful

local success = app.process.kill(1234)
if success then
    app.log.info("Process terminated")
else
    app.log.error("Failed to terminate process")
end

app.process.killByName(name)

Terminate processes by name. Exact match on application name or Bundle ID (case-insensitive).

Parameters:

• name (string) - Process name or Bundle ID

Returns: number - Number of processes terminated

local count = app.process.killByName("Safari")
app.log.info("Terminated " .. count .. " Safari processes")

activationPolicy Description

Examples

Check if an Application is Running

function MyPlugin:checkAppRunning(appName)
    if app.process.isRunning(appName) then
        app.dialog.alert({
            title = "Running",
            message = appName .. " is running"
        })
    else
        app.dialog.alert({
            title = "Not Running",
            message = appName .. " is not running"
        })
    end
end

Get List of Running Applications

function MyPlugin:handleListApps(context)
    local processes = app.process.list()

    -- Filter regular applications
    local apps = {}
    for _, p in ipairs(processes) do
        if p.activationPolicy == "regular" then
            table.insert(apps, p.name .. " (" .. p.pid .. ")")
        end
    end

    app.dialog.alert({
        title = "Running Applications (" .. #apps .. ")",
        message = table.concat(apps, "\n")
    })
end

Terminate a Resource-Intensive Application

function MyPlugin:handleKillApp(context)
    local result = app.dialog.form({
        title = "Terminate Application",
        fields = {
            {type = "text", id = "name", label = "Application Name", default = ""}
        }
    })

    if not result or result.name == "" then return end

    local pid = app.process.pidOf(result.name)
    if not pid then
        app.dialog.alert({title = "Notice", message = "Application not found"})
        return
    end

    local info = app.process.info(pid)
    local confirm = app.dialog.alert({
        title = "Confirm Termination",
        message = "Terminate " .. (info and info.name or result.name) .. "?",
        buttons = {"Cancel", "Terminate"}
    })

    if confirm == "Terminate" then
        if app.process.kill(pid) then
            app.notification.show("Done", "Terminated " .. result.name)
        else
            app.notification.show("Failed", "Unable to terminate " .. result.name)
        end
    end
end