ebb-ai — carbon-aware MCP scheduler

MCPAI代理

提供方 Vitalini · 包名 @ebb-ai/mcp

AI代理 stdio · 本地进程 API Key 社区 / 第三方 Claude DesktopClaudeCursorWindsurf
查看接入方式

Open-source MCP server that defers non-urgent LLM tasks to the cleanest electricity-grid hour inside a deadline. When the user says "do this later", "by tomorrow", "overnight", "by EOD", "no rush" — the agent auto-routes the task through schedule_task and the MCP picks the cleane

一句话选型结论

按资料字段整理

ebb-ai — carbon-aware MCP scheduler 属于AI代理类 MCP 服务器,stdio · 本地进程,API Key,可直接接入 Claude Desktop、Claude、Cursor 等,有可直接执行的安装命令。接入前先确认权限范围;涉及写入、删除或付款的操作,建议先在测试环境验证。

分类AI代理 传输方式stdio · 本地进程 鉴权API Key 部署方式本地部署
GitHub 星标 未标注 仓库热度,无公开仓库时显示未标注
工具数 未标注 暴露给模型的工具数量
资源 / 提示词 0 / 0 资源与提示词模板数量
维护方 社区 / 第三方 核验等级 仅资料核对

工具与能力

AI代理
数量来自来源目录的标注,具体工具清单以官方文档为准
工具数量未标注暴露给模型可调用的工具个数
资源数量0可读取的资源条目
提示词数量0内置提示词模板数量

能力标签

scheduler claude code openclaw sustainability mcp anthropic openai

支持客户端

适用场景

schedulerclaude codeopenclaw

安装与配置

stdio · 本地进程 API Key
客户端在本机拉起子进程,数据不出本机
npx -y @ebb-ai/mcp

这条命令只是入口,具体启动参数请按官方文档补齐,不要直接照搬到别的服务器。

  1. 1
    准备运行环境

    stdio 服务在本地起进程,需要先装好 Cross-platform,再按安装命令拉取依赖。

  2. 2
    安装服务

    复制上面的安装命令执行;命令里带占位符的位置,换成自己的密钥或路径。

  3. 3
    写入客户端配置

    在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,让新配置生效。

  4. 4
    验证是否可用

    连接成功后随便调一个只读工具,确认能返回结果,再接入正式流程。

典型使用场景

3 类
按分类与标签整理的常见用法,具体以官方文档为准
给代理接外部能力

让代理在任务中途调用搜索、数据库等真实工具。

多步任务编排

把一串操作拆成步骤,由代理按顺序执行。

自动化重复流程

把固定流程交给代理跑,减少手工操作。

选择建议

选之前先看这几条
按条目字段给出的判断,不替你决定用不用

值得选的地方

  • 有现成的安装命令,不用自己找入口,照着跑就能起服务。
  • 已适配 Claude Desktop、Claude、Cursor,换客户端不用重新研究配置。

先想清楚的地方

  • stdio 方式要求本地装好运行时(如 Node.js),换机器要重新装一遍。
  • 使用前要准备好API Key对应的凭据,并按最小权限配置。
  • 资料没标注工具数量,实际能力要装好后确认。
  • 版本更新与行为细节以官方仓库为准。

更适合

  • 需要在AI代理场景里让模型直接调用外部能力的人。
  • 已经在用 Claude Desktop、Claude 的用户,接入路径最短。
  • 想先快速试一下、能接受在本地或自有环境跑服务的人。

不太适合

  • 完全不想在本地装环境的人。
  • 不方便管理密钥或第三方授权的人。
  • 需要厂商级 SLA 和技术支持的生产环境。

同类对比

6 个同类
同分类里挑最接近的几条,字段以各自详情页为准
MCP 服务器工具数传输方式部署方式安装命令最后核验
ebb-ai — carbon-aware MCP scheduler当前 未标注 stdio · 本地进程 本地部署 有 未标注
Filesystem 560c4363 13 未标注 本地部署 无 2026-05-17
Server Everything (everything) 11 stdio · 本地进程 本地部署 有 2026-05-17
Time 7365cb6d 2 SSE · 服务端推送 远程部署 有 2026-05-18
Everything Claude Code 未标注 stdio · 本地进程 本地部署 有 2026-05-17
Openmemory 557e1585 未标注 stdio · 本地进程 本地部署 有 2026-05-17

