clockify-tracker

Clockify 時間追跡（REST API）

https://api.clockify.me/api/v1 への HTTPS リクエストを使って Clockify と連携します。ローカルに clockify_tracker バイナリが存在するとは限りません。

API キー

次の優先順位でキーを取得します。

1. CLOCKIFY_API_KEY 環境変数 — echo $CLOCKIFY_API_KEY で確認します
2. CLOCKIFY_API_KEY_FILE 環境変数 — キーだけが記載されたファイルへのパスです。cat "$CLOCKIFY_API_KEY_FILE" 2>/dev/null | tr -d '[:space:]' で読み取ります
3. シェル設定ファイル — 一般的な rc ファイルで CLOCKIFY_API_KEY のエクスポートまたは代入を grep します。

   grep -h "CLOCKIFY_API_KEY" ~/.zshrc ~/.zprofile ~/.bashrc ~/.bash_profile ~/.profile 2>/dev/null \
     | grep -v '^\s*#' | head -1
   

   export CLOCKIFY_API_KEY=abc123 または CLOCKIFY_API_KEY="abc123" のような行から、次のコマンドで値を抽出します。

   sed 's/.*CLOCKIFY_API_KEY[[:space:]]*=[[:space:]]*//' | tr -d '"'"'"' '
   

   空でない値が見つかった場合は、（実行中の環境に設定されている場合と同じように）何も通知せずに使用します。
4. prefs ファイルの api_key フィールド（下記の CLOCKIFY_PREFS_PATH を参照）— cat <prefs-path> 2>/dev/null で読み取ります
5. いずれも見つからない場合 → ユーザーにキーを貼り付けてもらいます（Clockify → Profile → API）。その後、保存するか確認します。

   "このキーを に保存して、次回から入力しなくて済むようにしますか？（yes/no）" 「yes」の場合は、prefs ファイルに "api_key": "<key>" をマージします。

キーの値を表示したりログに記録したりしないでください。curl -H "X-Api-Key: $KEY" コマンド内でのみ使用します。

環境

変数	用途
CLOCKIFY_API_KEY	実行中の環境に直接設定された API キーの値です。
CLOCKIFY_API_KEY_FILE	API キーを内容とするファイルへのパスです（例：~/.secrets/clockify）。シークレットマネージャーやシンボリックリンクされた保管庫ファイルと併用すると便利です。
CLOCKIFY_PREFS_PATH	prefs JSON ファイルのカスタムパスです。未設定の場合は ~/.clockify-prefs.json がデフォルトです。prefs パスの解決方法：${CLOCKIFY_PREFS_PATH:-~/.clockify-prefs.json}。
CLOCKIFY_TZ_OFFSET	UTC からのローカル時差（整数時間）です（例：アルゼンチンの場合は -3）。prefs ファイルにタイムゾーンがない場合の代替値です。

確認するシェル設定ファイル（上記のステップ 3）：~/.zshrc、~/.zprofile、~/.bashrc、~/.bash_profile、~/.profile。

認証

各リクエストで次を指定します。

• ヘッダー：X-Api-Key: <resolved key>
• ヘッダー：Content-Type: application/json（POST 本文の場合）

エンドポイント（以前の CLI の動作を再現）

ワークスペースの一覧表示

GET /workspaces

ワークスペースの JSON 配列を返します。各項目には id と name が含まれます。

ワークスペース内のプロジェクト一覧

GET /workspaces/{workspaceId}/projects?page-size=5000

プロジェクトの JSON 配列を返します。各項目には id と name が含まれます。

フロー： ユーザーが複数のワークスペースを持っている可能性がある場合は、まず GET /workspaces を呼び出し、ユーザーに選択してもらいます（ワークスペースが1つだけの場合はそれを使用します）。次に、選択された workspaceId のプロジェクトを一覧表示します。

時間エントリの作成

POST /workspaces/{workspaceId}/time-entries

JSON 本文（以前の CLI のフィールドに準拠）：

フィールド	必須	備考
start	はい	ISO 8601 UTC 文字列。例：2025-03-25T12:00:00.000Z
description	はい	作業の説明
billable	いいえ	ブール値。省略時のデフォルトは false
end	いいえ	ISO 8601 UTC。終了時刻を指定しないエントリの場合は省略します
projectId	いいえ	Clockify のプロジェクト ID

ユーザーのローカル時刻 HH:mm を UTC の start／end に変換する

ユーザーが ローカル 時刻を HH:mm 形式で指定した場合（任意で YYYY-MM-DD も指定できます。指定がない場合は、ユーザーのロケールでの意図に基づく 今日 とします）：

1. 日付 D（年、月、日）と時刻の各要素 hour、minute を解析します。
2. tzOffset をそのローカルタイムゾーンの UTC からのオフセット（時間単位）とします。UTC+5 なら +5、UTC-3 なら -3 です。CLOCKIFY_TZ_OFFSET が設定されている場合はそれを使用します（整数の時間）。それ以外の場合はユーザー情報（例：アルゼンチンなら -3）または文脈から推測します。
3. UTC の時刻を作成します。 utc_hour = hour - tzOffset その後、必要に応じて日付を繰り上げ／繰り下げし、日付 D 上の有効な UTC DateTime に正規化して、Z 付き（ISO 8601 UTC）でシリアライズします。

