Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
146 changes: 146 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -38,6 +38,152 @@ Configuration is done via the UI:

Webhooks let Clockify push timer changes to Home Assistant instantly instead of the integration having to poll the Clockify API on a schedule, which keeps API usage low and avoids hitting Clockify's rate limits, even on a free-tier.

## Entities

Each configured project gets a device named `Clockify - <project>` with these entities (shown for a project called "My Project"):

| Entity | Description |
| --- | --- |
| `switch.clockify_my_project_timer` | Start/stop the Clockify timer for the project |
| `sensor.clockify_my_project_timer_status` | `Running` or `Idle` |
| `sensor.clockify_my_project_hours_today` | Hours logged today, in decimal hours (e.g. `3.25`) |
| `sensor.clockify_my_project_hours_this_week` | Hours logged this week |
| `sensor.clockify_my_project_hours_this_month` | Hours logged this month |
| `sensor.clockify_my_project_hours_this_year` | Hours logged this year |

The hours sensors refresh every 5 minutes, and immediately when a timer starts or stops.

## Examples

Replace `my_project`, `your_phone`, `person.you` and `zone.work` with your own entities.

### Live timer notification on your phone

Shows a notification with a running stopwatch while the timer is on, starting from the hours already logged today, plus a second notification with a **Stop timer** button. The stopwatch ticks on the device, so Home Assistant sends no repeated updates. Requires the Home Assistant Companion app on a version that supports live update notifications.

```yaml
alias: "Clockify: Live timer notification"
triggers:
- trigger: state
entity_id: switch.clockify_my_project_timer
to: "on"
# Give the hours sensor a moment to refresh after the timer starts
for:
seconds: 10
id: start
- trigger: state
entity_id: switch.clockify_my_project_timer
to: "off"
id: stop
- trigger: event
event_type: mobile_app_notification_action
event_data:
action: clockify-stop-timer
id: action-stop
actions:
- choose:
- conditions:
- condition: trigger
id: start
sequence:
- variables:
elapsed_seconds: >-
{{ (states('sensor.clockify_my_project_hours_today') | float(0) * 3600) | int }}
- action: notify.mobile_app_your_phone
data:
title: Clockify — My Project
message: "Today: {{ states('sensor.clockify_my_project_hours_today') }} h"
data:
tag: clockify_timer_activity
live_update: true
chronometer: true
when: "{{ -1 * elapsed_seconds }}"
when_relative: true
notification_icon: mdi:timer-play-outline
notification_icon_color: "#03A9F4"
color: "#03A9F4"
# Live notifications can't show action buttons, so the stop button gets its own notification
- action: notify.mobile_app_your_phone
data:
title: Clockify
message: The timer is running.
data:
tag: clockify_timer_active
actions:
- action: clockify-stop-timer
title: Stop timer
- conditions:
- condition: trigger
id: stop
sequence:
- action: notify.mobile_app_your_phone
data:
message: clear_notification
data:
tag: clockify_timer_activity
- action: notify.mobile_app_your_phone
data:
message: clear_notification
data:
tag: clockify_timer_active
- conditions:
- condition: trigger
id: action-stop
sequence:
- action: switch.turn_off
target:
entity_id: switch.clockify_my_project_timer
mode: queued
max: 10
```

### Start and stop the timer when you arrive at and leave work

Starts the timer two minutes after you enter the work zone (so driving past doesn't count) and stops it when you leave, then sends you the hours logged today.

```yaml
alias: "Clockify: Track time at work"
triggers:
- trigger: zone
entity_id: person.you
zone: zone.work
event: enter
id: enter
- trigger: zone
entity_id: person.you
zone: zone.work
event: leave
id: leave
actions:
- choose:
- conditions:
- condition: trigger
id: enter
sequence:
- delay:
minutes: 2
# Skip if you already left again during the delay
- condition: zone
entity_id: person.you
zone: zone.work
- action: switch.turn_on
target:
entity_id: switch.clockify_my_project_timer
- conditions:
- condition: trigger
id: leave
sequence:
- action: switch.turn_off
target:
entity_id: switch.clockify_my_project_timer
- action: notify.mobile_app_your_phone
data:
title: Clockify stopped
message: >-
You worked {{ states('sensor.clockify_my_project_hours_today') }} hours today.
mode: restart
```

## License

See [LICENSE](LICENSE).
Loading