服务器档案

AI代理
字段来自项目仓库与公开索引,中文说明由本站标注
提供方Vitalini上游标注的维护方 Vitalini
分类AI代理本站按上游分类展示
连接方式stdio · 本地进程客户端在本机拉起子进程,数据不出本机
鉴权方式API Key远程服务建议用最小权限凭据
维护方社区 / 第三方核验等级 仅资料核对
包名 / 运行时@ebb-ai/mcp · Cross-platform本地安装时用到的包标识与运行时
部署类型本地部署上游给出的部署形态
最近核验未标注上游最后核验时间

详细介绍

46.7 KB
来自项目仓库与上游目录的原文,未做删改

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 very_clean (forecast value on 2026-10-15; yours will differ)python
    import asyncio; from datetime import datetime, timedelta, timezone
    from tidegap import recommend_window, uk_carbon_intensity_feed
    deadline = datetime.now(timezone.utc) + timedelta(hours=24)
    plan = asyncio.run(recommend_window(region="GB", deadline=deadline, feed=uk_carbon_intensity_feed(), rng=lambda: 0))
    print(plan.scheduled_for, plan.intensity_g_co2_per_kwh, plan.band)

2026-10-16T11:00:00.000Z 66 very_clean (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 `recommend_window` and `schedule_task` (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`.

| What you have from 0.17 | What happens on 0.19 | What you do |
|---|---|---|
| Ledger, key and config in `~/.ebb-ai/` | Not read since 0.19; one stderr line names `~/.ebb-ai`. 0.18 moved it to `~/.tidegap/` and left a link | Before 0.19: run any 0.18 command once. After: stop tidegap, move `~/.tidegap` aside, rename `~/.ebb-ai` to `~/.tidegap` |
| `EBB_*` variables (shell, MCP host config) | Not read since 0.19; one stderr line names each one | Rename them to `TIDEGAP_*` |
| `EBB_*` keys in `~/.tidegap/config` | Not read since 0.19; one stderr line names each one | Rename the keys to `TIDEGAP_*` |
| Secrets in `~/.config/ebb/env` | Not read since 0.19; one stderr line names the file. 0.18 `tidegap install` copied it to `~/.config/tidegap/env` | Move it to `~/.config/tidegap/env` and rename its `EBB_*` keys to `TIDEGAP_*` |
| Daemon `com.ebb-ai.tick` / `ebb-tick.timer` | Keeps running while `@ebb-ai/cli` is installed | `npm i -g @tidegap/cli` (uninstall `@ebb-ai/cli` first if npm reports `EEXIST`), `tidegap install`, run the unload commands it prints, then `npm uninstall -g @ebb-ai/cli` |
| `ebb `, `ebb-mcp` | Removed in 0.19 | Use `tidegap `, `tidegap-mcp` |
| `npx -y @ebb-ai/mcp` in a host config | Runs a 0.17.1 shim that starts `@tidegap/mcp` | Switch to `npx -y @tidegap/mcp` under the key `tidegap` (tools become `mcp__tidegap__*`) |
| Claude Code plugin `ebb-ai@ebb-ai`, `/ebb-ai:*` commands | No in-place update: the marketplace and plugin names changed | `claude plugin uninstall ebb-ai`, `claude plugin marketplace remove ebb-ai`, `claude plugin marketplace add tidegap/tidegap`, `claude plugin install tidegap`; then use `/tidegap:*` |
| OpenClaw `clawhub:@vitalini/ebb`, config `plugins.entries.ebb` | The old plugin stays on 0.17; the new plugin id is `tidegap` | `openclaw plugins install clawhub:@vitalini/tidegap`, move your config block to `plugins.entries.tidegap`, remove the old plugin |
| `pip install ebb-ai`, `import ebb_ai` | A 0.17.1 shim installs `tidegap`; the old import works with a warning | `pip install tidegap`, `import tidegap` |
| Links to `github.com/Vitalini/ebb-ai` and `www.ebb-ai.com` | GitHub redirects; the site redirects to `www.tidegap.com` | Nothing |

## Why defer non-urgent AI work?

US data centers are projected to consume 6.7–12% of national electricity
grid load by 2028 (DOE 2024), driven primarily by AI compute.
Most agent workload that lands on that load is *deferrable* (overnight
summaries, batch analyses, scheduled compliance scans, multi-step
report generation) — agent code just dispatches it synchronously by
default. `tidegap` makes the choice automatic. Four parallel wins:

1. **Lighter on the grid.** Spreads load away from peak hours, which is
   what ISOs and grid operators want from large compute users.
2. **50% cheaper (projected, Batch API list price).** Auto-routes
   through Anthropic and OpenAI Batch APIs (24-hour SLA) when the
   deadline allows. Same prompt, half the bill.
3. **Faster at off-peak.** Anthropic explicitly expanded off-peak
   capacity in 2026 (rate-limit policy)
   — doubled usage limits outside peak hours, citing smoothed demand.
   Sync calls observe shorter queues.
4. **Lower carbon.** Dispatch lands in the cleanest grid hour inside
   the deadline; the saving depends on region and day (see
   docs/claims.md). Per-task carbon receipts against the actual
   grid intensity used at dispatch, persisted to a local SQLite ledger.
   Auditable, region-aware, reproducible. v0.10+ uses per-model Wh/token
   coefficients (Patterson 2021, Luccioni 2024, Hugging Face AI Energy
   Score) so receipts reflect what the agent actually ran — not a flat
   placeholder. v0.11+ signs every receipt with Ed25519 so consumers can
   verify them offline via `tidegap verify` (B2B ESG export path).

`tidegap` is the same code that would have fired a sync LLM call —
now deferred to the cleanest, cheapest, fastest hour inside the
deadline. Apache-2.0.

A real run, excerpted (GB, 2026-09-30T21:03:30Z, live National Grid ESO
feed, local Ollama `llama3.2:1b`; raw output and reproducer in
`docs/examples/2026-09-30-GB-tick/`):```console
$ bash docs/examples/2026-09-30-GB-tick/command.sh
forecast source: ukCarbonIntensity (forecast)
forecast now:  2026-09-30T21:00:00.000Z  158 gCO2/kWh
forecast peak: 2026-10-01T17:00:00.000Z  183 gCO2/kWh

recommendWindow({ region: "GB", model: "llama3.2:1b", ... }):
  "scheduledFor": "2026-10-02T09:00:00.000Z",
  "intensityGCo2PerKwh": 88,
  "band": "very_clean",

$ tidegap tick --db <temp> --region GB
tick: 1 inspected, 1 dispatched, 0 failed

$ tidegap verify t-ef2354ee-eff0-431c-b11e-6edfcb8299b0 --db <temp>
✓ VALID
intensity_g_kwh   158
grid_source       ukCarbonIntensity
signer_public_key tTpsWuAS52easY0sgqz5E42aen7tdE5otdfLN6F+kxg=
UTC hour Carbon intensity
Forecast peak 2026-10-01T17:00 183 gCO2/kWh
Recommended window (72h deadline) 2026-10-02T09:00 88 gCO2/kWh

(forecast (projected), one GB run, 2026-09-30 — 88 vs 183 gCO2/kWh is
~52% lower for this run only; not a general or typical figure. The
158 gCO2/kWh the receipt records at dispatch is the measured value. See
docs/claims.md.)

Price: not available for this run. Tidegap has no electricity-price feed, and
its sync vs Batch list-price comparison needs at least two candidate models;
this run used one unpriced local Ollama model.

recommendWindow() 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.19.0 (this release) · 2026-10-17 · published on npm and PyPI
> · @tidegap/{core,mcp,cli} on npm under the
> @tidegap org; tidegap on PyPI; @vitalini/tidegap OpenClaw
> plugin on ClawHub (openclaw plugins install clawhub:@vitalini/tidegap),
> not npm, and shares the queue. One-command Claude Code plugin
> via /plugin marketplace add tidegap/tidegap && /plugin install tidegap.
> Five real-data grid feeds across 31 regions (NA/EU/APAC)
> — measured against the code, see docs/claims.md:
> 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 / ES / IT / NL / …, free with
> token), WattTime v3 marginal-emissions forecasts (US ISOs, free with
> account — takes precedence over EIA where covered), and Electricity Maps
> as universal fallback. v0.10:
> per-model Wh/token coefficients across 59 LLMs (measured, count grows
> with each catalogue refresh; Patterson 2021,
> Luccioni 2024, HF AI Energy Score) replace the v0.1–v0.9 flat
> placeholder. v0.11: Ed25519-signed carbon receipts (offline
> verifiable via tidegap verify) plus WAL multi-writer SQLite so
> tidegap tick and the MCP server can share ~/.tidegap/queue.db.
> v0.12 ("trust repairs"): Batch API routing is real — deferrable
> tasks (deadline > 24h) are submitted to the provider's Batch API and
> polled to completion (submitted status), instead of the previous
> dead-code gate; receipts record grid-data provenance (intensity, feed
> source — synthetic mock is disclosed, not silently signed) and the
> energy-coefficient confidence tier; Python- and TS-signed receipts
> verify in either language (one canonical signing form, JCS numbers);
> daemons installed by tidegap install actually dispatch (real
> node/script paths, ~/.config/tidegap/env secrets); hardened ledger
> (0600, redacted body_json); honest feed labeling
> (forecast vs persistence). Anthropic + OpenAI Batch adapters, Python
> port at parity, live dashboard, recommend_window planning endpoint,
> always-on tidegap tick CLI with macOS launchd + Linux systemd +
> pmset/rtcwake wake events, full control surface (cancel_task /
> expedite_task / update_deadline / retry_task / cancel_all),
> receipt redaction, file output, retry-with-backoff. 3,367 automated tests (1183 core-ts + 1207 cli + 130 mcp-server + 107 openclaw-plugin + 116 extension + 15 web + 609 core-py) across 7 packages. See QUICKSTART.md.

Live demo

Or visit the maintainer-hosted dashboard at
www.tidegap.com to see live grid-load and
carbon-intensity forecasts across 31 grid regions (NA / EU / APAC —
CAISO, ERCOT, ISO-NE, PJM, Great Britain, France, Germany, and more)
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); US ISOs use WattTime v3 marginal-emissions
forecasts when a WattTime account is configured (falling through to the
EIA open-data feed otherwise), EU zones ENTSO-E, with Electricity Maps as
the universal fallback and a clearly-labelled deterministic mock when no
key is configured.


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 (projected, provider list price)
    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.
    tidegap 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
    swings substantially over a single day as generation mix shifts.
    The same dispatch decision that saves cost and smooths load also
    emits less CO₂. tidegap writes an
    auditable receipt for every dispatch — useful for ESG reporting,
    cost-accounting, and upcoming compute-disclosure regulations.

