agentleFS
kratoczkratocz/skills/skills/tracker-log-entry/SKILL.md

tracker-log-entry

Skill1 starsChanged 50 days agoMITView on GitHub

Log a retroactive (already finished) time entry to the configured tracker. Use when the user says "/tracker-log-entry", "log this to Toggl/Clockify", "add a time entry for ...", "track 2 hours retroactively", "zaloguj to do Toggl", or names a past time window they want recorded. For time worked in the current agent session, that is tracker-backfill.

The file

We split this skill into the rules it gives an agent

7 rules. About 0 are common, 3 are distinctive, and 4 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈3

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 4

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Create a completed time entry (start + end in the past) in the configured backend — unlike /tracker-start, no live timer is involved.

    line 12
  2. Very specific:

    Read config: Read ~/.claude/plugins/session-tracker/config.json.

    line 17
  3. Distinctive:

    If the file doesn't exist: "No configuration found.

    line 18
  4. Very specific:

    Read config.language (default "en").

    line 20
  5. Distinctive:

    If no window can be parsed, ask the user for it (one question, in the configured language).

    line 39
  6. Very specific:

    Keep %S in the input format.

    line 68
  7. Distinctive:

    Create the entry: Keep the API key out of argv (it would land in the process table and transcripts): pass it via a config file / header …

    line 113

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Log Retroactive Entry

Create a completed time entry (start + end in the past) in the configured backend — unlike /tracker-start, no live timer is involved.

