docs
Everything you need to install + use ebb-ai.
Pick your AI host below, copy the command. Then call any of the eight slash commands (Claude Code) or nine MCP tools (every other host).
install
Pick your host
Universal — add ebb-mcp to any host that speaks Model Context Protocol.
npx -y @ebb-ai/mcpthen Wire this into your host's MCP config (the snippets for specific hosts are in the dropdown).
commands
Eight slash commands (Claude Code)
After installing the Claude Code plugin, these are available as/ebb-ai:<cmd>in any session. Identical CRUD over the task queue.
/ebb-ai:defer<prompt> [--by <when>] [--region <zone>] [--budget <g>]Queue a task to run at the cleanest grid hour inside the deadline. Returns task_id + scheduled UTC time + region.
/ebb-ai:plan<deadline> [--region <zone>] [--budget <g>]Preview what window the scheduler would pick — without queueing. Returns chosen hour, savings vs now, top-3 alternatives.
/ebb-ai:check[task_id] [--all]List all tasks (default) or get full detail + carbon receipt for one task. Read-only.
/ebb-ai:cancel<task_id>Cancel a queued or scheduled task. Idempotent — completed/failed/cancelled tasks return their existing status.
/ebb-ai:expedite<task_id>Dispatch a scheduled task immediately, bypassing the cleanest-window pick. Receipt is tagged intensitySource=expedited.
/ebb-ai:reschedule<task_id> <new_deadline>Re-score a task against a new deadline. Lets you extend (more window for clean hour) or compress (may exceed carbon budget).
/ebb-ai:retry<task_id>Re-dispatch a task currently in failed status. New receipt overwrites the old. No-op for non-failed tasks.
/ebb-ai:grid<zone> [--hours N]Show current carbon intensity + next-24h forecast for a region. Useful for deciding now-vs-wait without queueing.
mcp tools
Nine MCP tools (every host)
The same surface that powers the slash commands. Any MCP host can invoke these directly. Parameters are documented in each tool's JSON schema.
get_grid_forecastread-onlyHourly carbon-intensity forecast for a region (gCO2/kWh + band). Backs /ebb-ai:grid.
recommend_windowread-onlyCleanest in-deadline window + alternatives + savings vs now. Non-committal planning.
schedule_taskwritePersist a task to the SQLite queue with a deadline. Returns task_id. Backs /ebb-ai:defer.
check_queue_statusread-onlyList all tasks or detail for one (with receipt). Backs /ebb-ai:check.
cancel_taskwriteSet a task's status to cancelled. Idempotent.
expedite_taskwrite (dispatch)Dispatch immediately, bypassing the scheduled window. Requires a provider API key.
update_deadlinewriteRe-score a task against a new deadline. Backs /ebb-ai:reschedule.
retry_taskwrite (dispatch)Re-dispatch a failed task. Requires a provider API key. Backs /ebb-ai:retry.
cancel_allwriteCancel every non-terminal task at once. Useful for clearing a corrupted queue.
on-disk
Paths
~/.ebb-ai/queue.dbSQLite ledger — queue + carbon receipts. The CLI, MCP server, and dashboard all read this same file. Read-only from your agent; modifiable from the CLI.
~/.ebb-ai/telemetry.keyLocal-only 256-bit token + Ed25519 keypair for the (v0.9-planned) opt-in leaderboard. Never sent. Not generated until you opt in.
environment
Optional API keys
ebb-ai works without any keys (GB is always live via UK National Grid ESO; everything else falls back to a deterministic mock). Set these in your MCP host's env block to unlock live data for more regions.
EBB_EIA_API_KEYU.S. Energy Information Administration. Unlocks live data for the six US ISOs (CISO, ERCO, ISNE, MIDA-PJM, NY-NYIS, MIDW-MISO). Free at eia.gov/opendata/register.php.
EBB_ENTSOE_SECURITY_TOKENENTSO-E Transparency Platform. Unlocks live data for European zones (FR, DE, ES, IT, NL). Free at transparency.entsoe.eu.
EBB_ELECTRICITY_MAPS_API_KEYElectricity Maps free tier (100 req/day). Universal fallback for any other zone. Free at electricitymaps.com/free-tier-api.
ANTHROPIC_API_KEY · OPENAI_API_KEYRequired only if you want ebb-ai to actually dispatch provider calls (vs. just queueing them). Either is enough.
deeper