tidegap automates the choice for any task that is not "answer me
right now."


Components

Package Purpose
@tidegap/core TypeScript core library. defer() API, AnthropicAdapter, OpenAIAdapter, GeminiAdapter, OllamaAdapter, opt-in SQLite-backed durable queue, per-model energy coefficients (estimateEnergyKwh, MODEL_ENERGY_COEFFICIENTS).
@tidegap/mcp Model Context Protocol server. Drop-in for Claude Desktop, Claude Code, OpenClaw, Cursor. schedule_task with repeat creates a recurring job that runs at the cleanest hour of each period.
tidegap (Python) Python 3.11+ port. asyncio scheduler, aiosqlite persistence, Anthropic + OpenAI + Gemini + Ollama adapters, mirrored tidegap.energy module.
apps/web Next.js 15 website at https://www.tidegap.com — install picker (12 hosts), live carbon-intensity map, best-window planner, docs.
packages/claude-code-plugin Claude Code plugin tree (8 /tidegap:* slash commands + auto-invocation skill + MCP wiring).
packages/openclaw-plugin OpenClaw plugin (@vitalini/tidegap-ai on ClawHub). Native OpenClaw tools mirroring the MCP surface.
docs/spec Upstream MCP spec proposal for priority, deadline, carbon_budget fields.

