Using AppleScript with Timemator

Requirements#

• Timemator for Mac, version 3.4.0 or later.
• macOS 12 or later.
• The version from timemator.com and the version from Setapp work the same.
• Reading data never needs a license. Changing data does. With an expired trial, Timemator is in read-only mode, and scripts cannot change anything either.

AppleScript is only available on the Mac. On iPhone and iPad, use Timemator's actions in the Shortcuts app instead.

What is AppleScript?#

AppleScript is the scripting language built into macOS. It reads almost like English, and it lets one app control another. A script can ask Timemator to start a timer, read what is running, or write a report to a file. You write scripts in Script Editor, which comes with every Mac, and run them from there, from the menu bar, from Shortcuts or from a hotkey.

AppleScript is easy to read but takes a little practice to write. Start with the examples below; each one works as it is. For a thorough introduction, see Apple's AppleScript Language Guide.

Example scripts#

Four scripts for the most common jobs. Copy one into Script Editor and click the run button, or download the file. All snippets on these pages are free to copy, change and share; no attribution is needed.

Start a timer#

Starts the timer for the task Design in the folder Acme. Missing folders and tasks are created, so the script works in any library. Change "Acme/Design" to the path of your own task.

-- Starts the timer for the task "Design" in the folder "Acme".
-- Missing folders and tasks are created, so the script works in any library.
-- Change "Acme/Design" to the path of your own task.
tell application "Timemator"
	set theTask to create task named "Acme/Design"
	start timer for theTask
end tell

Download script

Pause the timer#

Pauses the running timer. Nothing happens when nothing is running, so it is safe to run twice.

-- Pauses the timer. Nothing happens when nothing is running.
tell application "Timemator"
	pause timer
end tell

Download script

Show what is running#

Shows a dialog with the task being tracked and the total time you have logged today, calculated the way the Reports window does.

-- Shows what is being tracked and how much time you have logged today.
tell application "Timemator"
	set todaySummary to get time summary scope daily
	set todayMinutes to round ((total duration of todaySummary) / 60)
	if timer running then
		set statusLine to "Tracking: " & (path of current task)
	else
		set statusLine to "Nothing is being tracked."
	end if
end tell
set todayLine to "Today: " & (todayMinutes div 60) & " h " & (todayMinutes mod 60) & " min"
display dialog statusLine & return & todayLine buttons {"OK"} default button "OK"

Download script

Export last week#

Writes last week's time entries, Monday to Sunday, to a CSV file on the Desktop. It is the same file the Export window writes. An existing file of that name is replaced.

-- Exports last week's time entries (Monday to Sunday) as a CSV file on the Desktop.
set todayStart to current date
set time of todayStart to 0
set daysSinceMonday to ((weekday of todayStart) as integer) - 2
if daysSinceMonday < 0 then set daysSinceMonday to 6
set thisMonday to todayStart - daysSinceMonday * days
set lastMonday to thisMonday - 7 * days
set outputPath to (POSIX path of (path to desktop)) & "Timemator last week.csv"

tell application "Timemator"
	export time entries from lastMonday to thisMonday to file (POSIX file outputPath) as CSV
end tell

Download script

Run your scripts#

Script Editor#

Open Script Editor from Applications → Utilities, paste a script and click the run button in the toolbar (or press ⌘R). The result appears at the bottom of the window. Save the script with File → Save to keep it.

If Script Editor refuses to compile a script and reports "Expected end of line but found identifier" (or "… but found property"), the Timemator it found has no scripting dictionary: it is older than 3.4.0, or tell application "Timemator" resolved to another copy of the app on your Mac. Run path to application "Timemator" in Script Editor to see which copy that is, and update or remove it.

The Scripts menu#

macOS can show a script menu in the menu bar, with scripts that appear only while Timemator is in front.

1. In Script Editor, open Settings and switch on Show Script menu in menu bar.
2. Save your scripts to the folder ~/Library/Scripts/Applications/Timemator/. Create the folders if they do not exist; the last one must be named exactly Timemator.
3. While Timemator is the active app, open the script menu in the menu bar and pick a script.

