# Capacity monitor

Capacity monitor is a read-only agent. It trends API request volume and error rates, then warns before traffic or errors look like a capacity problem.

A capacity agent that tracks API request growth, error rates, and approaching resource ceilings.

```mermaid
flowchart TD
  Schedule([Once each morning]) --> Inspect[query_logs and usage APIs]
  Inspect --> Signals["Request growth, error rates, resource trends"]
  Signals --> Limit{Likely to hit a limit?}
  Limit -->|Yes| Report["Trend, projected date, scaling guide"]
  Limit -->|No| Silent[Stay silent]
```

## What it watches

- API request growth against a recent baseline
- Server-error rate increases
- Disk, connection, or table growth when database inspection is available

It uses `query_logs` on project-scoped, read-only [Supabase MCP](https://supabase.com/docs/guides/ai-tools/mcp) and the [Management API usage endpoints](https://supabase.com/docs/reference/api/v1-get-project-usage-api-count) when those are already authorized. It does not change billing, compute, or plan settings. MCP does not expose organization billing totals.

## When it watches

Run it once per day on a schedule.

Run it on demand after an unexpected traffic change.

## What it will output

Capacity monitor reports request growth, error-rate changes, and resource trends. If a metric looks likely to hit a limit within 14 days, it flags the date and the relevant scaling guide.

When the agent finds an issue, it reports in the harness. Send that report wherever you already triage work. Use the connections your harness already has. For example, Codex can open a Linear issue.

Keep the Supabase project read-only. Filing a ticket is work in the harness, not a change to the project.

If you want that routing on every scheduled run, add it to the prompt.

## Set up the agent

**Prompt**

```text
You are "Capacity monitor", a capacity-planning agent for a Supabase project.
Reach the project only through Supabase MCP in read-only mode.

Run once each morning. On each review:
1. Call execute_sql for database size, per-table sizes, and connection counts.
2. Compare today's numbers to the trailing 7-day trend.
3. Call get_advisors with type performance for unindexed foreign keys and
   unused indexes that contribute to growth.
4. If query_logs is available, report API request growth and server-error rate
   changes. Do not infer billing quotas from project API counts.
5. If any metric is projected to hit a limit within 14 days, flag the date
   and the relevant scaling guide.

Do not change billing, compute, or plan settings.

REFERENCE
https://supabase.com/docs/guides/observability/detecting.md#usage
```

**Claude**

Create a Claude routine that runs Capacity monitor once each morning.

1. Connect the [Supabase MCP server](/docs/guides/ai-tools/mcp) with `project_ref` and `read_only=true`.
2. Open [Claude routines](https://claude.ai/code/routines) or run `/schedule` in Claude Code.
3. Name it Capacity monitor. Paste the prompt. Set the schedule to once each morning.

[Claude docs](https://code.claude.com/docs/en/routines)

**Codex**

Create a Codex scheduled task that runs Capacity monitor once each morning.

1. Connect the [Supabase MCP server](/docs/guides/ai-tools/mcp) with `project_ref` and `read_only=true`.
2. Open **Scheduled** in the ChatGPT desktop app, or ask Codex to create a standalone scheduled task.
3. Name it Capacity monitor. Paste the prompt. Set the schedule to once each morning. Each run should start a new chat.

[Codex docs](https://developers.openai.com/codex/app/automations)

**Cursor**

Create a Cursor automation that runs Capacity monitor once each morning.

1. Connect the [Supabase MCP server](/docs/guides/ai-tools/mcp) with `project_ref` and `read_only=true`.
2. Create an automation in the Agents Window, at [cursor.com/automations](https://cursor.com/automations), or with the `/automate` skill.
3. Name it Capacity monitor. Use a scheduled trigger (once each morning, cron `0 9 * * *`). Paste the prompt. Keep the agent read-only, with no repository.

[Cursor docs](https://cursor.com/docs/cloud-agent/automations)