Architecture

The MCP server is a thin stdio process the agent host (Claude Code,
Claude Desktop, Cursor, Cline, Zed, OpenClaw) spawns. It enqueues
work to a SQLite-backed queue at ~/.tidegap/queue.db; an off-process
tidegap tick daemon (launchd / systemd / cron) reads scheduled rows
and dispatches them to the LLM provider at the chosen window. The
grid feed is a side-channel — the router picks per-zone between four
real-data sources before falling back to mock.

Quick start

See QUICKSTART.md — four steps, five minutes.

As a Claude Code plugin (one-command install)```bash

claude plugin marketplace add tidegap/tidegap
claude plugin install tidegap


That ships ten slash commands (`/tidegap:defer`, `/tidegap:plan`,
`/tidegap:check`, `/tidegap:cancel`, `/tidegap:expedite`, `/tidegap:reschedule`,
`/tidegap:retry`, `/tidegap:grid`, `/tidegap:later`, `/tidegap:usage`), an `tidegap` skill, and auto-wires the
`@tidegap/mcp` MCP server. Full plugin reference: **`packages/claude-code-plugin/README.md`**.```
> /tidegap:defer "Summarize today's GitHub notifications" --by 4h
Deferred ✓ scheduled for 22:15 UTC (cleanest window inside the deadline)

