Stream Deck - Clockify

This plugin allows you to track, start and stop Clockify timers on your Elgato Stream Deck.

Download

You can get the plugin directly on the Elgato Marketplace!
For new releases it usually takes 1-2 days until they're approved. In the meantime you can grab a copy from the GitHub release pages.

Setup

• Basic
  • Title: Override the title being set by the plugin, leave empty otherwise
  • API Key: (required) Provide your 48 characters long Clockify API Key, which is required for the plugin to work
  • Workspace Name: (required) Write the name of the workspace you want to run/track timers in
  • Project Name: (optional) Provide the name of an existing project to run/track a timer for
  • Task Name: (optional) Set the name of the project-specific task
  • Timer Name: (optional) Specify a name for the timer you want to run/track
  • Tags: (optional) Provide a comma separated list of tags to be assigned to the timer
    • Note: If your tag contains a comma (WHY?!) use a backslash to escape it, e.g. tag1,tag\,2,tag3
  • Billable (optional) Check or uncheck the box to run the timer as billable or non-billable
• Advanced
  • Client Name: (optional) Set the client name assigned to the specified project
    • Note: If a client name is set, it has to exist, otherwise the button won't start any timer
  • Title Format: (optional) Specify the format for the title to be displayed on the button
    • This can include any of:
      • {workspaceName} : The workspace name
      • {projectName} : The project name
      • {taskName} : The task name
      • {timerName} : The timer name
      • {clientName} : The client name
      • {timer} : The current timer value when running. Blank when not running
  • Refresh Rate: (required) Define how often the plugin checks for timers started or stopped outside of the Stream Deck, the default is Automatic
    • "Automatic" checks every 5 minutes on the Free plan and every 5 seconds on paid plans, based on the plan Clockify reports for the workspace
    • Your own key presses are shown right away, the refresh rate only matters for changes made in the web app, the desktop app or on your phone
    • "Only on key press" never checks in the background
    • Keep in mind, that the Free plan only allows 30 API requests per hour for the whole workspace
  • Server Url: (required) Change from the default URL to the API URL of your own/company instance
    • Note: Starting with V1.11 the URL should not end with /v1

StreamDeck.-.Clockify.Demo.mp4

FAQ / Troubleshooting

• Why am I getting a yellow triangle when pressing the button?
  • Your API Key is likely incorrect
  • Make sure your local system time is up-to-date, it's not uncommon for systems to be off by a few seconds
  • If you have clients assigned to your project, make sure they're configured in the Stream Deck
• Why am I not seeing the running timer on my button?
  • Make sure you haven't set a title, as this will override any other content
  • Make sure the API Key, Workspace name and optional the project and timer name
  • If the settings were wrong, the plugin waits a bit before trying again, pressing the button tries right away
  • Make sure that for projects with the same name, different clients are set
• Why are my tags missing on the timer?
  • Make sure the tags have been created through the web app, as the plugin doesn't create them
  • Make sure the tag names match and tags with commas (WHY!?!) are escape with a backslash, e.g. tag1,tag\,2,tag3
• Why does the timer always start with a negative number?
  • This can happen when your local computer time isn't in sync with the Clockify server time
  • Make sure you synchronize your clock with a time-server
• Why does it take a while until the button shows a timer I started in the web app?
  • The plugin only checks for changes made outside the Stream Deck as often as the refresh rate allows, which is every 5 minutes on the Free plan by default
  • Pressing the button always checks first, if the last check is older than a minute
• Why do I get a yellow triangle after a while, even though the settings are correct?
  • You likely ran into Clockify's API limit, the Free plan only allows 30 requests per hour for the whole workspace
  • Check the log for "rate limit reached", it tells you until when the requests are paused
  • Set a slower refresh rate and keep in mind, that other integrations in your workspace use the same limit
• Why can't I select my Workspace and Project in a dropdown menu?
  • Because I was lazy 😅
• Where can I find the logs?
  • Windows: %appdata%\Elgato\StreamDeck\Plugins\dev.duerrenberger.clockify.sdPlugin\Windows\pluginlog.log
  • macOS: ~/Library/Application Support/com.elgato.StreamDeck/Plugins/dev.duerrenberger.clockify.sdPlugin/macOS/pluginlog.log
• IT DOESN'T WORK, WHY?!?
  • Feel free to open a GitHub issue or ping me on Bluesky or Twitter

Credits

• Feel free to star this repository and follow me on Bluesky or Twitter
• Thanks to Bar Raiders for the great tooling and community
• Shout-out to Hugh Macdonald for adding the text formatting feature!
• Took some inspiration from the Toggl plugin
• Using a CC0 licensed Timer image for the Time Tracking category
• Talking to Clockify with the ClockifyClient library
• And thanks to Clockify for providing an excellent time tracking tool for free

License

This project is licensed under the MIT License - see the LICENSE file for details