# dream-rainy/usage-guard architecture

> Architecture diagram of the GitHub repository dream-rainy/usage-guard, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dream-rainy/usage-guard
- Repository: https://github.com/dream-rainy/usage-guard

## Overview

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: [`plugins/usage-guard/scripts/usage-guard.js`](https://github.com/dream-rainy/usage-guard/blob/main/plugins/usage-guard/scripts/usage-guard.js) (Event dispatch), [`plugins/usage-guard/hooks/hooks.json`](https://github.com/dream-rainy/usage-guard/blob/main/plugins/usage-guard/hooks/hooks.json) (Lifecycle hooks)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_hook["Lifecycle integration"]
  node_hooks["Lifecycle hooks<br/>[hooks.json]"]
  node_runtime["Hook runtime<br/>[usage-guard.js]"]
  node_event["Event dispatch<br/>[usage-guard.js]"]
  node_guidance["Usage guidance<br/>[SKILL.md]"]
end

subgraph group_policy["Usage policy"]
  node_usage["Usage evaluation<br/>[usage-guard.js]"]
  node_windows["Window classification<br/>[usage-guard.js]"]
  node_policyactions["Policy actions<br/>[usage-guard.js]"]
  node_toolgate["Tool gating<br/>[usage-guard.js]"]
end

subgraph group_recovery["Checkpoint and recovery"]
  node_checkpoint["Checkpoint verification<br/>[usage-guard.js]"]
  node_pause["Pause tracking<br/>[usage-guard.js]"]
  node_resume["Resume planning<br/>[usage-guard.js]"]
  node_heartbeat["Heartbeat request<br/>[usage-guard.js]"]
end

node_codex(("Codex CLI"))

node_codex -->|"invokes lifecycle"| node_hooks
node_hooks -.->|"dispatches events"| node_runtime
node_runtime -->|"dispatches event"| node_event
node_event -->|"refreshes usage"| node_usage
node_usage -->|"classifies windows"| node_windows
node_event -->|"checks policy"| node_policyactions
node_policyactions -->|"gates tools"| node_toolgate
node_event -->|"checks marker"| node_checkpoint
node_event -->|"updates pause"| node_pause
node_event -->|"plans continuation"| node_resume
node_resume -->|"requests heartbeat"| node_heartbeat

click node_hooks "https://github.com/dream-rainy/usage-guard/blob/main/plugins/usage-guard/hooks/hooks.json"
click node_runtime "https://github.com/dream-rainy/usage-guard/blob/main/plugins/usage-guard/scripts/usage-guard.js"
click node_event "https://github.com/dream-rainy/usage-guard/blob/main/plugins/usage-guard/scripts/usage-guard.js"
click node_usage "https://github.com/dream-rainy/usage-guard/blob/main/plugins/usage-guard/scripts/usage-guard.js"
click node_windows "https://github.com/dream-rainy/usage-guard/blob/main/plugins/usage-guard/scripts/usage-guard.js"
click node_policyactions "https://github.com/dream-rainy/usage-guard/blob/main/plugins/usage-guard/scripts/usage-guard.js"
click node_toolgate "https://github.com/dream-rainy/usage-guard/blob/main/plugins/usage-guard/scripts/usage-guard.js"
click node_checkpoint "https://github.com/dream-rainy/usage-guard/blob/main/plugins/usage-guard/scripts/usage-guard.js"
click node_pause "https://github.com/dream-rainy/usage-guard/blob/main/plugins/usage-guard/scripts/usage-guard.js"
click node_resume "https://github.com/dream-rainy/usage-guard/blob/main/plugins/usage-guard/scripts/usage-guard.js"
click node_heartbeat "https://github.com/dream-rainy/usage-guard/blob/main/plugins/usage-guard/scripts/usage-guard.js"
click node_guidance "https://github.com/dream-rainy/usage-guard/blob/main/plugins/usage-guard/skills/usage-guard/SKILL.md"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_hooks,node_runtime,node_event,node_guidance toneBlue
class node_usage,node_windows,node_policyactions,node_toolgate toneAmber
class node_checkpoint,node_pause,node_resume,node_heartbeat toneMint
class node_codex toneIndigo
```

## Components

### Lifecycle integration

- [Lifecycle hooks](https://github.com/dream-rainy/usage-guard/blob/main/plugins/usage-guard/hooks/hooks.json): `plugins/usage-guard/hooks/hooks.json`
- [Hook runtime](https://github.com/dream-rainy/usage-guard/blob/main/plugins/usage-guard/scripts/usage-guard.js): `plugins/usage-guard/scripts/usage-guard.js`
- [Event dispatch](https://github.com/dream-rainy/usage-guard/blob/main/plugins/usage-guard/scripts/usage-guard.js): `plugins/usage-guard/scripts/usage-guard.js`
- [Usage guidance](https://github.com/dream-rainy/usage-guard/blob/main/plugins/usage-guard/skills/usage-guard/SKILL.md): `plugins/usage-guard/skills/usage-guard/SKILL.md`

### Usage policy

- [Usage evaluation](https://github.com/dream-rainy/usage-guard/blob/main/plugins/usage-guard/scripts/usage-guard.js): `plugins/usage-guard/scripts/usage-guard.js`
- [Window classification](https://github.com/dream-rainy/usage-guard/blob/main/plugins/usage-guard/scripts/usage-guard.js): `plugins/usage-guard/scripts/usage-guard.js`
- [Policy actions](https://github.com/dream-rainy/usage-guard/blob/main/plugins/usage-guard/scripts/usage-guard.js): `plugins/usage-guard/scripts/usage-guard.js`
- [Tool gating](https://github.com/dream-rainy/usage-guard/blob/main/plugins/usage-guard/scripts/usage-guard.js): `plugins/usage-guard/scripts/usage-guard.js`

### Checkpoint and recovery

- [Checkpoint verification](https://github.com/dream-rainy/usage-guard/blob/main/plugins/usage-guard/scripts/usage-guard.js): `plugins/usage-guard/scripts/usage-guard.js`
- [Pause tracking](https://github.com/dream-rainy/usage-guard/blob/main/plugins/usage-guard/scripts/usage-guard.js): `plugins/usage-guard/scripts/usage-guard.js`
- [Resume planning](https://github.com/dream-rainy/usage-guard/blob/main/plugins/usage-guard/scripts/usage-guard.js): `plugins/usage-guard/scripts/usage-guard.js`
- [Heartbeat request](https://github.com/dream-rainy/usage-guard/blob/main/plugins/usage-guard/scripts/usage-guard.js): `plugins/usage-guard/scripts/usage-guard.js`

### Other components

- **Codex CLI**

## Connections

- Codex CLI → Lifecycle hooks: invokes lifecycle (evidence: `README.md`)
- Lifecycle hooks → Hook runtime: dispatches events
- Hook runtime → Event dispatch: dispatches event (evidence: `plugins/usage-guard/scripts/usage-guard.js`)
- Event dispatch → Usage evaluation: refreshes usage (evidence: `plugins/usage-guard/scripts/usage-guard.js`)
- Usage evaluation → Window classification: classifies windows (evidence: `plugins/usage-guard/scripts/usage-guard.js`)
- Event dispatch → Policy actions: checks policy (evidence: `plugins/usage-guard/scripts/usage-guard.js`)
- Policy actions → Tool gating: gates tools (evidence: `plugins/usage-guard/scripts/usage-guard.js`)
- Event dispatch → Checkpoint verification: checks marker (evidence: `plugins/usage-guard/scripts/usage-guard.js`)
- Event dispatch → Pause tracking: updates pause (evidence: `plugins/usage-guard/scripts/usage-guard.js`)
- Event dispatch → Resume planning: plans continuation (evidence: `plugins/usage-guard/scripts/usage-guard.js`)
- Resume planning → Heartbeat request: requests heartbeat (evidence: `plugins/usage-guard/scripts/usage-guard.js`)