例：

• tzOffset = -3 のとき、2025-03-10 のローカル時刻 09:00 → UTC の時刻は 9 - (-3) = 12 → 2025-03-10T12:00:00.000Z。
• ユーザーが T とタイムゾーン／Z を含む完全な ISO 文字列をすでに指定している場合は、この変換を行わず、そのまま渡します。

複数のカレンダー日

期間（「3月2日〜6日」）や個別の日付リスト（「3月23日、24日、25日、26日、27日」）の場合は、各日の start（および指定があれば end）に適切な日付を設定し、同じローカル時刻を使用して、日ごとに POST を1回 実行します。年が指定されていない場合は、現在の暦年を使用します。

運用フロー

1. 実行環境で CLOCKIFY_API_KEY が利用できることを確認します。
2. ワークスペースが不明な場合：GET /workspaces を実行し、workspaceId を特定します。
3. プロジェクトが必要な場合：GET /workspaces/{workspaceId}/projects?page-size=5000 を実行し、projectId を特定します。
4. 説明、開始時刻（および任意の終了時刻）、必要に応じて日付とタイムゾーンのオフセットを確認します。
5. JSON を作成し、POST /workspaces/{workspaceId}/time-entries を実行します。
6. API の JSON レスポンス、または明確なエラー（ステータスコードと本文）を表示します。

エラー

成功以外のステータスの場合はレスポンス本文を読み取り、問題に応じて修正します（無効な ID、権限、形式不正な本文など）。公式リファレンス：Clockify API documentation。

---

ログベースモード

ユーザーが 「use logs」、「from work logs」、「usa los logs」、「auto-fill from logs」 などと言った場合に起動します。既存の手動モード（説明／プロジェクト／日付／時刻を明示する方法）に変更はありません。

設定ファイル

パス：${CLOCKIFY_PREFS_PATH:-~/.clockify-prefs.json}。必ず実行時に解決します。まず環境変数を確認し、次に ~/.clockify-prefs.json にフォールバックします。cat "${CLOCKIFY_PREFS_PATH:-~/.clockify-prefs.json}" 2>/dev/null で読み込み、統合した JSON でファイルを上書きして書き込みます。

{
  "api_key": "<clockify-api-key>",
  "timezone": { "name": "Buenos Aires, Argentina", "offset": -3 },
  "default_start": "09:00",
  "default_end": "17:00",
  "workspace_id": "<wid>",
  "repo_mappings": {
    "mini-meta-repo":  { "name": "Nubank",        "id": "<pid>" },
    "somnio-ai-tools": { "name": "Internal Tools", "id": "<pid>" }
  }
}

新しいキーは必ず既存の設定に統合してください。ファイル全体を置き換えてはいけません。

手順

1. 設定を読み込む — ~/.clockify-prefs.json を読み込みます。ファイルがない場合、保存済みの状態はないものとし、初回設定に進みます。

2. 初回設定（設定ファイルなし） — ほかのことを尋ねる前に、次のように質問します。

"設定を行いましょう。現在取り組んでいるリポジトリ／プロジェクトと、それぞれに対応する Clockify のプロジェクト名を教えてください。 例：mini-meta-repo → Nubank、somnio-ai-tools → Internal Tools"

名前で指定された Clockify プロジェクトを GET /workspaces/{wid}/projects で ID に解決し、設定に保存します。プロジェクト全体を宣言するのはこのときだけです。後から新しいリポジトリが見つかった場合は、その都度1回だけ質問します。

3. 期間を尋ねる — ユーザーのメッセージに含まれていない場合：

"どの日を確認しますか？（例：今日、今週、5月22日〜26日）"

4. ログファイルを読む — 期間内の各日について：

cat ~/.work-log/YYYY-MM-DD.md 2>/dev/null

ファイルがない場合は、その日をスキップし、ユーザーに伝えます。選択したすべての日から、各 ## HH:MM - … (branch) ヘッダーを解析し、重複のないリポジトリ名を収集します。

5. 時間枠を確認する — デフォルトは09:00〜17:00（8時間）です。保存済みの設定があれば表示します。変更を尋ねるのは、設定がない場合、またはユーザーが別の時間枠を明示した場合のみです。

6. タイムゾーンを選ぶ — 保存済みのタイムゾーンがある場合は、それをデフォルトとして提示します。

"Buenos Aires（UTC-3）を使用します — Enter キーで確定するか、番号を選ぶ／独自の値を入力してください："

保存済みの設定がない場合は、番号、名称、または自由記述の入力を表示して待ちます。

1. Buenos Aires, Argentina  (UTC-3)
2. Montevideo, Uruguay      (UTC-3)
3. São Paulo, Brazil        (UTC-3)
4. Quito, Ecuador           (UTC-5)
5. Lima, Peru               (UTC-5)
6. Colombia                 (UTC-5)
7. Nicaragua                (UTC-6)
8. Other — type your city or UTC offset (e.g. "Madrid" or "UTC+1")

