Setup

---
name: setup
description: Configure the GENESIS usage sensor interactively - set the trigger cap (5h/7d), choose advise/enforce/off, toggle desktop notifications, and optionally wire the statusline readout. Persists to settings.json. Use after installing genesis-usage, or when the user asks to set up / change the usage cap, threshold, sensor mode, notifications, or the usage statusline.
---

# /genesis-usage:setup - Configure the usage sensor

The sensor works out of the box; this makes it yours. It writes choices into
`~/.claude/settings.json` so you never hand-edit JSON or memorize an env var.

If the user passed a number as an argument (e.g. `/genesis-usage:setup 80`),
treat it as the 5-hour cap - but still show the weekly cap (default 85) so it is
never set silently. A second number sets the weekly cap too
(`/genesis-usage:setup 80 75`).

## 1. Check eligibility first (be honest)

The sensor only fires on **Claude.ai Pro/Max** (Claude Code **v1.0.80+**), and
only **after the first model response** in a session - that is when Claude Code
starts sending `rate_limits`. On API-key-only accounts it stays silent by
design. If the user is on API keys, say so plainly and stop - configuring it
will not make data appear.

**Critical:** `rate_limits` is delivered to the **statusline** input only, never
to hook input. The sensor is a Stop hook, so it gets its data from a bridge file
the statusline writes each render. **The statusline is therefore required, not
optional** - without it the sensor has no usage data and never fires. Treat
step 4 as part of the core setup, not an extra.

## 2. Ask what they want (one short round)

Show every setting's current value (or its default) and let the user keep or
change it - never leave a setting at a default the user never saw. Both caps are
first-class; present them as a pair:

- **5-hour cap** - usage %% that triggers the warning (default 90).
- **7-day (weekly) cap** - usage %% that triggers the weekly warning (default 85).
- **Mid-turn watch** - `on`/`off` (default off). Ask this **right after the two
  caps**, because it builds on them. Describe it plainly: the normal sensor only
  checks at the end of each turn, so a single large multi-tool turn can blow past
  the cap before it ever fires. Turning this on adds a PostToolUse hook that
  checks the same usage numbers *after every tool call*, so a crossing is caught
  between tools - in `advise` it warns you and Claude mid-turn; in `enforce`
  (inside a GENESIS project) it writes a snapshot itself and tells Claude to run
  `/genesis:close` before the next tool. Default off because it runs on a hot
  path; suggest `on` to anyone who runs long agentic turns. It reuses the same
  caps and the once-per-bucket throttle, so it adds no new tuning.
- **Mode** - `advise` (warn in the terminal, default), `enforce` (block the
  turn so Claude runs `/genesis:close`), or `off`. Note: mid-turn watch follows
  this same mode.
- **Desktop notification** - `on`/`off` (default off). When on, the sensor also
  posts a macOS notification, useful when you are working in another app.
- **Statusline** - required data feed (see step 4). Default to installing it;
  only skip if the user already runs a statusline they will not replace - and
  warn them the sensor cannot fire without one.

Keep it to one round: present all six with their current values, take the
answers, done. Efficient is fine - silent is not. Even when the user only cares
about the 5-hour cap, show the weekly cap's value so it is a visible choice, not
a hidden default.

## 3. Write the config

Merge into `~/.claude/settings.json` under `"env"` (create the block if absent;
preserve anything already there). **Write both caps the user confirmed - even if
a value equals the default - so each is visible and editable, never silent.** For
mode, notify, and grace, write only what differs from the default to keep the
block tidy:

```json
{
  "env": {
    "GENESIS_USAGE_THRESHOLD": "80",
    "GENESIS_USAGE_WEEK_THRESHOLD": "80",
    "GENESIS_USAGE_MODE": "advise",
    "GENESIS_USAGE_MIDTURN": "on",
    "GENESIS_USAGE_NOTIFY": "on"
  }
}
```

Write `GENESIS_USAGE_MIDTURN` only when the user turns it on (default off, so
omit it otherwise to keep the block tidy).

For a **per-project** cap instead of global, write the same `"env"` block into
that project's `.claude/settings.json` - it overrides the global default there.
This is the right answer when only some repos need a tighter cap (or want mid-turn
watch in just one repo).

Full variable reference:

| Variable | Default | Meaning |
|----------|---------|---------|
| `GENESIS_USAGE_MODE` | `advise` | `advise`, `enforce`, or `off`. Applies to both the turn-end and mid-turn sensors. |
| `GENESIS_USAGE_THRESHOLD` | `90` | 5-hour usage %% that triggers. |
| `GENESIS_USAGE_WEEK_THRESHOLD` | `85` | 7-day usage %% that triggers. |
| `GENESIS_USAGE_MIDTURN` | `off` | `on` adds the PostToolUse mid-turn watch (catches a crossing between tool calls). |
| `GENESIS_USAGE_GRACE_SECS` | `120` | Stay silent if the window resets within this many seconds. |
| `GENESIS_USAGE_BRIDGE_MAX_AGE` | `900` | Ignore the statusline bridge file if older than this many seconds. |
| `GENESIS_USAGE_NOTIFY` | `off` | `on` posts a macOS desktop notification when the sensor fires. |

**Changing it later by hand:** edit the same `"env"` block in
`~/.claude/settings.json` (global) or a repo's `.claude/settings.json`
(per-project). For example, to turn mid-turn watch on globally, add
`"GENESIS_USAGE_MIDTURN": "on"`; to turn it off, set it to `"off"` or remove the
line. Toggling the mid-turn hook **on or off requires restarting Claude Code**
(it registers a new hook); the caps, mode, and notify settings re-read every turn
and need no restart.

`enforce` only blocks inside a GENESIS project (one with `docs/registry/`);
elsewhere it falls back to `advise`. `GENESIS_OFF=1` silences this and every
GENESIS hook entirely.

## 4. The statusline (required data feed)

This is not cosmetic: the statusline writes the bridge file the Stop-hook sensor
reads, so it is the sensor's only source of usage data. Install it unless the
user explicitly keeps another statusline. One statusline can be active at a time,
so never clobber an existing one without asking - if the user declines, tell them
plainly the sensor will stay silent until a feed exists.

1. Resolve this plugin's installed directory and the absolute path to
   `statusline/statusline.sh` (the `statusLine` setting does not expand
   `${CLAUDE_PLUGIN_ROOT}`). Confirm it is executable.
2. If `~/.claude/settings.json` already has a `statusLine`, show it and ask
   before replacing. Otherwise set:

   ```json
   "statusLine": { "type": "command", "command": "/abs/path/to/statusline.sh" }
   ```

3. Restart Claude Code for the statusline to take effect.

## 5. Confirm back

Tell the user, in two lines: the effective cap/mode/midturn/notify, and that the
turn-end sensor is live now (it re-reads the env on every turn). If you wired the
statusline, or turned mid-turn watch on or off, remind them to **restart Claude
Code** - both register/​change a hook or statusline and only take effect on a
fresh session.