Scripts saved to ~/Library/Scripts/ directly appear in every app.

Shortcuts#

In the Shortcuts app, add the action Run AppleScript to a shortcut and paste your script into it. The shortcut can then have a keyboard shortcut, sit in the menu bar, or run on a schedule with a Shortcuts automation. Shortcuts with a Run AppleScript action only run on the Mac, not on iPhone or iPad. See Run a script from Shortcuts for an example that takes input.

Save as an app#

In Script Editor, choose File → Export… and set File Format to Application. The result is a double-clickable app you can keep in the Dock or open with Spotlight.

Hotkeys with other tools#

Keyboard Maestro, Raycast and Alfred can each run an AppleScript on a hotkey. In Keyboard Maestro use an Execute AppleScript action, in Raycast a script command of type AppleScript, in Alfred a Run Script workflow action set to /usr/bin/osascript.

Permissions#

The first time a script controls Timemator, macOS asks whether the app that runs the script, for example Script Editor or Shortcuts, may control Timemator. Click OK once; macOS remembers the answer for that app.

Allowing an app to control Timemator lets its scripts read everything in Timemator, not only your folders, tasks and time entries but also the activity log of activity tracking: which apps you used and when, their window titles, the websites and the files. They can change and delete your data too. Timemator asks for nothing beyond this permission, so allow only apps you trust.

If you clicked Don't Allow, scripts from that app fail with the error "Not authorized to send Apple events to Timemator" (number -1743). To change the answer, open System Settings → Privacy & Security → Automation, find the app that runs your scripts and switch on Timemator under it.

If the app is not listed there, reset the permission in Terminal so that macOS asks again:

tccutil reset AppleEvents

This resets the automation permission for every app, so each will ask again the next time it controls another app.

Which automation should I use?#

Timemator can be automated in three ways on the Mac.

• Shortcuts actions. Timemator comes with actions for the Shortcuts app: Start Timer for Task, Pause Running Timer, Continue Tracking, Create Task and Create Task and Start Timer. They need no code and work on iPhone and iPad too. Use them to start and pause tracking from a shortcut, Siri or the Action button.
• AppleScript. Everything else: reading what is running and for how long, finding and editing time entries, marking entries as billed, archiving, totals per task, and exporting CSV or PDF files. Use it when a shortcut action does not cover what you need, or when another app or tool (Keyboard Maestro, Raycast, Alfred, SwiftBar, a shell script) should talk to Timemator.
• The MCP server. For AI agents and chat tools such as Codex, Claude Code, Claude Desktop and Cursor: you ask in plain words, and the agent reads and changes your time entries through Timemator's MCP server. It is off until you switch it on in Preferences → Integrations. See Using the MCP server with Timemator.

Shortcuts actions and AppleScript work from the same shortcut, since a Run AppleScript action can sit next to Timemator's own actions.

In short: agents and chat tools use the MCP server; scripts, hotkeys and menu bar tools use AppleScript; Shortcuts uses Timemator's own actions.

Write your own scripts#

Timemator's dictionary lists every command and object a script can use. To open it, start Script Editor, choose File → Open Dictionary… and pick Timemator. The Timemator Suite holds the commands for the timer, folders, tasks, time entries, reports and export.

Ready to write your own? See AppleScript Commands and Examples for snippets grouped by task, from starting a timer to exporting a report. The AppleScript Reference lists every command, class and property with its exact parameters and types.

A few things to know:

• What the dictionary does not list, a script cannot do. There is, for example, no way to change auto-tracking rules by script; a script can only read them and switch them on or off.
• Every change a script makes can be undone in Timemator with Edit → Undo, and syncs to your other devices like a change made in the app. Deleting activity records is the exception: as in the timeline, it cannot be undone, and the activity log stays on this Mac.
• If a documented command does not do what this documentation says, that is a bug; please write to support@timemator.com with the script and what happened.
• We can give only limited help with writing or debugging your own scripts.

Related#

• AppleScript Commands and Examples
• AppleScript Reference
• Using the MCP server with Timemator
• Auto-tracking manual