⏳ This skill is pending AI review.

Scores will appear once the review pipeline completes.

version unknown

usage-guard

shirley-xue-2025@shirley-xue-2025⭐ 15 stars· last commit 3mo ago· 0 open issues

Arm proactive 5-hour usage protection for long Claude Code sessions (batch, subagents, high window % at start). Daemon reads account-level 5-hour window usage (not per-session). User types /usage-guard at session start. Re-arm every sitting. If user mentions usage-guard by name, read this file and run arm.sh.

Choose how to use this skill

You do not need every option. Choose the path your AI client supports. The stable page stays the same; versioned files are immutable.

1. Native installer

This listing has no registered native installer command. Use the complete package or source fallback below, depending on what your client supports.

Do not guess an installer command or replace an existing version without reviewing the diff.

2. Complete package recommended

Download the ZIP when available. It includes SKILL.md plus the references, security notes and version metadata.

No complete ProSkills package is published for this listing yet.

3. Prompt-only

Copy the prompt above when the agent can read the stable page or when you want to adopt the workflow without installing a skill.

Need only the instruction file?

Download SKILL.md only if your client requires a single file. The complete ZIP is safer for a full installation because it preserves the references and release context.

No path installs or executes anything by itself. Your agent still needs access to the project files. Before updating, compare the installed version and review the diff.

—/10

// RATINGS

⭐GitHub Stars
⭐⭐ 15 on GitHubGitHub ↗

Growing

🟢ProSkills Score
—
📍

Not yet listed on ClawHub or SkillsMP

// README

usage-guard

test

Opt-in proactive usage guard for long Claude Code sessions (macOS — Desktop Code tab and CLI). Monitors the account 5-hour window (default pause at 90%) and, optionally, the weekly limit (default pause at 98%) — either can trigger a checkpoint before you hit the wall.

Arm with /usage-guard before long batch, subagent, or overnight work — especially when the shared window is already partly used. An external daemon reads your usage (zero session tokens), sets PAUSE before limits, sends macOS notifications, and you resume with /usage-guard resume after reset — without chat reminders that get queued behind subagents.

Latest: v0.2.2 — fail-closed when blind (UNKNOWN), valid_until freshness, LaunchAgent KeepAlive, blind-alert backoff. See CHANGELOG / release notes.

Who is this for?

  • Long Claude Code sessions that burn the 5-hour window quickly (batch jobs, subagents, /loop, multi-session arcs)
  • Work that starts when usage is already high — arm gives account-level visibility, not just this chat's view
  • Weekly limit nearly full while the current session still looks safe (e.g. 60% session, 97% weekly) — enable weekly monitoring in config
  • Subagent / batch work where mid-session chat messages stay queued
  • You want to pause near 90% (5h) or 98% (weekly) and avoid extra usage wallet charges at 100%
  • macOS — Claude Desktop Code tab or Claude Code CLI
  • You can arm once per session (/usage-guard) — no per-project setup

Also used on heavy model runs (e.g. Fable when available). Same 5-hour wall either way.

Proactive vs reactive: claude-auto-retry resumes after you hit the wall. usage-guard tries to pause before it.

Why this exists

On long runs, chat messages queue while subagents work — so "stop at 90%" reminders never land in time. Hitting 100% can burn extra usage wallet. Stop buttons may not fully halt subagents. Each chat only sees its own usage; the daemon reads account-level usage (same OAuth API as Desktop Settings): the shared 5-hour window and optional weekly bar. A session that "looks" fine at 58% can already be at 94% on the 5h window — or at 97% weekly while the session meter still shows 60%. This tool uses an external control file + upfront session contract instead of mid-run chat.

How it works

/usage-guard  →  arm daemon  →  ~/.usage-guard/control.json
                                      ↑
Session (cooperative)  ←── read state at safe checkpoints only
  - before each subagent batch
  - after each unit completes
  - on /loop guard ticks
