Work Guardian / 上班守護者

Stop yourself from burning through your Claude Pro/Max quota while goofing off at home. Work Guardian watches your rolling usage limit, warns when it runs low, and hard-stops new work before a cutoff time so you always keep a reserve for when it actually matters.

別在家玩過頭把 Claude 額度燒光。上班守護者盯著你的用量上限,額度低了先提醒,在你設定的截止時間前保留一段額度硬擋新工作,關鍵時刻才不會沒額度可用。

---

How it works / 運作方式

Claude Code feeds usage data (rate_limits) to the status line — but not to hooks. So this plugin has two pieces:

1. A status line (statusline/dump.py) that saves the raw payload to ~/.claude/_statusline_last.json and prints a compact line (model · 7d 23% · ctx 56%).
2. A UserPromptSubmit hook (hooks/quota-guard.py) that reads that file and, each time you submit a prompt:
   • remaining < warn_at → soft warning (still runs)
   • remaining < floor and now is before the cutoff time → hard block (with an override escape hatch)
   • can't read the data (free tier, or before the first API response) → does nothing, never locks you out

Claude Code 把用量資料(rate_limits)只餵給狀態列、不餵給 hook,所以本 plugin 有兩塊:一支狀態列負責把原始資料存到檔案,一支 hook 讀那個檔做判斷。

---

Install / 安裝

# add this repo as a plugin marketplace, then install
/plugin marketplace add loreias32/work-guardian
/plugin install work-guardian

Then set the status line so the hook has data to read. In ~/.claude/settings.json:

{
  "statusLine": {
    "type": "command",
    "command": "python \"~/.claude/plugins/work-guardian/statusline/dump.py\""
  }
}

Already have your own status line? Just make it also write ~/.claude/_statusline_last.json (copy the dump lines from statusline/dump.py).

已經有自己的狀態列?把 statusline/dump.py 裡的 dump 那幾行併進去即可,不必換掉你原本的。

Note: rate_limits only appears for Claude Pro/Max subscribers, and only after the first API response in a session. 免費層或 session 第一次回應前沒有這筆資料,守門會自動放行。

---

Configure / 設定

Run the setup wizard:

/work-guardian

Or edit ~/.claude/work-guardian.json directly:

{
  "warn_at": 20,
  "floor": 13,
  "deadline_weekday": 4,
  "deadline_hour": 10,
  "window": "seven_day",
  "lang": "zh",
  "dump_path": "~/.claude/_statusline_last.json"
}

Key	Meaning	Default
warn_at	Warn when remaining quota drops below this % / 剩餘低於此 % 就提醒	20
floor	Before the cutoff, quota must not drop below this % / 截止時間前的保留線	13
deadline_weekday	Cutoff weekday: 1=Mon..7=Sun, 0=no cutoff / 截止星期幾,0=不設	4
deadline_hour	Cutoff hour (24h) / 截止時刻	10
window	seven_day or five_hour / 看哪個額度	seven_day
lang	zh or en / 訊息語言	zh

---

Override / 手動放行

Hit a hard block but really need to keep going?

touch ~/.claude/work-guardian-off   # disables the guard entirely
rm ~/.claude/work-guardian-off      # re-enable when done

被硬擋但真的有急事:碰一下上面那個檔就整個關掉守門,用完刪掉恢復。

---

License

MIT