> /tidegap:check
2 tasks queued · oldest in 1h · cleanest at 03:00 UTC

Full command surface: /tidegap:{defer, plan, check, cancel, expedite, reschedule, retry, grid}. Tasks persist to ~/.tidegap/queue.db and
survive Claude Code restarts.

As an MCP server (Claude Desktop / Cursor / Cline / Zed)```bash

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


Then add to Claude Desktop's MCP config
(`~/Library/Application Support/Claude/claude_desktop_config.json` on
macOS):```json
{
  "mcpServers": {
    "tidegap": {
      "command": "npx",
      "args": ["-y", "@tidegap/mcp"],
      "env": {
        "TIDEGAP_ELECTRICITY_MAPS_API_KEY": "optional; falls back to mock data without it. GB is always live via the free UK Carbon Intensity API.",
        "TIDEGAP_EIA_API_KEY": "optional; US ISO fuel-mix (average) intensity.",
        "TIDEGAP_ENTSOE_SECURITY_TOKEN": "optional; EU zone intensity.",
        "WATTTIME_USERNAME": "optional; with WATTTIME_PASSWORD, enables WattTime v3 marginal-emissions forecasts for US ISOs (takes precedence over EIA where covered).",
        "WATTTIME_PASSWORD": "optional; pairs with WATTTIME_USERNAME."
      }
    }
  }
}

The MCP server exposes twelve tools to the agent (measured, toolsForHost("mcp") in
packages/core-ts/src/tool-surface.ts):

  • get_grid_forecast(region, hours?) — returns the next N hours of
    carbon intensity for a grid region (e.g. US-CAL-CISO).
  • recommend_window(deadline, region?, ...) — plans the cleanest window
    inside the deadline without queueing anything.
  • schedule_task(prompt, deadline, model?, carbon_budget_g?) — queues a
    task for execution at the cleanest window inside the deadline;
    deadline_kind: "quota_reset" sets the deadline to the next configured
    quota reset minus a margin.
  • check_queue_status(task_id?) — lists pending tasks and any
    completed receipts; viewing one finished task marks it read.
  • cancel_task, expedite_task, update_deadline, retry_task,
    cancel_all — control a queued task (or the whole queue).
  • reply_task(task_id, text) — continue a completed task as a new task.