LayerRoleTokens
DaemonOAuth usage poll (5h + weekly + extra wallet), adaptive schedule, notifications0
SkillArm, checkpoint rules, /loop timetableMinimal reads

Pause rule: PAUSE when either limit hits its threshold (defaults: 5h ≥ 90%, weekly ≥ 98% if enabled). Resume when both are clear. See pause_reason in control.json (five_hour, weekly, or both).

Consumer contract: obey state (RUN / PAUSE / COOLDOWN / UNKNOWN). If now > valid_until (or stale: true / prefer effective_state), treat as UNKNOWN even when state still says RUN — the daemon may have died while numbers looked healthy. state never stays RUN while telemetry_lost is true.

./install.sh also installs a macOS LaunchAgent (io.usage-guard.daemon) with KeepAlive so a crashed daemon restarts; disarm exits cleanly and stays down.

Install (macOS)

git clone https://github.com/shirley-xue-2025/usage-guard.git
cd usage-guard
chmod +x install.sh
./install.sh
export PATH="$HOME/.local/bin:$PATH"   # add to ~/.zshrc if needed
usage-guard doctor

Updating

Active development — we ship fixes frequently from real session dogfood.

cd usage-guard          # your clone
git pull
./install.sh            # refreshes skill + CLI (git pull alone is not enough)
usage-guard doctor      # checks credentials + shows update notice if available

doctor compares your installed version to the latest GitHub release (cached 24h). Set USAGE_GUARD_NO_UPDATE_CHECK=1 to skip.

One-time: enable usage reads (Desktop-only users)

OAuth tokens may not exist until Claude Code CLI login:

npm i -g @anthropic-ai/claude-code
claude login
usage-guard doctor   # expect ✓ Usage API

See docs/TROUBLESHOOTING.md. Release notes: docs/releases/.

Use

Desktop Code tab

  1. Open your project in the Code tab
  2. Run: /usage-guard your long task description (type manually if it does not appear in the slash picker)
  3. Approve the arm script when prompted — arm waits for the first usage poll before returning
  4. Let it run — watch Terminal: usage-guard status

After reset (new session OK)

/usage-guard resume

CLI

Same /usage-guard skill after install (shared ~/.claude/skills/).

Commands

usage-guard doctor          # credentials + usage API (5h, weekly, extra wallet)
usage-guard arm             # start daemon + session
usage-guard status          # state, %, weekly, checkpoint, pause_reason
usage-guard disarm          # stop daemon
usage-guard poll            # one-shot usage fetch

Mock mode (no OAuth)

cd usage-guard
PYTHONPATH=. python3 -m usage_guard arm --mock-percent 91 --force
PYTHONPATH=. python3 -m usage_guard status
PYTHONPATH=. python3 -m usage_guard disarm

Configuration

Optional ~/.usage-guard/config.json:

{
  "threshold_pause": 90,
  "threshold_warn": 85,
  "weekly_enabled": false,
  "weekly_threshold_pause": 98,
  "weekly_threshold_warn": 95,
  "weekly_pause_within_hours": 5,
  "cooldown_margin_seconds": 60
}

Weekly limit (opt-in): set "weekly_enabled": true to PAUSE when the account weekly utilization (Desktop → Settings → Usage → "All models") reaches weekly_threshold_pause (default 98%), even if the 5-hour window is still low. Either limit can trigger PAUSE; both must clear before RUN resumes. Set weekly_pause_within_hours (e.g. 5) so weekly only pauses when the weekly reset is that soon — if weekly is 99% but reset is days away, you stay RUN (5h guard still applies). Omit or set null to pause at threshold regardless of reset time. The OAuth API exposes one weekly number (seven_day) — not per-model Sonnet/Opus bars separately.

Example — dogfood session (screenshot)

This image is from a real Claude Code session, not part of this README.

Config in use: weekly_enabled: true, weekly_threshold_pause: 98, weekly_pause_within_hours: 5.