Steps

  1. Read config: Read ~/.claude/plugins/session-tracker/config.json.
    • If the file doesn't exist: "No configuration found. Please run /tracker-setup-tracker first." Then stop.
    • Read config.language (default "en"). Phrase all user-facing text in this language; keep proper nouns, IDs, URLs and durations unchanged.
  2. Determine the time window. Parse it from the arguments if given (formats to accept: 9:00-11:30, 0:00 to now, 2h, 45m, yesterday 14:00-16:00, an explicit date 2026-07-01 22:00-23:15, since last entry / od konce posledního záznamu). Interpretation rules:

    • A bare duration (2h) means "ending now".
    • Times without a date mean today (or the stated relative day) in the user's local timezone.
    • "Since last entry" (any phrasing that anchors the start to the end of the most recent record — "navázat na poslední záznam", "start where the last entry stopped") means: fetch the backend's most recent completed entry (Toggl: GET /api/v9/me/time_entries?meta=true first item with a stop; Clockify: first page of the user's time entries), use its stop as the start, and "now" as the end. Echo which entry was used as the anchor (its description + stop time) in the final report; if a timer is currently running, say so and ask instead of guessing.
    • If no window can be parsed, ask the user for it (one question, in the configured language). Never guess a duration.

    Convert the window to what the API needs using date (never do timezone arithmetic in your head):

    date -u +%Y-%m-%dT%H:%M:%SZ                      # now, UTC
    
    # local wall-clock -> UTC, macOS: go through an epoch. The input must carry
    # seconds — a window given as 14:00-16:00 is written out as "...14:00:00".
    EPOCH=$(date -j -f "%Y-%m-%d %H:%M:%S" "2026-07-31 18:00:00" +%s)
    date -u -r "$EPOCH" +%Y-%m-%dT%H:%M:%SZ
    
    # local wall-clock -> UTC, GNU/Linux
    date -u -d "<local datetime>" +%Y-%m-%dT%H:%M:%SZ

    On macOS the epoch round-trip is the only form that parses in local time and prints in UTC; every shorter-looking variant is wrong:

    • -u after the positional argument is not parsed as a flag at all, so +<outfmt> is ignored and you get a localized default string back (pá 31. července 2026 18:00:11 CEST) instead of an ISO timestamp, which the API rejects as Invalid time format. The only variant that fails loudly.
    • -u before -f switches the whole run to UTC, so the input is parsed as UTC too and the window silently shifts by the offset (18:00 CEST comes back as 18:00:00Z instead of 16:00:00Z).
    • no -u with a Z in the output format prints local time wearing a UTC suffix — silently off by the offset again.

    Keep %S in the input format. Dropping it to %H:%M makes date fill the seconds in from the current time (18:00 parses as 18:00:11) and start/stop drift apart; keeping it rejects a seconds-less input outright (Failed conversion ... illegal time format) — which is why the :00 is written out.

    Compute duration in seconds as end - start. Echo the resolved window back to the user in local time in the final report so an off-by-timezone mistake is visible.

  3. Determine description: remaining argument text, or ask (in the configured language). Optionally derive context from the current git repo as /tracker-start does.
  4. Resolve tracker project (same as /tracker-start): fetch active projects, match the repo/dir name case-insensitively, fall back to default_project_id (may be null → omit the field).
  5. Read config.billable (default true if missing). If the user named tags in the arguments, include them (Toggl: "tags": [...]; Clockify uses tag IDs — resolve via GET /workspaces/<id>/tags and match by name, skip silently if no match).
  6. Check for overlap before writing. A retroactive window is the one most likely to be covered already — by a parallel session's timer, by an entry the user added by hand, or by a later reconciliation. Fetch the entries of every day the window touches, across all projects (Toggl: GET /api/v9/me/time_entries?start_date=<day>&end_date=<day+1>), and print any whose [start, stop) intersects the window (a running entry covers from its start onward). On an intersection, do not write: report it and propose the free remainder instead. Then check the time nobody has logged yet: other agent sessions active inside the window (events in <harness-home>/projects/*/*.jsonl timestamped within it) whose project bills the same client will be turned into entries later, so cut the window there or name their work in this entry's description — the user decides which. Real case (2026-10-23): a 31-minute window passed the tracker check clean, but a same-client session had been active for 28 of those minutes with nothing logged.

    When the window is the current session's own past work, use tracker-backfill instead. It splits the transcript into activity blocks from all event timestamps and runs both checks above. Reading only the user's own prompts misses activity: answers to in-session dialogs and results from background agents arrive as tool results, so one such block looked 12 minutes shorter than it was.

  7. Create the entry. Keep the API key out of argv (it would land in the process table and transcripts): pass it via a config file / header read from stdin, with the key expanded from a shell variable — never as a literal in the command.

    Toggl Track

    KEY=<config.toggl.api_key read into a shell variable, not echoed>
    printf 'user = "%s:api_token"\n' "$KEY" | curl -sS --config - \
      -H "Content-Type: application/json" \
      -X POST "https://api.track.toggl.com/api/v9/workspaces/<workspace_id>/time_entries" \
      --data-binary '{"created_with":"session-tracker",
        "workspace_id":<workspace_id>,"description":"<description>",
        "start":"<UTC start>","stop":"<UTC end>","duration":<seconds>,
        "billable":<billable>}'

    (Add "project_id":<id> / "tags":[...] only when resolved.)

    Clockify

    KEY=<config.clockify.api_key read into a shell variable, not echoed>
    curl -sS -H @- -H "Content-Type: application/json" \
      -X POST "https://api.clockify.me/api/v1/workspaces/<workspace_id>/time-entries" \
      --data-binary '{"description":"<description>","start":"<UTC start>",
        "end":"<UTC end>","billable":<billable>}' <<< "X-Api-Key: $KEY"

    (Add "projectId" / "tagIds" only when resolved.)

    Worktree-isolated sessions: the Bash guard there rejects compound commands (variable assignment + pipeline, loops) — including the KEY=…; printf … | curl patterns above — as "too complex to verify". Remedy: write the whole call, key lookup included, as a small script into the session scratchpad and run it with a single plain bash <script> — the key still stays out of argv. Create the script with the ordinary file-Write tool (its full content then shows in the conversation before anything runs) and keep it to that one API call, so the user can review exactly what will execute. The script must contain the key lookup (KEY=$(jq -r … config.json)), never the key literal.

  8. Verify and report (concise, in the configured language): parse the response; on success show the entry id, the window in local time, the rounded duration in hours, billable flag, and project/tags if attached. On HTTP error show the API message verbatim and suggest checking /tracker-setup-tracker. If the response indicates a billable/project constraint (e.g. Toggl "workspace does not allow non-billable entries in billable projects"), retry once with billable: true and say so.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.