ebb-ai

Workload scheduling for the agentic-AI economy.
Defer non-urgent LLM tasks to cheap, low-load grid windows. ~50%
cheaper inference via Batch APIs, smoother data-center load curves,
auditable carbon receipts. MCP-native, ships as an npm package and
a one-command Claude Code plugin.

AI inference is on track to consume 6.7–12% of US grid load by 2028
(DOE projections).
A lot of agentic-AI workload is deferrable (overnight summaries,
batch analysis, scheduled compliance scans, document processing) but
agent code dispatches it synchronously by default. ebb-ai makes the
choice automatic: the same code that would have fired a sync LLM call
now defers to a cheap, off-peak grid window — and writes an auditable
receipt (cost + carbon + provider + duration) for every dispatch.

import { recommendWindow } from "@ebb-ai/core";
const plan = await recommendWindow({

  deadline: "2026-05-14T08:00:00-04:00",

  region: "US-CAL-CISO",

});
// {

//   scheduledFor:                "2026-05-14T05:00:00.000Z",

//   intensityGCo2PerKwh:         60,

//   band:                        "very_clean",

//   estimatedCarbonGCo2:         0.1,

//   estimatedSavingsVsNowPct:    73,

//   batchEligible:               true,

//   reasoning:

//     "cleanest in-deadline window is 05:00 UTC (very clean mix); " +

//     "~73% cleaner than dispatching now; Batch API saves an " +

//     "additional 50% on cost (24h SLA)"

// }

Same call surfaces as an MCP tool to any compatible agent host
(Claude Desktop, Claude Code, Cursor, Cline, Continue, Zed,
Windsurf, OpenClaw, OpenAI Codex CLI, Pi). The agent asks
recommend_window, sees the plan, then commits via schedule_task
— or doesn't.

> Status: v0.7 · 2026-05-14 · @ebb-ai/{core,mcp,cli} published
> to npm under the @ebb-ai org. One-command Claude Code plugin
> via claude plugin install ebb-ai. Four real-data grid feeds:
> UK National Grid ESO Carbon Intensity API (GB, free no key),
> US EIA Open Data (CAISO / ERCOT / ISO-NE / PJM, free with key),
> ENTSO-E Transparency Platform (FR / DE, free with token), and
> Electricity Maps as universal fallback. Anthropic + OpenAI Batch
> adapters, durable SQLite queue, Python port at parity, live
> dashboard, recommend_window planning endpoint, always-on ebb
> tick CLI with macOS launchd + Linux systemd + pmset/rtcwake wake
> events, full control surface (cancel_task / expedite_task /
> update_deadline / retry_task), receipt redaction, file output,
> retry-with-backoff. 88 + Python tests passing across 4 packages
> and 2 languages. See QUICKSTART.md.

Live demo

Or visit the maintainer-hosted dashboard at
ebb-ai.com to see live grid-load and
carbon-intensity forecasts across the seven regions where the major
LLM providers run inference (CAISO, ERCOT, ISO-NE, PJM, Great Britain,
France, Germany) and to try the best-window planner without installing
anything. Great Britain is powered by the free
National Grid ESO Carbon Intensity API
(real data, no key required); the other zones use Electricity Maps when
a key is configured and a deterministic mock otherwise.

---

Why

AI inference is becoming a major load on US grid infrastructure.
Data-center electricity demand has doubled since 2020 and is projected
to keep rising as agentic workloads scale.
But the same agent code that triggers this load dispatches it
synchronously by default — even when the task is "summarize my inbox
overnight" or "rewrite these 5,000 product descriptions by Friday."
Three things follow:

