playbooks

home / skills / steveclarke / dotfiles / time-tracking

time-tracking skill

/ai/skills/time-tracking

This skill helps you manage time tracking across Toggl and Clockify, including starting, stopping, and logging entries for accurate productivity records.

npx playbooks add skill steveclarke/dotfiles --skill time-tracking

Review the files below or copy the command above to add this skill to your agents.

Files (2)
SKILL.md
2.0 KB
---
name: time-tracking
description: Manage time tracking with Toggl or Clockify. Use when user asks about time tracking, timers, timesheets, logging hours, starting/stopping work, checking what's running, viewing time entries, or creating manual entries. Triggers on "toggl", "clockify", "time tracking", "timer", "timesheet", "log time", "track time", "hours worked".
---

# Time Tracking

Use `scripts/track` for all time tracking operations. Supports both Toggl (default) and Clockify.

## Commands

```bash
# Real-time tracking (default: Toggl)
scripts/track start "Task description" -p "Project Name"
scripts/track stop
scripts/track current

# Use Clockify instead
scripts/track start "Task description" -p "Project Name" -P clockify
scripts/track current -P clockify

# Manual entries (past dates)
scripts/track create "Description" -p "Project" -s "YYYY-MM-DD HH:MM" -e "YYYY-MM-DD HH:MM"
scripts/track create "Description" -p "Project" -s "..." -e "..." -t "tag1,tag2"  # with tags

# Management
scripts/track delete <entry-id>
scripts/track entries --days 7
scripts/track projects
scripts/track me

# Projects and tags (Toggl only)
scripts/track project:create "Project Name"
scripts/track project:create "Project Name" -b        # billable
scripts/track project:create "Project Name" --private # private project
scripts/track tags
```

## Provider Selection

- `-P toggl` (default) - Use Toggl Track
- `-P clockify` - Use Clockify

## Notes

- Project names must match exactly - use `projects` to list available names
- Authentication via 1Password:
  - Toggl: `op://Employee/Toggl/api key`
  - Clockify: `op://Employee/Clockify/Saved on app.clockify.me/apikey`
- **Token caching**: API tokens are cached in `~/.local/state/steveos/time-tracking/` for 24 hours to avoid repeated 1Password prompts
- Run `scripts/track --help` for full usage

## Cache Management

```bash
scripts/track cache:clear      # Clear token for current provider
scripts/track cache:clear:all  # Clear all cached tokens
```

Use these if you rotate your API key in 1Password or need to re-authenticate.

Overview

This skill manages time tracking via Toggl or Clockify from the command line. It provides commands to start and stop timers, create manual time entries, list projects and recent entries, and manage cached API tokens. Use it to keep consistent tracking workflows across machines.

How this skill works

The skill exposes a single script-driven interface that defaults to Toggl but can switch to Clockify with a provider flag. It authenticates using credentials stored in 1Password and caches API tokens locally for 24 hours to avoid repeated prompts. Commands cover real-time timers, manual entry creation, entry management, and project/tag inspection.

When to use it

  • Start or stop a live timer for a task (scripts/track start/stop).
  • Create manual time entries for past work periods (scripts/track create).
  • View what timer is currently running or recent entries (scripts/track current, entries).
  • Switch between Toggl and Clockify for different accounts or teams.
  • List available projects or tags before logging time to ensure exact names.

Best practices

  • Always run scripts/track projects before creating entries to match project names exactly.
  • Use the provider flag (-P clockify) when your team uses Clockify instead of the default Toggl.
  • Keep your API keys in 1Password and rotate them there; clear cached tokens after rotation.
  • Use scripts/track create with precise start/end timestamps for accurate historical logging.
  • Clear cached tokens with cache:clear if you see authentication errors or change accounts.

Example use cases

  • Start a timer for coding work: scripts/track start "Implement feature X" -p "Project Name"
  • Stop the current timer after finishing a task: scripts/track stop
  • Add a two-hour manual entry from yesterday: scripts/track create "Bug fixes" -p "Project" -s "2026-01-29 10:00" -e "2026-01-29 12:00"
  • List last week’s entries for reporting: scripts/track entries --days 7
  • Switch to Clockify for a contractor project: scripts/track start "Client task" -p "Client Project" -P clockify

FAQ

How does authentication work?

The skill reads API tokens from 1Password (preconfigured item paths) and caches them locally for 24 hours to avoid repeated prompts.

What if a project name doesn't match?

Project names must match exactly. Run scripts/track projects to list available names, then retry the command using the exact string.