toggl

Toggl Time Tracker

Track time and pull reports via the Toggl Track API.

Environment note: This skill works in both Claude Code and Cowork. The only difference is how the config file is read in Step 1 — Claude Code reads it directly, Cowork uses osascript.

---

Step 1: Read the config

The config lives on the Mac at ~/.toggl-config.json.

In Claude Code (direct file system access):

CONFIG=$(cat ~/.toggl-config.json 2>/dev/null || echo "NOT_CONFIGURED")

In Cowork (VM — needs osascript to reach the Mac home):

CONFIG=$(osascript -e 'do shell script "cat ~/.toggl-config.json 2>/dev/null || echo NOT_CONFIGURED"')

Then parse it safely in Python — never log or print the raw config or API token:

python3 -c "
import json, sys, base64
raw = '''$CONFIG'''
if raw.strip() == 'NOT_CONFIGURED':
    print('STATUS:NOT_CONFIGURED')
    sys.exit(0)
try:
    cfg = json.loads(raw)
    token = cfg['apiToken']
    # Build Basic Auth header: token:api_token base64-encoded
    auth = base64.b64encode(f'{token}:api_token'.encode()).decode()
    print('STATUS:OK')
    print(f'AUTH:Basic {auth}')
    print(f'WORKSPACE:{cfg.get(\"workspaceId\", \"\")}')
except Exception as e:
    print(f'STATUS:PARSE_ERROR:{e}')
"

• If STATUS:NOT_CONFIGURED → tell the user:

  "Toggl isn't set up yet. Create ~/.toggl-config.json with your API token:

  {
    "apiToken": "your-toggl-api-token",
    "workspaceId": 1234567
  }
  

  Find your API token at https://track.toggl.com/profile (scroll to 'API Token'). Find your workspace ID in the URL when logged into Toggl: https://track.toggl.com/{workspaceId}/timer." Stop here.

• If STATUS:PARSE_ERROR → tell the user the config file is malformed.
• If STATUS:OK → extract AUTH and WORKSPACE from output. Continue.

IMPORTANT: The API token belongs to the user. Never print it, log it, or include it in any output shown to the user.

---

API Base

All requests go to:

https://api.track.toggl.com/api/v9

All requests need:

-H "Authorization: $AUTH" -H "Content-Type: application/json"

Where $AUTH is the Basic ... value from Step 1.

---

Start a timer

RESPONSE=$(curl -s -X POST \
  -H "Authorization: $AUTH" \
  -H "Content-Type: application/json" \
  -d "{
    \"created_with\": \"claude-toggl-plugin\",
    \"description\": \"<what the user is working on>\",
    \"workspace_id\": $WORKSPACE,
    \"start\": \"$(date -u +%Y-%m-%dT%H:%M:%SZ)\",
    \"duration\": -1,
    \"project_id\": <project_id or null>,
    \"tags\": [<optional tags>]
  }" \
  "https://api.track.toggl.com/api/v9/workspaces/$WORKSPACE/time_entries")
echo "$RESPONSE"

• duration: -1 means the timer is running
• Parse the response for id (you'll need it to stop the timer)
• Tell the user: "Timer started: "

---

Stop the running timer

First, get the current running entry:

CURRENT=$(curl -s \
  -H "Authorization: $AUTH" \
  -H "Content-Type: application/json" \
  "https://api.track.toggl.com/api/v9/me/time_entries/current")
echo "$CURRENT"

If null → no timer running, tell the user.

If a timer is running, extract its id and workspace_id, then stop it:

ENTRY_ID=<id from current>
RESPONSE=$(curl -s -X PATCH \
  -H "Authorization: $AUTH" \
  -H "Content-Type: application/json" \
  -d "{\"stop\": \"$(date -u +%Y-%m-%dT%H:%M:%SZ)\"}" \
  "https://api.track.toggl.com/api/v9/workspaces/$WORKSPACE/time_entries/$ENTRY_ID/stop")
echo "$RESPONSE"

Parse the response and tell the user:

• What was stopped (description)
• How long it ran (calculate from start/stop)

---

Check what's currently running

curl -s \
  -H "Authorization: $AUTH" \
  -H "Content-Type: application/json" \
  "https://api.track.toggl.com/api/v9/me/time_entries/current"

If null → "No timer running." Otherwise → show description, project, and how long it's been running.

---

Log a completed time entry

For time already spent (not a running timer):

curl -s -X POST \
  -H "Authorization: $AUTH" \
  -H "Content-Type: application/json" \
  -d "{
    \"created_with\": \"claude-toggl-plugin\",
    \"description\": \"<description>\",
    \"workspace_id\": $WORKSPACE,
    \"start\": \"<ISO 8601 start time>\",
    \"stop\": \"<ISO 8601 stop time>\",
    \"duration\": <seconds>,
    \"project_id\": <project_id or null>,
    \"tags\": [<optional tags>]
  }" \
  "https://api.track.toggl.com/api/v9/workspaces/$WORKSPACE/time_entries"

• Duration must match the difference between start and stop (in seconds)
• Ask the user for the details if not provided

---

List recent time entries

# Today's entries
TODAY=$(date -u +%Y-%m-%d)
curl -s \
  -H "Authorization: $AUTH" \
  -H "Content-Type: application/json" \
  "https://api.track.toggl.com/api/v9/me/time_entries?start_date=$TODAY&end_date=$TODAY"

For a date range:

curl -s \
  -H "Authorization: $AUTH" \
  -H "Content-Type: application/json" \
  "https://api.track.toggl.com/api/v9/me/time_entries?start_date=<YYYY-MM-DD>&end_date=<YYYY-MM-DD>"

Format the results as a clean summary:

• Group by project
• Show description, duration (human-readable), and tags
• Show total hours

---

List projects

curl -s \
  -H "Authorization: $AUTH" \
  -H "Content-Type: application/json" \
  "https://api.track.toggl.com/api/v9/workspaces/$WORKSPACE/projects?active=true"

Use this to help the user pick a project when starting a timer.

---

List workspaces

curl -s \
  -H "Authorization: $AUTH" \
  -H "Content-Type: application/json" \
  "https://api.track.toggl.com/api/v9/me/workspaces"

Use this if the user hasn't set a workspace ID in their config, or needs to switch workspaces.

---

Weekly summary report

Pull all entries for the current week and summarize:

python3 -c "
from datetime import datetime, timedelta
today = datetime.utcnow()
monday = today - timedelta(days=today.weekday())
sunday = monday + timedelta(days=6)
print(f'START:{monday.strftime(\"%Y-%m-%d\")}')
print(f'END:{sunday.strftime(\"%Y-%m-%d\")}')
"

Then fetch entries for that range and summarize by:

• Total hours this week
• Hours per project
• Hours per day
• Top tags

---

Error handling

• 401/403: Auth failed — tell the user to check their API token
• 429: Rate limited — wait and retry (free tier: 30 req/hour)
• 404: Resource not found — check workspace ID or entry ID
• Network errors: Report the curl exit code

---

Notes

• All times are in UTC — convert to the user's local time for display
• API token is at https://track.toggl.com/profile
• Workspace ID is in the Toggl URL: https://track.toggl.com/{workspaceId}/timer
• Rate limits: Free=30/hr, Starter=240/hr, Premium=600/hr
• Config at ~/.toggl-config.json
• The user's API token is NEVER printed or logged