- Cost. Anthropic and OpenAI both offer Batch APIs at a flat 50%
discount for tasks that can wait up to 24 hours. Almost no agent
code uses them, because the choice has to be made at the call site.
ebb-ai makes the choice automatic — and routes deadline-tolerant
work through the cheaper path.
- Grid load. Data-center AI compute is concentrated in a few
US regions (PJM Mid-Atlantic / Virginia, ERCOT Texas, CAISO
California). Peak-hour AI workloads compete with hospitals,
industrial users, and residential customers for capacity that is
already constrained — Virginia regulators have flagged data-center
load growth as a top-tier reliability concern. Time-shifting
deferrable workloads to off-peak windows reduces the peak the grid
has to plan for.
- Carbon, as a measurable side effect. Grid carbon intensity
varies 30–60% inside a single day. The same dispatch decision that
saves cost and smooths load also emits less CO₂. ebb-ai writes an
auditable receipt for every dispatch — useful for ESG reporting,
cost-accounting, and upcoming compute-disclosure regulations.

ebb-ai automates the choice for any task that is not "answer me
right now."

---

Components

| Package | Purpose |
|---|---|
| @ebb-ai/core | TypeScript core library (v0.2). defer() API, AnthropicAdapter, OpenAIAdapter, opt-in SQLite-backed durable queue. |
| @ebb-ai/mcp | Model Context Protocol server (v0.2). Drop-in for Claude Desktop, Claude Code, OpenClaw, Cursor. |
| ebb-ai (Python) | Python 3.11+ port. asyncio scheduler, aiosqlite persistence, Anthropic + OpenAI adapters. |
| apps/web | Next.js 15 website at https://www.ebb-ai.com — install picker (13 hosts), live carbon-intensity map, best-window planner, docs. |
| packages/claude-code-plugin | Claude Code plugin tree (8 /ebb-ai: slash commands + auto-invocation skill + MCP wiring). |
| packages/openclaw-plugin | OpenClaw plugin (@vitalini/ebb-ai on ClawHub). Native OpenClaw tools mirroring the MCP surface. |
| docs/spec | Upstream MCP spec proposal for priority, deadline, carbon_budget fields. |

claude plugin marketplace add Vitalini/ebb-ai
claude plugin install ebb-ai

> /ebb-ai:defer "Summarize today's GitHub notifications" --by 4h
Deferred ✓ 38% cleaner than now, scheduled for 22:15 UTC, est. 0.34 g CO2e
> /ebb-ai:check

2 tasks queued · oldest in 1h · cleanest at 03:00 UTC

npm install -g @ebb-ai/mcp     # or run via npx -y @ebb-ai/mcp

{
  "mcpServers": {
    "ebb-ai": {
      "command": "npx",
      "args": ["-y", "@ebb-ai/mcp"],
      "env": {
        "EBB_ELECTRICITY_MAPS_API_KEY": "optional; falls back to mock data without it. GB is always live via the free UK Carbon Intensity API."
      }
    }
  }
}

import { defer } from "@ebb-ai/core";
const result = await defer(

  () => anthropic.messages.create({ / … */ }),

  {

    deadline: "2026-05-13T08:00:00-04:00",

    carbonBudgetG: 5,

    region: "US-CAL-CISO",

  },

);

With a provider adapter and the Batch API (v0.2)

import { Scheduler, AnthropicAdapter } from "@ebb-ai/core";
const scheduler = new Scheduler({ dbPath: "/var/lib/ebb/queue.sqlite" });

const adapter = new AnthropicAdapter();
await scheduler.defer(

  () => adapter.dispatch("claude-sonnet-4-5", "Summarize today's git commits."),

  { deadline: "2026-05-13T08:00:00-04:00", region: "US-CAL-CISO" },

);
// or — submit 100 prompts via Anthropic Message Batches for a 50% discount:

const handle = await adapter.dispatchBatch("claude-sonnet-4-5", prompts);

console.log(handle.batchId);

The SQLite-backed queue is opt-in via dbPath; without it the
scheduler runs in-memory as in v0.1. The Anthropic and OpenAI SDKs are
peer dependencies — install them only if you use the corresponding
adapter.

Python

pip install -e "packages/core-py[anthropic,openai]"

import asyncio
from ebb_ai import defer
asyncio.run(defer(

    lambda: do_work(),

    deadline="2026-05-13T08:00:00-04:00",

    carbon_budget_g=5,

    region="US-CAL-CISO",

))

Dashboard

```bash
pnpm --filter @ebb-ai/web dev