What happened: the 5-hour window had just reset (4%). Weekly was 99%, so the guard entered COOLDOWN with pause_reason: weekly — the agent stopped dispatching new subagents even though the session window looked safe.

Claude Code session: weekly COOLDOWN at 99% while the 5-hour window is at 4%

Forced re-arm daemon to enable weekly polling

The force re-arm shows phase: cooldown even though the 5h window just
reset (4%, fresh) — weekly is now what's gating us.

That's exactly why watching weekly mattered — the weekly limit is at 99%
(over the 98% pause threshold), so the guard went to COOLDOWN
(pause_reason: weekly) even though the 5-hour window is fresh (4%).
Without weekly monitoring I'd have kept dispatching subagents straight
into the weekly cap.

Honest limits

  • Cooperative — session must follow skill rules; we brief up front

// HOW IT'S BUILT

// FILES

8 files shipped with this skill. Inline text is the catalog copy. The upstream link is the source repository.

  • skill/usage-guard/SKILL.md13 KB2df792a83b8fupstream ↗
    ---
    name: usage-guard
    description: Arm proactive 5-hour usage protection for long Claude Code sessions (batch, subagents, high window % at start). Daemon reads account-level 5-hour window usage (not per-session). User types /usage-guard at session start. Re-arm every sitting. If user mentions usage-guard by name, read this file and run arm.sh.
    disable-model-invocation: true
    user-invocable: true
    allowed-tools: Bash, Read, Write, Edit
    argument-hint: [resume | your task description]
    ---
    
    # usage-guard
    
    Proactive usage guard for long Claude Code sessions (Desktop Code tab or CLI). **Invoke once at session start** before heavy batch, subagent, or overnight work — especially when the account window is already partly used.
    
    ### Why account-level monitoring matters
    
    Each Claude session only sees its own usage. The **shared 5-hour window** is account-level — you can start at 58% in one session while another tab or earlier work already pushed the window to 94%. The daemon polls the OAuth usage API (same as Desktop Settings) so the guard sees the real window, not just this chat's view.
    
    ### Re-arm every sitting
    
    **Arms do not survive** Desktop quit, crash, or daemon exit. At the start of **every** new sitting, run `/usage-guard` (or `/usage-guard resume` if continuing a paused task). If `arm.sh` prints `"warning"`, the previous guard was stale — proceed with the new arm.
    
    ## If the user mentions usage-guard without `/usage-guard`
    
    When the user says "use usage-guard", "pay attention to usage limits", or names this skill but does not run the slash command:
    
    1. **Follow this file** (you are reading it — treat that as the contract).
    2. Run `arm.sh` via bash before heavy work (same as ARM MODE below).
    3. Tell the user: `/usage-guard` is the normal entry point; with `disable-model-invocation` it may not show in the slash picker — **typing `/usage-guard` still works**.
    
    Do **not** auto-arm on your own initiative without the user asking for usage protection.
    
    ## When the user invokes `/usage-guard`
    
    ### Mode detection
    
    - If the argument is `resume` (or starts with `resume`): **RESUME MODE** (skip arm, go to section 4).
    - Otherwise: **ARM MODE**.
    
    ---
    
    ## 1. ARM MODE — start guard
    
    Run:
    
    ```bash
    bash "${CLAUDE_SKILL_DIR}/scripts/arm.sh" {{ARGUMENTS}}
    ```
    
    If arm fails, **stop** and tell the user to run `usage-guard doctor` in Terminal. Do not start heavy work without a successful arm.
    
    Read `~/.usage-guard/control.json` once and confirm:
    
    - `armed: true`
    - `phase` is `normal` (or `five_hour_percent` is set) — **not** stuck on `waiting_first_poll` without a live daemon
    - If arm JSON output includes `"warning"`, tell the user the prior guard was not active and this is a fresh arm
    - Report go/no-go using arm JSON: `five_hour_percent`, `five_hour_reset_local`, `seconds_until_five_hour_reset`, `state` — **not** raw UTC strings
    - If `weekly_percent` is present (weekly monitoring enabled in config), also report weekly % and `weekly_reset_local` / `seconds_until_weekly_reset`. **Weekly can trigger PAUSE even when 5h looks safe.**
    - If present in control.json, also report **extra usage wallet**: `extra_used_credits`, `extra_monthly_limit`, `extra_utilization`, `extra_currency` (amounts are in cents; `usage-guard status` formats them), or run `usage-guard poll` for a live snapshot
    
    **If arm JSON has `"already_armed": true`** (daemon from a prior sitting):
    
    - **Proceed** — guard is active; do not `--force` restart unless user asks.
    - **Same arc, new sitting** → `join.sh --task "label"` (not arm with a task — task is ignored on already_armed; JSON includes `task_ignored` if you tried).
    - **After join** → `checkpoint.sh` writes to `sitting_session_id` automatically (stored in control.json). Do **not** use primary `session_id` unless you pass `--session-id` intentionally.
    - **Continuing paused work** → `/usage-guard resume` (not join, not fresh arm).
    
    **Decision tree:** already_armed + same sitting → proceed on `checkpoint_writes_target` | new sitting same arc → join.sh | paused task → resume | dead daemon → arm fresh
    
    **Warmup:** right after arm, `phase` may be `waiting_first_poll` with null telemetry while the daemon fetches usage. `arm.sh` blocks up to ~45s for the first poll. If `phase` is still `waiting_first_poll` after arm returns, the daemon is warming up — **do not** start heavy subagent batches yet; re-read control.json in a few seconds. If `five_hour_percent` stays null and daemon is dead (`usage-guard status` → daemon not running), stop and run `usage-guard doctor`.
    
    ---
    
    ## 2. Session contract (inform up front — before main work)
    
    You are now **usage-guard armed**. Follow this for the rest of this session:
    
    ### Control file (only signal that matters)
    
    - Path: `~/.usage-guard/control.json`
    - Obey **`state` only**: `RUN` = continue, `PAUSE` / `COOLDOWN` / `UNKNOWN` = stop dispatching new work.
    - **Either limit can pause:** account **5-hour window** (default 90%) **or** **weekly limit** (opt-in, default 98%) — check `pause_reason` (`five_hour`, `weekly`, or `both`) in control.json.
    - **`UNKNOWN`:** guard is blind (usage API returned no 5h percent for several polls) **or** the file is past `valid_until`. Do **not** start heavy work; tell user to run `claude login` or `usage-guard doctor`. Prefer `effective_state` if present — it already fails closed on staleness/blindness.
    - **Freshness:** if `now` is past `valid_until` (or `stale: true`), treat as `UNKNOWN` even when `state` still says `RUN` (daemon may have died while numbers looked healthy).
    - **Never** decide pause/continue from `five_hour_percent` yourself.
    - **Never compare timestamps yourself** (`five_hour_resets_at`, `sleep_until`, etc.). UTC trips up models. Use precomputed fields only:
      - `seconds_until_five_hour_reset` — positive = reset not yet; negative or `five_hour_reset_pending: false` = reset time passed
      - `five_hour_reset_local` — for user-facing reports (local timezone, not UTC)
      - `weekly_percent`, `weekly_reset_local`, `seconds_until_weekly_reset` — when weekly monitoring is enabled (OAuth `seven_day` = Desktop "All models" weekly bar)
      - If `state` is **`RUN`**, continue — **do not** call percent "stale" because a UTC clock comparison looked past. Wrong timezone math caused false "reset already passed" bugs.
    - **Post-reset poll lag:** `five_hour_reset_pending: false` + non-null `five_hour_percent` (e.g. 88% with reset time an hour ago) means the **old window's percent** until the daemon re-polls — not a reason to pause. Check `awaiting_post_reset_poll` and `percent_note`; trust **`state`**. Expect correction at `daemon_next_poll_at` / `daemon_next_poll_local`.
    - After a **window reset**, `five_hour_percent` may be `null` until the daemon's next poll. If `state` is `RUN`, trust `state` (check `last_reset_at` if present) — do not wait for the user to return.
    - **`session_check_seconds`** — recommended delay for self-paced `/loop` guard ticks while armed. During `PAUSE`/`COOLDOWN`, prefer **`sleep_until`** instead. Daemon polling is separate (`daemon_next_poll_at`).
    
    ### Checkpoint file
    
    - Path: `~/.usage-guard/sessions/<session_id>/checkpoint.json` (session_id from control.json)
    - After **every completed unit** (file, batch item, subagent return): update checkpoint (`done`, `next`, `note`).
    - **Prefer bash** (atomic, no Read-before-Write harness issue):
    
    ```bash
    bash "${CLAUDE_SKILL_DIR}/scripts/checkpoint.sh" --quiet --json '{"done":["item-id"],"next":"next-item","note":""}'
    ```
    
    Or flags: `checkpoint.sh --quiet --done item-id --next "next-item" --note "" --task "short label for status"`
    
    Set **`task`** on the first checkpoint (via `/usage-guard <task>` at arm, or `checkpoint.sh --task`) so `usage-guard status` stays readable.
    
    ### Multi-session arcs (orchestrator + worker sessions)
    
    PAUSE/RUN is **account-level** (one daemon). Checkpoints are **per `session_id`**.
    
    - First sitting: `/usage-guard <task>` (arms daemon; sets primary `session_id` and `sitting_session_id`).
    - Later sitting (daemon already running): `join.sh --task "this sitting's label"` — sets `sitting_session_id` in control.json; **all `checkpoint.sh` writes go there** until the next arm/join.
    - To **share one checkpoint chain** across sittings (advanced): pass `--session-id <existing>` to checkpoint.sh explicitly.
    - **join** = new sitting, new checkpoint file, same daemon. **resume** = continue a **paused** task from checkpoint (COOLDOWN/PAUSE arc), not "daemon already live."
    
    `active_session_ids` lists all sittings; `sitting_session_id` is the active checkpoint write target.
    
    - User can run `usage-guard status` in Terminal to see progress if Desktop UI is stuck.
    
    ### Safe checkpoints (critical for subagents / long runs)
    
    Read control.json only at these times:
    
    1. Before starting the main task loop
    2. **Before dispatching each subagent or parallel batch**
    3. After each subagent returns
    4. Before starting any new multi-step tool sequence expected to take >10 minutes
    5. At each `/loop` iteration dedicated to guard checks
    
    **Never** rely on the user sending a chat message mid-run — messages queue during subagent work.
    
    ### On `state == PAUSE` or `COOLDOWN`
    
    1. Finish the **current atomic unit** only — do not abandon mid-write.
    2. Update checkpoint with `done`, `next`, clear `note`.
    3. Tell the user: paused near usage limit (`pause_reason`); daemon may macOS-notify at reset. **Do not** treat that as a substitute for scheduling your own wake-up below.
    4. **Do not** start new subagents, batches, or long tool chains this turn.
    5. During `COOLDOWN`, use **`sleep_until`** / `seconds_until_five_hour_reset` for wait duration — do **not** poll every 5 minutes.
    
       **Before ending this turn**, you **must** schedule a wake-up. **Forbidden:** ending with "ping me when reset", "tell me when you're back", or "message me after the window resets".
    
       Pick **one** path (in order of preference):
    
       **A. `/loop` guard tick (preferred)** — any session type:
       ```text
       /loop Read ~/.usage-guard/control.json. If PAUSE/COOLDOWN: checkpoint if needed; sleep until sleep_until (cap 59m per iteration; chain). If RUN: continue from checkpoint next.
       ```
       Dynamic `/loop` (no interval) uses `ScheduleWakeup` internally after each iteration.
    
       **B. One-shot wake at reset** — if you are **not** starting `/loop`:
       - Natural language: `in N minutes, re-read ~/.usage-guard/control.json; if RUN continue checkpoint next; if still COOLDOWN schedule again`
       - Or `CronCreate` one-shot pinned to `five_hour_reset_local` (+ ~3 min margin)
       - Claude may implement this via `ScheduleWakeup` or `CronCreate` — either is fine
       - Chain: if still `COOLDOWN` after fire, schedule the next check (cap 59m steps)
    
       **C. Non-negotiable:** schedule *something* before ending the turn. Platform docs emphasize `ScheduleWakeup` for dynamic `/loop`, but it often works for one-shot waits too — **never** fall back to asking the user to ping you.
    
    6. If wake scheduling fails (cron disabled, provider lacks loop-dynamic), say so explicitly and give `five_hour_reset_local` — checkpoint is still safe for `/usage-guard resume`.
    
    ### On `state == RUN` with existing checkpoint
    
    Continue from `next` in checkpoint; skip items in `done`.
    
    ### Subagent discipline (long batch runs)
    
    - Prefer **smaller** subagent batches when armed (e.g. 3–5 items, not 50).
    - Before each dispatch: read control.json; if not `RUN`, do not dispatch.
    - Main chat orchestrates workload so subagents respect the timetable — **no mid-run chat reminders**.
    
    ### Session wrap — report window delta
    
    At session end (or before a long pause), tell the user:
    
    - **5h window now:** `five_hour_percent`, `five_hour_reset_local`, `state`
    - **Weekly limit** (if enabled): `weekly_percent`, `weekly_reset_local`, `pause_reason`
    - **Extra usage wallet** (if enabled): `extra_used_credits` / `extra_monthly_limit` / `extra_utilization` from control.json, or `usage-guard status` for formatted amounts
    - **Delta this sitting** if you recorded percent at arm/join (e.g. "4% → 41% this session")
    - This is the most useful user-facing summary — report it even without subagents
    
    ---
    
    ## 3. Start work
    
    If the user provided a task in `/usage-guard <task>`, begin it under the contract above using self-paced `/loop`.
    
    Example loop prompt:
    
    ```text
    /loop Read ~/.usage-guard/control.json. If PAUSE/COOLDOWN: checkpoint and stop new work; sleep until sleep_until (or session_check_seconds). If RUN: continue task from checkpoint.
    ```
    
    ---
    
    ## 4. RESUME MODE — `/usage-guard resume`
    
    1. Read `~/.usage-guard/control.json` — if `state` is not `RUN`, tell user to wait (show `five_hour_reset_local` / `sleep_until_local`, or `seconds_until_*`).
    2. Read checkpoint for `sitting_session_id` (or `checkpoint_writes_target` / primary `session_id` if no join).
    3. Continue from `next`; dedupe using `done`.
    4. Re-arm only if `armed` is false: run `arm.sh` again.
    
    ---
    
    ## 5. Limits (be honest with user)
    
    - Cannot force-stop a running subagent from outside; guard prevents **new** work after PAUSE.
    - Progress safety depends on frequent checkpoint writes.
    - After force-quit Desktop, use `/usage-guard resume` in a **new** session (re-arms daemon if needed).
    - Daemon exit does **not** keep the guard active — always `/usage-guard` or `/usage-guard resume` at the start of a sitting.
    
  • skill/usage-guard/scripts/arm.sh302 Bbde25c395f12upstream ↗
    #!/usr/bin/env bash
    set -euo pipefail
    
    SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
    # shellcheck source=resolve-guard.sh
    source "${SCRIPT_DIR}/resolve-guard.sh"
    
    TASK="${*:-}"
    resolve_guard_bin
    
    if [ -n "$TASK" ] && [ "$TASK" != "resume" ]; then
      $GUARD_BIN arm --task "$TASK"
    else
      $GUARD_BIN arm
    fi
    
  • skill/usage-guard/scripts/checkpoint.sh211 B5751dcd56162upstream ↗
    #!/usr/bin/env bash
    set -euo pipefail
    
    SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
    # shellcheck source=resolve-guard.sh
    source "${SCRIPT_DIR}/resolve-guard.sh"
    
    resolve_guard_bin
    exec $GUARD_BIN checkpoint "$@"
    
  • skill/usage-guard/scripts/disarm.sh197 B9a3639979b83upstream ↗
    #!/usr/bin/env bash
    set -euo pipefail
    
    SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
    # shellcheck source=resolve-guard.sh
    source "${SCRIPT_DIR}/resolve-guard.sh"
    
    resolve_guard_bin
    $GUARD_BIN disarm
    
  • skill/usage-guard/scripts/join.sh211 Bd33913646303upstream ↗
    #!/usr/bin/env bash
    set -euo pipefail
    
    SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
    # shellcheck source=resolve-guard.sh
    source "${SCRIPT_DIR}/resolve-guard.sh"
    
    resolve_guard_bin
    exec $GUARD_BIN arm --join "$@"
    
  • skill/usage-guard/scripts/resolve-guard.sh1.6 KBf88b8383908aupstream ↗
    #!/usr/bin/env bash
    # Sourced by skill scripts. Sets GUARD_BIN to the CLI wrapper or "python3 -m usage_guard".
    
    _resolve_guard_lib="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
    
    _resolve_guard_fail() {
      local stale="${1:-}"
      echo "usage-guard: cannot find the usage_guard package." >&2
      echo "  Re-run ./install.sh from your usage-guard clone, then: usage-guard doctor" >&2
      if [ -n "$stale" ]; then
        echo "  Stale install path: ${stale}" >&2
      fi
      return 1
    }
    
    # Sets GUARD_BIN. Exits 1 with a helpful message if nothing resolves.
    resolve_guard_bin() {
      GUARD_BIN=""
    
      if [ -n "${USAGE_GUARD_BIN:-}" ]; then
        if command -v "$USAGE_GUARD_BIN" >/dev/null 2>&1 || [ -x "$USAGE_GUARD_BIN" ]; then
          GUARD_BIN="$USAGE_GUARD_BIN"
          return 0
        fi
      fi
    
      if command -v usage-guard >/dev/null 2>&1; then
        GUARD_BIN="usage-guard"
        return 0
      fi
    
      local wrapper="${HOME}/.local/bin/usage-guard"
      if [ -x "$wrapper" ]; then
        GUARD_BIN="$wrapper"
        return 0
      fi
    
      local repo_root=""
      local repo_root_file="${HOME}/.usage-guard/repo-root"
      if [ -f "$repo_root_file" ]; then
        IFS= read -r repo_root < "$repo_root_file" || true
        if [ -n "$repo_root" ] && [ -d "${repo_root}/usage_guard" ]; then
          export PYTHONPATH="${repo_root}:${PYTHONPATH:-}"
          GUARD_BIN="python3 -m usage_guard"
          return 0
        fi
      fi
    
      local dev_root
      dev_root="$(cd "${_resolve_guard_lib}/../../.." && pwd)"
      if [ -d "${dev_root}/usage_guard" ]; then
        export PYTHONPATH="${dev_root}:${PYTHONPATH:-}"
        GUARD_BIN="python3 -m usage_guard"
        return 0
      fi
    
      _resolve_guard_fail "$repo_root"
      exit 1
    }
    
  • skill/usage-guard/scripts/status.sh197 B2ccc7cc61f44upstream ↗
    #!/usr/bin/env bash
    set -euo pipefail
    
    SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
    # shellcheck source=resolve-guard.sh
    source "${SCRIPT_DIR}/resolve-guard.sh"
    
    resolve_guard_bin
    $GUARD_BIN status
    
  • README.mdupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

Plain-text copy, no login: /skill-bundles/shirley-xue-2025-usage-guard-skill-usage-guard.md

// REPO STATS

15 stars
0 open issues
Last commit: 3mo ago