As a library```typescript

import { defer } from "@tidegap/core";

const result = await defer(
() => anthropic.messages.create({ / … / }),
{
deadline: new Date(Date.now() + 12 * 3600 * 1000).toISOString(), // 12 h from now
carbonBudgetG: 5,
region: "US-CAL-CISO",
},
);


### With a provider adapter and the Batch API (v0.2)```typescript
import { Scheduler, AnthropicAdapter } from "@tidegap/core";

const scheduler = new Scheduler({ dbPath: "/var/lib/tidegap/queue.sqlite" });
const adapter = new AnthropicAdapter();

await scheduler.defer(
  () => adapter.dispatch("claude-sonnet-5", "Summarize today's git commits."),
  { deadline: new Date(Date.now() + 12 * 3600 * 1000).toISOString(), region: "US-CAL-CISO" },
);

// or — submit 100 prompts via Anthropic Message Batches for a 50% discount:
const handle = await adapter.dispatchBatch("claude-sonnet-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.

Run through your Claude Code subscription

tidegap tick can run tasks through the local claude CLI. It uses your Claude Code subscription quota and login, so you need no API key.

Requirements. Install Claude Code and log in once (claude, then /login) as the user who runs the tick daemon. If a task fails with an "unknown option" message, update Claude Code.

Which tasks use it.

  • A task with provider: "claude-code" always runs through Claude Code. schedule_task (MCP) and quick add in tidegap ui accept this provider. The OpenClaw plugin does not.
  • A task that schedule_task queues from a Claude Code session gets provider: "claude-code" when the call names no provider, and runs in a copy of that session (see "Run in the session that asked" below).
  • An anthropic task runs through Claude Code when ANTHROPIC_API_KEY is not set. When the key is set, it uses the Anthropic API as before.
  • openai, gemini and ollama tasks never run through Claude Code. When the tick finds Claude Code and one of these tasks is due without its key, the task fails with "no adapter configured" and does not wait.

How the tick finds claude. First TIDEGAP_CLAUDE_BIN, then each directory on PATH, then ~/.local/bin, ~/.claude/local, /opt/homebrew/bin and /usr/local/bin. On macOS, as a last step, it asks your login shell (zsh -ilc 'command -v claude'). It does this only when a pending task needs Claude Code. This step finds claude under launchd, whose PATH does not include ~/.local/bin.

What a run can do. The tick runs:```bash
claude -p --output-format json --tools "WebSearch,WebFetch" \
--allowedTools "WebSearch,WebFetch" --permission-mode dontAsk \
--max-budget-usd 1 --safe-mode --strict-mcp-config --no-session-persistence \
[--model <model>] [--system-prompt-file <file>]


- The prompt goes on stdin, so it does not show in `ps`.
- `--tools` and `--allowedTools` name the same tools. `--permission-mode dontAsk` denies every other tool. By default the model can search the web and fetch pages, and nothing else.
- `--safe-mode` and `--strict-mcp-config` turn off your CLAUDE.md, skills, plugins, hooks and MCP servers.
- The run happens in a new temporary directory, never in your repository, and the tick deletes the directory after the run.
- `--no-session-persistence` keeps these runs out of your Claude Code session history.
- The child process does not get `ANTHROPIC_API_KEY` or `ANTHROPIC_AUTH_TOKEN`, so it uses your subscription login. It also does not get your other provider keys, the WattTime login or any `TIDEGAP_*` variable.
- The tick runs a `claude` it finds on `PATH` or in a known location only when neither the file nor its directory is world-writable.
- A run that takes more than 10 minutes is stopped, together with every process it started, and the task fails.

**Tools.** A run gets `WebSearch` and `WebFetch` by default, so a task such as &quot;what is the weather forecast for Kyiv tomorrow&quot; gets a real answer. To change the set for one task, pass `tools` (an array of tool names) to `schedule_task` or `POST /api/tasks`; `[]` means no tools, and a reply keeps the tools of its parent. To change the default, set `TIDEGAP_CLAUDE_TOOLS` (a comma list; an empty value means no tools). Only `WebSearch`, `WebFetch`, `Read`, `Grep` and `Glob` are allowed. Any other name, such as `Bash`, `Write` or `Edit`, is rejected when you queue the task. Web pages are untrusted input: a page can contain text that tries to give the model instructions (prompt injection). For this reason a run never gets a tool that runs commands or writes files. `Read`, `Grep` and `Glob` can read files that your user can read, so add them only for prompts you trust. A set cannot combine a file tool with a web tool, because a fetched page could make the run send a local file out. The receipt records the tool set of the run, and `tidegap queue show ` prints it as `tools:`.

**Model.** The tick passes the task&#x27;s `model` to `--model` when it is a `claude-*` id or one of `opus`, `sonnet`, `haiku`, `fable`, `opusplan` (optionally with `[1m]`). Otherwise Claude Code uses its own default. A `claude-code` task queued without a model gets `&quot;default&quot;`. The receipt records the model that Claude Code reports. `maxTokens` and `temperature` have no effect, because the CLI has no flags for them.

**Settings** (environment or `~/.config/tidegap/env`):

| Variable | Effect |
|---|---|
| `TIDEGAP_CLAUDE_BIN` | Path of the `claude` binary. Skips the lookup. |
| `TIDEGAP_CLAUDE_CODE=0` | Do not look for Claude Code (`false`, `off` and `no` also work). |
| `TIDEGAP_CLAUDE_CODE_MAX_BUDGET_USD` | `--max-budget-usd` cap per run. Default `1`. An invalid value falls back to `1` with a warning. |
| `TIDEGAP_CLAUDE_TOOLS` | Default tool set, a comma list from the allowlist. Default `WebSearch,WebFetch`; an empty value means no tools. An invalid value keeps the default with a warning. Tasks queued from a Claude Code session do not use it (see below). |
| `TIDEGAP_RESUME=off` | Run every task fresh, also a task queued from a Claude Code session (`0`, `false` and `no` also work). |
| `TIDEGAP_RESUME_MAX_TOKENS` | Context cap of a run that resumes a session. Default `150000`. A larger session runs fresh. |
| `TIDEGAP_CLAUDE_CODE_RESUME_MAX_BUDGET_USD` | `--max-budget-usd` cap of a run that resumes a session. Default `3`. |

**Cost and quota.** Tasks use the same Claude Code quota as your interactive sessions. A night of queued tasks can use up the limit you expect to have in the morning. Claude Code&#x27;s list-price estimate for each run is in `tidegap queue show  --raw` (`total_cost_usd`, next to `session_id`). Your subscription is not billed per run. The budget cap uses this estimate.

**Carbon receipt.** The receipt has provider `claude-code`. Its token count includes the system prompt that Claude Code adds to each run (about 3k tokens) when Claude Code writes it to the prompt cache. Cache reads are not counted. Thus a receipt can show more tokens than an API call with the same prompt. A run that uses several models, for example a subagent, is billed model by model, and the receipt lists each model&#x27;s tokens and grams in `models`.

**Usage limit.** A run that hits the subscription limit does not fail. The task goes back to the queue and does not start before the limit resets; then it runs at the cleanest hour. The reset time comes from your limit state (see &quot;Usage and limits&quot; below) when a window is used up, else from the time in Claude Code&#x27;s message, else one hour later. After the first limit result in a tick, the other due tasks wait for the same time without a run. A task fails with the limit message when the reset is more than 8 days after the task was queued. `tidegap tick` prints `N deferred until HH:MM`.

**Failures.** Any other failed run fails the task once, with no retry. The error names the cause:

- `claude` not found or not executable: install Claude Code or set `TIDEGAP_CLAUDE_BIN`.
- &quot;Not logged in&quot;: run `claude` once as this user and complete `/login`.
- Budget cap: `error_max_budget_usd`.
- Timeout: &quot;timed out after 600s&quot;.
- Any other exit: the exit code and the end of stderr.

`retry_task` and `expedite_task` do not run `claude-code` tasks: they dispatch inside the MCP server, which has no Claude Code adapter. They leave the task as it is and name `tidegap queue run-now `, which runs it on the next tick.

### Run in the session that asked

A task that you queue from a Claude Code session runs with that session&#x27;s conversation as context, in that session&#x27;s project directory. &quot;Review the diff in queue.ts tonight&quot; can then read the repository and knows what you discussed.

**How Tidegap knows the session.** The Claude Code plugin has a session hook. At each session start (also after `/clear` and `/resume`) it writes `~/.tidegap/sessions/claude-.json` (mode 0600) with the session id, the transcript path and the project directory, and it deletes the file when the session ends. When the agent calls `schedule_task`, the MCP server reads the file of the Claude Code process that runs it. Without the plugin, the server uses the session id from its environment, which does not change after `/clear`. A `/tidegap:defer` call passes the id directly. The server uses a passed id only when it names this process&#x27;s session (the hook file&#x27;s or the environment&#x27;s); another id is ignored, and the reply has a `warning:` line. The hook only takes a `claude` process that runs as you. When no session is found, the task runs as before.

**What runs.** At the clean hour, `tidegap tick` runs a copy (fork) of the session:```bash
cd &lt;project directory&gt; &amp;&amp; claude -p --output-format json --tools &quot;Read,Grep,Glob&quot; \
  --allowedTools &quot;Read(//&lt;project directory&gt;/**)&quot; --permission-mode dontAsk \
  --max-budget-usd 3 --safe-mode --strict-mcp-config \
  --resume &lt;session id&gt; --fork-session
  • The fork gets a new session id. Your session and its transcript do not change, so you can keep working in it while the task runs.
  • Resuming gives context, not permissions. The run can read files inside the project directory only. It never gets Bash, Write or Edit, so it answers with text (a plan, a diff in the reply) and does not change files.
  • The fork is kept, so you can open it: tidegap queue show prints open: cd &amp;&amp; claude --resume. Forks of -p runs do not show in the claude --resume picker; open them by id.
  • A reply to such a task runs in a copy of the session too when it comes from tidegap queue reply, the page, or that same session. A reply_task call from another session, or from OpenClaw, runs fresh.
  • A task that names tools keeps them. A task with WebSearch or WebFetch runs fresh, because session context and web tools together could send a local file out.

…(正文过长,页面只展示前面部分,完整内容见仓库)

常见问题

8 问
答案由本站依据条目字段整理,不引用上游原文
ebb-ai — carbon-aware MCP scheduler 怎么安装?

在客户端按下面的安装命令接入:npx -y @ebb-ai/mcp。对应的包名是 @ebb-ai/mcp。装完在客户端配置里引用同一个包或端点。

ebb-ai — carbon-aware MCP scheduler 怎么在 Claude Desktop、Claude、Cursor 里配置?

它的传输方式是stdio · 本地进程,在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,配置才会生效。

ebb-ai — carbon-aware MCP scheduler 收费吗?

本站不代收费用,也没有标注具体价格。是否收费取决于服务本身和背后的接口额度,正式使用前按官方说明确认。

ebb-ai — carbon-aware MCP scheduler 需要 API Key 吗?

资料标注需要API Key认证,使用前准备好对应凭据,并按最小权限配置。

ebb-ai — carbon-aware MCP scheduler 支持哪些客户端?

资料标注支持 Claude Desktop、Claude、Cursor、Windsurf、Cline、Codex;其他客户端只要能配置 MCP Server,也能用同样的命令或地址接入。

ebb-ai — carbon-aware MCP scheduler 能提供哪些能力?

资料显示能力标签包括 scheduler、claude code、openclaw、sustainability、mcp、anthropic。具体工具清单以官方文档为准。

ebb-ai — carbon-aware MCP scheduler 需要什么运行环境?

运行时为 Cross-platform;属于本地进程,需要在本机装好运行环境。

ebb-ai — carbon-aware MCP scheduler 是本地还是远程?

它是本地进程(stdio),由客户端在本机拉起。传输方式为stdio · 本地进程。

热门专题

按标签挑服务器
全部专题 →

服务器信息以作者仓库与官方文档为准;分类、传输方式与鉴权方式的中文说明为中文整理,最近核验 未标注。