tidegap/tidegap

Run non-urgent LLM tasks at the cleanest grid hour before your deadline.
Tidegap takes the LLM tasks your agent does not need right now, runs them at the lowest-carbon grid hour before a deadline you set, and sends them through the provider Batch API when the deadline allows.
Picks the dispatch hour from a live 72-hour grid carbon-intensity forecast: 5 real-data feeds, 31 regions (measured, counted in code).
Routes work with a deadline over 24 hours through the Anthropic and OpenAI Batch APIs, at 50 % of the sync list price (projected, provider list price).
Writes a signed carbon receipt per task to a local SQLite ledger. tidegap verify checks it offline.
bash
npm install @tidegap/core # TypeScript / Node
pip install "tidegap[anthropic,openai,signing]" # Python 3.11+
claude plugin marketplace add tidegap/tidegap && claude plugin install tidegap # Claude Code
npx -y @tidegap/mcp # any other MCP host
ts
// save as plan.mjs, run: node plan.mjs (GB uses the free UK feed, no API key)
import { recommendWindow, ukCarbonIntensityFeed } from "@tidegap/core";
const deadline = new Date(Date.now() + 24 3600 1000).toISOString();
const plan = await recommendWindow({ region: "GB", deadline }, { feed: ukCarbonIntensityFeed(), rng: () => 0 });
console.log(plan.scheduledFor, plan.intensityGCo2PerKwh, plan.band);
// 2026-10-16T11:00:00.000Z 66 veryclean (forecast value on 2026-10-15; yours will differ)
python
import asyncio; from datetime import datetime, timedelta, timezone
from tidegap import recommendwindow, ukcarbonintensityfeed
deadline = datetime.now(timezone.utc) + timedelta(hours=24)
plan = asyncio.run(recommendwindow(region="GB", deadline=deadline, feed=ukcarbonintensityfeed(), rng=lambda: 0))
print(plan.scheduledfor, plan.intensitygco2perkwh, plan.band)
# 2026-10-16T11:00:00.000Z 66 veryclean (forecast value on 2026-10-15; yours will differ)
Without rng, Tidegap picks at random among the cleanest band of near-equal hours, so repeated runs spread load and can return different hours; an rng that returns 0 gives the strict minimum.
Proof: one real run (GB, 2026-09-30, live National Grid ESO forecast). Forecast peak 183 gCO2/kWh, recommended window 88 gCO2/kWh: about 52 % lower, for this run only (forecast, projected). The test task had a 5-minute deadline, so it ran at once; its signed receipt records 158 gCO2/kWh (measured). Raw output and reproducer · every number and its source
In an agent: in Claude Code, /tidegap:defer "Summarize today's notifications" --by 4h. In any other MCP host, the agent calls recommendwindow and scheduletask (12 MCP tools, 12 hosts — host configs).
## Renamed from Ebb AI
Until 0.17 this project was Ebb AI (@ebb-ai/, ebb-ai on PyPI, the ebb command). 0.18.0 renames it to Tidegap, because "Ebb" conflicts with an existing software trademark. Your queue, receipts, signing key and daemon keep working. The old names worked for one release (0.18) and were removed in 0.19. Coming from 0.17? Upgrade through 0.18 once before 0.19 (or move ~/.ebb-ai to ~/.tidegap by hand): 0.19 no longer moves the old data directory. If 0.19 already ran, stop tidegap, move ~/.tidegap aside, then rename ~/.ebb-ai to ~/.tidegap.