How dream-rainy/usage-guard works
Usage Guard is a cross-platform Codex plugin that applies usage-aware policies at lifecycle boundaries, narrows work as limits approach, and supports bounded checkpointing and same-thread recovery. Its principal flow is a Codex hook event through usage evaluation and policy enforcement, with verified checkpoints enabling eligible short-window resume scheduling. The runtime is concentrated in one large script, so several distinct responsibilities share its path. Hook wiring and unsampled implementation details are not inferred beyond README-supported behavior.
Main entry points: usage-guard.js Event dispatch · hooks.json Lifecycle hooks
Components 13
Lifecycle integration
- Lifecycle hooks
plugins/usage-guard/hooks/hooks.json - Hook runtime
plugins/usage-guard/scripts/usage-guard.js - Event dispatch
plugins/usage-guard/scripts/usage-guard.js - Usage guidance
plugins/usage-guard/skills/usage-guard/SKILL.md
Usage policy
- Usage evaluation
plugins/usage-guard/scripts/usage-guard.js - Window classification
plugins/usage-guard/scripts/usage-guard.js - Policy actions
plugins/usage-guard/scripts/usage-guard.js - Tool gating
plugins/usage-guard/scripts/usage-guard.js
Checkpoint and recovery
- Checkpoint verification
plugins/usage-guard/scripts/usage-guard.js - Pause tracking
plugins/usage-guard/scripts/usage-guard.js - Resume planning
plugins/usage-guard/scripts/usage-guard.js - Heartbeat request
plugins/usage-guard/scripts/usage-guard.js
Other components
- Codex CLI
Connections 11
- Codex CLI → Lifecycle hooks: invokes lifecycle
README.md - Lifecycle hooks → Hook runtime: dispatches events
- Hook runtime → Event dispatch: dispatches event
plugins/usage-guard/scripts/usage-guard.js - Event dispatch → Usage evaluation: refreshes usage
plugins/usage-guard/scripts/usage-guard.js - Usage evaluation → Window classification: classifies windows
plugins/usage-guard/scripts/usage-guard.js - Event dispatch → Policy actions: checks policy
plugins/usage-guard/scripts/usage-guard.js - Policy actions → Tool gating: gates tools
plugins/usage-guard/scripts/usage-guard.js - Event dispatch → Checkpoint verification: checks marker
plugins/usage-guard/scripts/usage-guard.js - Event dispatch → Pause tracking: updates pause
plugins/usage-guard/scripts/usage-guard.js - Event dispatch → Resume planning: plans continuation
plugins/usage-guard/scripts/usage-guard.js - Resume planning → Heartbeat request: requests heartbeat
plugins/usage-guard/scripts/usage-guard.js