This article covers:
- What is Toggl Desktop
- Tracking Time and Managing Data in List and Timeline View
- Managing Preferences
- Keyboard Shortcuts and MacOS TouchBar Integration
What is Toggl Desktop?
Toggl Desktop for Mac is a native macOS application that can be installed on your computer. It works seamlessly with the web version of Toggl, syncing data on the fly. Toggl Desktop also works offline; it stores data locally and sends it to the Toggl server once you’re back online.
Download the App
Click here to download the app! Please note that this version of Toggl Desktop works only on macOS 10.11 El Capitan or newer.
Toggl Desktop is also available on App Store! If you prefer the App Store update system more than the current automatic updater, you are more than welcome to switch to the App Store version of Toggl Desktop.
Please note, the App Store version will not automatically update unless you have enabled this setting in System Preferences.
Tracking Time and Managing Data in List and Timeline View
The app offers two views; List and Timeline, bringing our Timeline feature into the desktop app and allowing users to add/edit time entries directly in it. Both views allow you to track and edit time entries.
Toggl Desktop will switch between Light and Dark mode based on your macOS preferences.
List-view can display each time entry individually or it can group entries with the same description and project together.
You can load up to a 60 days worth of time entries for a better overview by clicking “Load more” at the bottom of the list.
1. Using the Timer
Tracking time with the desktop agent is as simple as it could possibly be.
Fill in the details of what you’re doing in the “What are you doing?” field, and click on the green “play” button to start the timer.
If you start the timer first and wish to add the details later, just click on the timer and a popup window appears where you’re able to edit the description, project, tags, duration, start/stop times and the date. On paid plans, you’re also able to mark the entry as “Billable” or not.
To make it easier to differentiate, the Toggl Desktop icon on your dock will be red when the timer is running, and grey when it is not. The same applies to the menu bar, but in different colors: black or transparent.
2. Adding manual entries in List-view
You can use Manual Mode if you want to add time entries at a later time. To switch to Manual Mode, open the Toggl Desktop menu from the menu bar and click “Switch Mode” (Keyboard shortcut: ⌘D).
Here's what the app will look like in Manual Mode.
3. Editing time entries in List-view
Editing your time entries in the desktop app has the same basics – just click on the entry you wish to edit and a similar popup window appears. Once you’re done editing, close the popup window. Changes are saved automatically. To continue a time entry, just click on the arrow button next to the time entry.
To rearrange your data and move an entry to a different date use drag-and-drop.
The Timeline view shows your tracked time in a vertical timeline side-by-side with your activity data. You can switch Timeline on at the top of this view, as well as switch the date, and zoom in and out (keyboard shortcuts: ⌘+ and ⌘-).
Please note: On macOS 10.15 the desktop app needs Screen Recording permissions to access complete data for the Timeline feature. If permissions are not granted, the Timeline feature will still work, but it will only display the application name and not the window title for additional details. A warning will appear when users switch on Timeline if they need to provide these permissions.
Time entries are shown as “pills”, color-coded to match the project they belong to on the left next to the date.
Information relating to the time entry is displayed while hovering over the item, or to the right of the pill if there are no overlapping time entries for the period. However, if an overlapping entry is found, this information is not displayed and can be viewed by hovering over the item.
Timeline activity is shown on the right and is only visible to the logged-in user. This data allows you to quickly compare your actual time entries with your activity, and make any changes necessary in one view. The darker a blue pill is in the activity view, the more active you were during that period of 15-minutes.
1. Adding time entries in Timeline view
To add a new entry, click on that place in the timeline to create a new entry and add details.
Here you can add a description, choose a project and task, add tags just as while adding time in List-view.
2. Editing time entries in Timeline-view
To edit a time entry, click on it and a popup will open where you can edit details. You can also drag and drop an existing time entry to a different time of the day, or resize a pill to change the duration on the time entry.
3. Managing overlapping entries
When two entries overlap, you can right-click on the latter time entry to adjust the start or end time to remove the overlap. A menu will allow you to choose between updating the stop time of the first entry or updating the start time of the second one.
4. Filling in gaps
When there is a gap in your day, a pill with a dashed border will show the empty space between time entries. Clicking on it will create a time entry with the exact start and end time you need to fill in the gap.
Adding Projects in the Desktop app
Projects can be added while editing time entries, including the one currently running.
In the edit popup window, select “Add New Project”. From where you can define the project name, color (customizable colors available on paid plans only), workspace and client. You can also enter the description for the entry you’re editing. When you’re done, click on the X button in the top right corner of the popup.
Toggl syncs all your entries back to the web automatically. However, if there is an issue with the app connecting to our server you may have unsynced entries. For more details on how Toggl sync works, open this syncing article.
You will see a warning next to your entry in the form of a red exclamation mark in the center of a pink triangle. If this happens, navigate to the Menu bar, and click Account > Sync.
If the sync is unsuccessful, please log out and log back into the desktop. To avoid data loss, be sure to make note of any unsynced entries which will then need to be added manually.
To edit the settings of your desktop agent, just click Toggl Desktop in the menu bar and then choose Preferences.
Preferences are divided into 4 tabs and shown one section at a time. This is what you’ll see.
1. Preferences – General tab
Show/Hide Toggl: Set a global shortcut to show or hide the Toggl app. This will work even when the app is not in focus.
Continue/Stop Timer: Set a global shortcut to continue or stop the Toggl Timer. This will work even when the app is not in focus.
Idle detection: Get notified of the time that you’ve been inactive/away from the keyboard. The notification will popup after an X number of minutes as set in your preferences.
After the notification has popped up, you can decide whether you want to keep the time or discard it. Here’s what it looks like:
The popup has four options for you to choose from:
- Discard idle time: Discards idle time, and stops the running timer from when you went idle.
- Discard idle and continue: Discards the idle time, but starts a new time entry that matches the previously running timer so you can resume work.
- Keep idle time: Ignores idle time, and adds it to the currently running time entry.
- Add idle time as new time entry: Stops previously running timer, and adds idle time as a new time entry.
The Cancel button at the bottom will also ignore the idle time, and add it to the currently running time entry.
Tick the ‘Pomodoro Timer’ option to enable it and set your preferred intervals for both work and break cycles.
Clicking Continue at the end of a break cycle restarts the last time entry you were using. Clicking Continue at the end of a work cycle continues the running time entry.
Show Project on Menu Bar: View the Project for the current timer on the Menu bar next to the Toggl Icon
Show Dock Icon: Show/Hide Toggl icon on your Doc.
Other configurable options:
- Keep Toggl on top of other windows.
- Stop running entry on computer sleep/shutdown.
- Focus app on global shortcut. This will always put the app into focus when using the Continue/Stop timer shortcut.
- Open Edit view when starting a time entry.
Default project: Pick one project that you use the most, and fill it in automatically whenever you start a time-entry without a project. If needed you can still change the project for both running and stopped time-entries.
Change duration when changing start time: Choose whether you want the duration updated when a time entry’s start time is updated.
Show Toggl in Touch Bar: feature to be removed soon
2. Preferences – Proxy tab
Under the Proxy tab you can configure proxy settings if you happen to be behind a proxy.
If you tick the ‘Use system proxy settings’ checkbox, Toggl Desktop will use the same proxy settings you have set up for your system.
3. Preferences – Autotracker tab
Under the Autotracker tab you can define applications or keywords and projects they connect to.
If an application with the keyword is in the foreground it triggers the AutoTracker. When the tracker is triggered it shows you a notification and asks if you would like to track time under the project you chose. Keep in mind that the AutoTracker notification will only trigger if you do not have a timer already running.
4. Preferences – Reminder tab
Under the Reminder tab you’re able to customize your tracking reminders. These reminders are triggered when the Toggl Desktop app is running but there are no running entries. This tab allows you to set the days on which the reminders are active as well as the time of day when they can trigger.
Note: If can't see any notifications from our desktop app, please make sure that Do Not Disturb is off.
Keyboard Shortcuts and MacOS TouchBar Integration
Toggl Desktop sports several keyboard shortcuts for fast time entry, and also supports the Macbook Pro Touch Bar.
- ⌘ N creates a new time entry and displays the edit window
- ⌘ D changes between timer and manual mode
- ⌘ S stops the running time entry
- ⌘ O continues the last recorded time entry
- ⌘ E open running entry in edit popup
There are context-specific shortcuts to make navigating inside the app easier:
Switching between timer and Time entry listing
- SHIFT+DOWN – Focuses the Time entry listing
- ESC – If the edit popup is opened it always closes the popup (even if listing is focused). If edit popup is not opened and entries list is focused it will switch the focus to Timer.
Moving inside Time entries listing
- UP/DOWN – switch between selected time entry
- ENTER – open the edit view of selected time entry
- SPACE – continue the selected time entry
- BACKSPACE – delete the selected time entry
- LEFT ARROW – collapses grouped time entries
- RIGHT ARROW – expands grouped time entries
Timeline View Zoom
- ⌘+ – Zooms in
- ⌘- – Zooms out
Macbook Pro Touch Bar Controls
- Time Entries List: Shows the last 10 unique entries in the list. Users can quickly start a time entry by tapping on it.
- Start/Stop Button: This functions like the Start button in the app.
- Running Time Entry: Shows the current running time entry.
Toggl Desktop is an open-source project. You’re welcome to help us by submitting pull requests, bug reports, or feature requests to our GitHub page.
Still confused about how the MacOS app works? Feel free to contact our support team!