ユーザーがリストにない都市または地域を入力した場合は、知識に基づいて標準 UTC オフセットを推定します（例：「Madrid」→冬は UTC+1／夏は UTC+2 — 今日の日付における現在の標準オフセットを使用します）。保存する前にユーザーに確認します：

「Madrid は UTC+1（標準時）です — これで正しいですか？」

7. リポジトリ名を解析して解決する — ログのヘッダーには 2 つの形式があります：

• ワークツリー：## HH:MM - mini-meta-repo/refactor-flutter_http (branch) — ルートリポジトリは / より前の部分です
• メインチェックアウト：## HH:MM - somnio-ai-tools (main) — 名前全体がルートリポジトリです

/ で分割して、ルートリポジトリ名（Clockify のマッピング用）とワークツリー名（説明の文脈用）を抽出します。その後：

• ルートリポジトリが repo_mappings にある → 確認せずに使用します。
• ルートリポジトリが repo_mappings にない → 1 回だけ尋ねます：

  「mini-meta-repo のエントリーがあります — これはどの Clockify プロジェクトですか？」

エントリーを作成する前に、不明なリポジトリに関する質問をすべてまとめて行います。

8. 設定を保存する — すべての質問に回答を得た後、回答を ~/.clockify-prefs.json にマージします。

9. 複数プロジェクトの日を処理する — 各日について、その日のリポジトリがマッピングされる Clockify プロジェクトの数を数えます：

• 単一プロジェクト → 時間ブロック全体で 1 件のエントリーを作成します。
• 複数のプロジェクト → 作業時間の分割方法をユーザーに尋ねます：

  「5 月 26 日は Nubank（mini-meta-repo）と Internal Tools（somnio-ai-tools）に取り組みました。8 時間をどのように分けますか？（例：Nubank 7 時間／Internal Tools 1 時間）」

その日のプロジェクトごとに、独自の開始時刻と終了時刻を設定したエントリーを 1 件ずつ作成します。

10. エントリーごとにログを要約する — 日付と Clockify プロジェクトの各組み合わせについて、関連するログエントリーを集め、2 文のエグゼクティブサマリーを作成します：

• 1 文目：主な成果 — 機能、決定事項、取り組んだ具体的なワークツリー／ブランチ（名前を挙げます）
• 2 文目：重要な発見、結果、または次のステップ

目標は、長文にならずに、Finance の読者が 8 時間の作業内容を理解できるだけの文脈を示すことです。

11. プレビューして確認する — 投稿する前に、各エントリーを全文表示し、ユーザーが説明を確認できるようにします。エントリーごとに 1 項目を使った番号付きリスト形式にします：

Here's what I'll post to Clockify:

1. May 22 — Nubank — 09:00–17:00
   refactor-flutter_http: Completed Flutter HTTP migration by updating LogoutInterceptor
   to use IRouter and fixing the redirect_interceptor_test setup. Key finding: the
   interceptor correctly dispatches the logout deeplink on 403 responses.

2. May 26 — Nubank — 09:00–16:00
   refactor-flutter_http: Diagnosed the native catalyst HTTP bypass on both iOS and
   Android — authenticated calls go through URLSession/OkHttp, not Dart/Dio, making
   LogoutInterceptor.onError structurally unreachable. Proposed and planned Option A
   (synthetic DioException) as the only viable path to trigger the interceptor.

3. May 26 — Internal Tools — 16:00–17:00
   somnio-ai-tools: Planned and implemented the clockify-tracker log-based mode,
   including hook fix for root-repo logging and the repo-to-project mapping system.

Post these entries? (yes / edit / cancel)

説明全体が切り詰められずに読めるよう、表ではなく番号付きリストを使用します。ユーザーが「edit」と言った場合は、変更するエントリーの番号と新しい説明を尋ねてから、投稿前にプレビュー全体を再表示します。

12. エントリーを作成する — 既存の UTC 変換ロジックを使用して、各行につき 1 件の POST /workspaces/{workspaceId}/time-entries を実行します。各 API のレスポンスを表示します。

13. ログファイルをクリーンアップする — すべてのエントリーが正常に投稿された後、処理済みファイルを削除するかユーザーに確認します。

~/.clockify-prefs.json で "auto_cleanup": true を確認します。設定されている場合は、確認せずに削除し、削除したファイルをユーザーに伝えます。設定されていない場合は、次のように尋ねます：

「エントリーを投稿しました。処理済みのログファイルを削除しますか？

• ~/.work-log/2026-05-26.md
• ~/.work-log/2026-05-27.md （yes / no / always — 「always」は設定を保存し、今後は確認しません）」

• yes — rm でこれらのファイルを削除し、それぞれが削除されたことを確認します
• no — ファイルをそのまま残します
• always — ファイルを削除してから、解決済みの設定ファイル（${CLOCKIFY_PREFS_PATH:-~/.clockify-prefs.json}）に "auto_cleanup": true をマージします

エントリーがすべて正常に投稿されたファイルのみを削除します。一部の投稿に失敗した場合は、失敗したエントリーがある日のファイルを削除せず、どのファイルを残したかをユーザーに伝えます。