---
name: bedrock-monitor-reference
description: Bedrock quota monitoring plugin reference — how it works, what it shows, and how to troubleshoot.
---

# Bedrock Quota Monitor

Shows Bedrock spending (3h/daily/weekly) on the Claude Code status line and warns Claude about high quota usage at session start.

## How it works

The plugin runs a **single synchronous SessionStart hook** that:

1. **Refreshes quota cache** — queries CloudWatch `Custom/Bedrock` metrics (spend + limits per user), caches to `/tmp/bedrock-quota-cache-<user>.json` for 5 minutes
2. **Auto-configures statusline** — on first run, backs up existing settings and points `~/.claude/settings.json` statusLine to the plugin's script (one-time, with `.pre-bedrock-monitor.bak` backup)
3. **Warns Claude** — if any quota window is above 50%, returns a `systemMessage` that Claude MUST surface in its first response

**Zero config required** — just install the plugin. Quota limits are read from CloudWatch (published by the Quota Enforcer Lambda), not from env vars.

## What users see

### Status line (after every assistant message)

| Max window % | Icon | Example |
|---|---|---|
| <40% | Hidden | `Claude Opus 4.6 │ API $1.23 │ ████░░░░ 42%` |
| 40-49% | 🟢 | `... │ 🟢 3h:45% day:30% │ ████░░░░ 42%` |
| 50-79% | 🟡 | `... │ 🟡 3h:65% day:50% wk:30% │ ████░░░░ 42%` |
| 80-99% | 🔴 | `... │ 🔴 3h:85% day:67% wk:42% │ ████░░░░ 42%` |
| 100%+ | 🚫 | `... │ 🚫 3h:105% day:107% wk:108% │ ████░░░░ 42%` |

Individual windows below 20% are hidden to reduce noise.

### System message (at session start, 50%+ only)

Claude will proactively warn about quota status in its first response, including spend vs limit per window and advice to reduce token-heavy operations.

## Prerequisites

- AWS CLI with `bedrock` profile configured
- `cloudwatch:GetMetricData` IAM permission on `Custom/Bedrock` namespace (added to group policy in `bedrock/users.tf`)
- `jq` installed
- Quota Enforcer Lambda publishing limit metrics (`QuotaWindowCost3hLimit`, etc.)

## Troubleshooting

**No quota shown on statusline:**
- Spend is below 40% — working as intended
- Check cache: `cat /tmp/bedrock-quota-cache-$(whoami).json`
- Not on Bedrock? Only shows when `CLAUDE_CODE_USE_BEDROCK=1`

**Stale data:**
- Cache TTL is 5 minutes: `rm /tmp/bedrock-quota-cache-$(whoami).json` and restart session

**AccessDenied on CloudWatch:**
- The `AllowCloudWatchQuotaMetrics` policy hasn't been applied yet
- Test: `aws cloudwatch get-metric-data --profile bedrock --region eu-central-1 ...`

**Restore old statusline:**
```bash
cp ~/.claude/settings.json.pre-bedrock-monitor.bak ~/.claude/settings.json
```

## Env var overrides (optional)

Only needed if CloudWatch limit metrics are unavailable:

| Variable | Default | Description |
|---|---|---|
| `BEDROCK_QUOTA_3H` | `6.00` | 3-hour window limit (USD) |
| `BEDROCK_QUOTA_DAY` | `15.00` | Daily window limit (USD) |
| `BEDROCK_QUOTA_WEEK` | `50.00` | Weekly window limit (USD) |
| `BEDROCK_QUOTA_CACHE_TTL` | `300` | Cache lifetime in seconds |