agentleFS
kratoczkratocz/skills/skills/tracker-start/SKILL.md

tracker-start

Skill1 starsChanged 50 days agoMITView on GitHub

Start the time tracking timer (Toggl/Clockify) for what you are about to work on. Use when the user says "/tracker-start", "start timer", "start tracking", "spusť stopky", "I'm starting work on <task>", or names the task they are beginning. Not the morning briefing over tasks and PRs — that is work-start.

The file

We split this skill into the rules it gives an agent

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

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈4

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 7

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Start a new time tracking session in the configured backend.

    line 12
  2. Very specific:

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

    line 16
  3. Distinctive:

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

    line 17
  4. Very specific:

    Read config.language (default "en" if missing).

    line 19
  5. Very specific:

    If a timer is already running, show its description and ask the user (in the configured language) whether to stop it first (via …

    line 47
  6. Very specific:

    If arguments were provided, trim them.

    line 50
  7. Very specific:

    Use WebFetch with a prompt like "Return only the primary title of this page (e.g., pull/merge request title, issue title, or <title> tag).

    line 51
  8. Very specific:

    If WebFetch fails or returns nothing usable, fall back to the URL as the full description.

    line 53
  9. Distinctive:

    If the argument is plain text, use it as-is (the user already chose the wording).

    line 54
  10. Distinctive:

    If no arguments were provided, ask the user — in the configured language — for a brief description of what they're working on.

    line 55
  11. Very specific:

    If matched, use its ID. Otherwise fall back to default_project_id from config (may be null — in which case no project is attached).

    line 60

≈ “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

Start Session

Start a new time tracking session in the configured backend.

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.
    • ⚠️ The file contains the API key in plaintext, so never cat it. Read only the fields you need, and read them inside the script that uses them (json.load(open(...))["toggl"]["api_key"]) rather than into a shell variable or the conversation. A cat of this file puts the key in the transcript, in any log that captures tool output, and past any secret-redaction that only watches command arguments — it is the same leak the --config - trick below exists to prevent, arriving by the other door. If you need to know whether a field is set, test it and print the boolean.
    • Read config.language (default "en" if missing). All user-facing text generated in the steps below — prompts, confirmations, URL-derived descriptions — should be phrased in this language. Keep proper nouns, code identifiers, URLs, and numeric durations unchanged.
  2. Gather project context (best-effort — ignore errors if not in a git repo):
    git remote get-url origin 2>/dev/null
    git branch --show-current 2>/dev/null
    pwd
    Derive a project name: take the last path segment of the git remote URL and strip a trailing .git (e.g., git@github.com:user/my-repo.git → my-repo). If not a git repo, fall back to the current directory name.
  3. Check for an already-running timer:

    Toggl Track

    KEY=<config.toggl.api_key read into a shell variable, not echoed>
    printf 'user = "%s:api_token"\n' "$KEY" | curl -s --config - \
      https://api.track.toggl.com/api/v9/me/time_entries/current

    (The path must include /me/ — the legacy api/v9/time_entries/current returns HTTP 405 with an empty body, which is easy to misread as "no timer running". The stdin --config trick keeps the key out of argv and sidesteps sandboxes that rewrite colon-bearing arguments — some harness Bash sandboxes turn -u user:token into a file path, so never pass the credential as a plain -u argument.)

    Worktree-isolated sessions: a worktree isolation guard may refuse these compound commands as "too complex to verify" — the VAR=$(…) assignment + pipeline shape is a known trigger. The fallback that reliably passes: Write a small script (shell or Python via stdlib urllib) into the session's scratchpad directory, reading the API key from the config file inside the script, and run it as one plain command (python3 <scratchpad>/toggl_start.py). The key stays out of argv either way. The same fallback applies to every curl call in the steps below (timer check, project list, start) — and to /tracker-stop.

    Clockify

    curl -s -H "X-Api-Key: <config.clockify.api_key>" \
      "https://api.clockify.me/api/v1/workspaces/<workspace_id>/time-entries?in-progress=true&page-size=1"

    If a timer is already running, show its description and ask the user (in the configured language) whether to stop it first (via /tracker-stop) or keep it running. Do not auto-stop.

  4. Determine description:
    • If arguments were provided, trim them. If the trimmed argument starts with http:// or https://, treat as a URL:
      • Use WebFetch with a prompt like "Return only the primary title of this page (e.g., pull/merge request title, issue title, or <title> tag). No commentary."
      • Compose the description as <title> — <URL>. If the configured language differs from the title's apparent language, translate/rephrase the title naturally (keep proper nouns, code identifiers, branch names, IDs intact).
      • If WebFetch fails or returns nothing usable, fall back to the URL as the full description.
    • If the argument is plain text, use it as-is (the user already chose the wording).
    • If no arguments were provided, ask the user — in the configured language — for a brief description of what they're working on.
  5. Resolve tracker project (optional):

    • First check config.project_map — an optional object mapping a repo name to a tracker project ID ({"payroll-system-PMA": 219087737}). If the detected repo is a key there, use that ID and skip the name matching entirely.
    • Otherwise fetch the active project list and look for a project whose name matches the detected repo/dir name (case-insensitive).
    • If matched, use its ID. Otherwise fall back to default_project_id from config (may be null — in which case no project is attached).
    • Name matching fails silently whenever the tracker project is not named after the repo, which is the normal case once projects are grouped by client: repo payroll-system-PMA against project NTIT/PMA matches on neither exact nor substring comparison, so the entry is created with no project at all and has to be repaired with a follow-up PUT. When that happens, say which project you attached (or that you attached none) in the step-8 report so it is visible immediately, and offer to add a project_map entry so the next start gets it right.

    Toggl Track

    KEY=<config.toggl.api_key read into a shell variable, not echoed>
    printf 'user = "%s:api_token"\n' "$KEY" | curl -s --config - \
      "https://api.track.toggl.com/api/v9/workspaces/<workspace_id>/projects?active=true"

    Clockify

    curl -s -H "X-Api-Key: <config.clockify.api_key>" \
      "https://api.clockify.me/api/v1/workspaces/<workspace_id>/projects"
  6. Get current UTC time:
    date -u +%Y-%m-%dT%H:%M:%SZ
  7. Start timer based on config.backend. Include the project ID field only if resolved in step 5; otherwise omit it entirely. Read config.billable (top-level field) and pass it in the payload — if the field is missing from the config, default to true.

    Toggl Track

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

    Clockify

    curl -s -H "X-Api-Key: <config.clockify.api_key>" \
      -H "Content-Type: application/json" \
      -X POST "https://api.clockify.me/api/v1/workspaces/<workspace_id>/time-entries" \
      -d '{"description":"<description>","start":"<UTC time>","billable":<billable>}'
  8. Report result (keep it concise, phrased in the configured language):
    • Success: an equivalent of Session started: '<description>' — append project name if resolved.
    • On HTTP error: show the API error message (verbatim, not translated) and suggest re-running /tracker-setup-tracker.

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.