# Install Tidegap > **What this is.** Plain-text install instructions for the > open-source Tidegap MCP server (Apache-2.0). Safe to read end to end > before running anything. > > - Project: > - Site: > - License: Apache-2.0 Tidegap is a Model Context Protocol (MCP) server. It defers non-urgent AI tasks to the cleanest hour of the electricity grid inside a deadline. It does **not** require an account, never sends data to Tidegap's authors, and stores everything in a local SQLite file at `~/.tidegap/queue.db`. --- ## What the install does It registers a new MCP server with your agent host so that the agent gains twelve new tools (`schedule_task`, `recommend_window`, `get_grid_forecast`, `check_queue_status`, `cancel_task`, `cancel_all`, `update_deadline`, `expedite_task`, `retry_task`, `reply_task`). The MCP server binary is `@tidegap/mcp`, run via `npx`. No global install, no system changes outside the agent host's own config file. --- ## Pick the install path for the host you're in ### Claude Code ```text /plugin marketplace add tidegap/tidegap /plugin install tidegap ``` Restart the session. Eight `/tidegap:*` slash commands and the MCP server are wired automatically. ### OpenClaw ```text openclaw plugins install clawhub:@vitalini/tidegap ``` The plugin self-registers on startup; no config edit needed. ### OpenAI Codex CLI ```text codex mcp add tidegap -- npx -y @tidegap/mcp ``` Or add this table to `~/.codex/config.toml` by hand: ```toml [mcp_servers.tidegap] command = "npx" args = ["-y", "@tidegap/mcp"] ``` Start a new Codex session to load the server. ### Other MCP hosts Claude Desktop, Cursor, Windsurf, Cline, mcphost and any other host that reads an `mcpServers` JSON file take this entry. Add it to the host's MCP config file: ```json { "mcpServers": { "tidegap": { "command": "npx", "args": ["-y", "@tidegap/mcp"] } } } ``` Config file paths: | Host | Config path | | -------------- | -------------------------------------------------------------------------- | | Claude Desktop | `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) | | | `%APPDATA%\Claude\claude_desktop_config.json` (Windows) | | Cursor | `~/.cursor/mcp.json` | | Windsurf | `~/.codeium/windsurf/mcp_config.json` | | Cline | VS Code → command palette → "Cline: Open MCP Settings" | | mcphost | the file you pass to `mcphost --config ` | **Continue** reads YAML. Add this to `~/.continue/config.yaml`: ```yaml mcpServers: - name: Tidegap command: npx args: - -y - "@tidegap/mcp" ``` **Zed** uses `context_servers` in `~/.config/zed/settings.json`: ```json { "context_servers": { "tidegap": { "command": "npx", "args": ["-y", "@tidegap/mcp"] } } } ``` **Goose** reads `~/.config/goose/config.yaml`. Add this under `extensions:` (or run `goose configure` → Add Extension → Command-line, with the command `npx -y @tidegap/mcp`): ```yaml extensions: tidegap: enabled: true type: stdio name: tidegap cmd: npx args: ["-y", "@tidegap/mcp"] timeout: 300 ``` Restart the host after editing the config file. --- ## Run tasks on time The MCP server only queues tasks. A small daemon, `tidegap tick`, dispatches each task when its window arrives. **Without the daemon, tasks stay queued and never run.** Install the CLI and register the daemon: ```text npm install -g @tidegap/cli tidegap install --laptop ``` - `--laptop` also writes a helper that registers wake events, so a sleeping Mac wakes for a task (it needs one sudoers line, which the command output explains). Use `--server` on a machine that never sleeps. - `tidegap install` requires one of the two flags. - Without a global install: `npx -y @tidegap/cli install --laptop`. The daemon then runs the copy in the npx cache, so a global install is the stable choice. The command writes the daemon file and prints the line that loads it. Run that line: ```text # macOS (launchd) launchctl load ~/Library/LaunchAgents/com.tidegap.tick.plist # Linux (systemd, user unit) systemctl --user daemon-reload && systemctl --user enable --now tidegap-tick.timer ``` On Windows, `tidegap install` prints a ready-to-paste `schtasks` command instead. To dispatch due tasks once, by hand: `tidegap tick --once`. **Claude Code limits (optional).** Tidegap can start a task after the Claude Code limit resets. It reads the limits from Claude Code's status line, which means one edit to `~/.claude/settings.json`. Ask the user first, and run this only after their yes: ```text tidegap usage install-hook ``` An existing status line command is wrapped and keeps working; the old file is kept as `settings.json.tidegap.bak`. To see the change first: `tidegap usage install-hook --dry-run`. To undo it: `tidegap usage install-hook --remove`. --- ## Configure Everything is optional. With no keys, Tidegap uses a clearly labelled simulated grid curve, except GB, which is always live (UK National Grid ESO, no key). **Region.** `TIDEGAP_DEFAULT_REGION` sets the grid region when a tool call names none, for example `GB`, `DE`, `FR` or `US-CAL-CISO`. The region list is on . When it is unset, Tidegap guesses the region from the time zone and falls back to GB. **Grid feeds** (live data; each is free): | Variable | Feed | | -------------------------------------------- | -------------------------------------- | | `TIDEGAP_EIA_API_KEY` | U.S. EIA (CAISO, ERCOT, ISO-NE, PJM) | | `WATTTIME_USERNAME`, `WATTTIME_PASSWORD` | WattTime (U.S. marginal emissions) | | `TIDEGAP_ENTSOE_SECURITY_TOKEN` | ENTSO-E (European zones) | | `TIDEGAP_ELECTRICITY_MAPS_API_KEY` | Electricity Maps (fallback, any zone) | **Provider keys** (to dispatch tasks): `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY` or `GOOGLE_API_KEY`, and `OLLAMA_HOST` for a local Ollama. Where each value goes: - The daemon reads `~/.config/tidegap/env`, one `KEY=VALUE` per line. `tidegap install` creates the file with mode 0600. Put the provider keys and the grid keys there. - The MCP server reads only the environment its host gives it. Put `TIDEGAP_DEFAULT_REGION` and the grid keys in the host's `env` block, next to `command` and `args`: ```json { "mcpServers": { "tidegap": { "command": "npx", "args": ["-y", "@tidegap/mcp"], "env": { "TIDEGAP_DEFAULT_REGION": "GB" } } } } ``` Never print a key back to the user or write it to a log. --- ## Libraries To call the scheduler from your own code instead of an agent host: ```text npm install @tidegap/core pip install tidegap ``` The Python package needs Python 3.11 or later. It is a library only: it has no command-line entry point, so there is no `pipx` install. --- ## Optional: connect the Mac app or the browser extension Both talk only to `tidegap ui`, a local web page on `127.0.0.1` (port 47821 by default). It is a long-running server: start it in the background, and pass `--no-open` so it does not open a browser: ```text npx -y @tidegap/cli ui --no-open ``` - **Browser extension** (Chrome, Edge, Firefox): mint a client token with `npx -y @tidegap/cli clients add --name browser --kind extension`. The token is printed once: give it to the user to paste into the extension options, and do not log or store it. - **Tidegap for Mac** (menu bar app, includes the Safari extension): it runs the `tidegap` command itself, so install the CLI globally first with `npm install -g @tidegap/cli`. The app then starts `tidegap ui` and pairs itself on first launch. No token to copy. To see or remove paired clients: ```text npx -y @tidegap/cli clients list npx -y @tidegap/cli clients revoke ``` --- ## Confirm the install worked Once the host has restarted, ask the agent to call `schedule_task` with `dry_run: true`. A successful dry-run returns a chosen window and an estimated carbon figure, without persisting anything. ```json { "tool": "schedule_task", "args": { "prompt": "ping", "deadline": "<24h from now in ISO-8601>", "dry_run": true } } ``` If the agent sees the response, the MCP server works. Then check that the daemon is loaded: ```text # macOS launchctl list | grep com.tidegap.tick # Linux systemctl --user status tidegap-tick.timer ``` A line for `com.tidegap.tick` (macOS) or an `active` timer (Linux) means queued tasks will run on time. --- ## Troubleshooting - No Tidegap tools in the agent: restart the host after the config edit. - Tasks stay queued: the daemon is not loaded. See "Run tasks on time". - The forecast says mock or simulated: the region has no live feed without a key. See "Configure". - Upgrading from 0.17: read the upgrade note in the [CHANGELOG](https://github.com/tidegap/tidegap/blob/main/CHANGELOG.md#0190--2026-10-17). --- ## Then what The agent can now run: ```text /tidegap:defer "summarize today's commits" --by tomorrow 6pm ``` (or call `schedule_task` directly) and the task lands at the cleanest grid hour inside the deadline. Full docs and tool reference: Everything on one page, as plain text: --- # Tidegap docs The same content as , as plain markdown. ## Install Tidegap is an MCP server that runs your agent's non-urgent tasks at the cleanest grid hour before a deadline. Pick your host, copy one command, and restart the host. The full install instructions for every host are at the top of this file, and at . Agents can read the same steps as plain text at [/install.md](/install.md). ### Run the tick daemon The MCP server queues tasks but runs no clock. The CLI's tick sends due tasks to the provider. Install it once: ```bash npm install -g @tidegap/cli tidegap install --laptop # launchd job plus wake events (macOS) tidegap install --server # launchd job only ``` Without the daemon, tasks wait in the queue. Run one pass by hand with `tidegap tick --once`. ### Confirm it worked Run `tidegap status`. It says whether queued tasks will run: the daemon, the last tick, the runners and the pending tasks. It exits 1 when they will not. Then ask the agent to call `schedule_task` with `dry_run: true`. The reply shows a chosen window and an estimated carbon figure, and nothing is saved. ```json { "tool": "schedule_task", "args": { "prompt": "ping", "deadline": "<24h from now in ISO-8601>", "dry_run": true } } ``` ### Libraries Call the scheduler from your own code instead of an agent host: ```bash npm install @tidegap/core pip install tidegap # Python 3.11 or later, library only ``` ## Hosts Every MCP host runs the same server, `@tidegap/mcp`, through `npx`. Only the config file differs per host. The full install instructions for every host are at the top of this file, and at . ## CLI The `tidegap` CLI drains the queue, inspects tasks and receipts, and serves the local UI. Claude Code also gets slash commands for the same actions. ### Slash commands In Claude Code, after `/plugin install tidegap`: | Command | Arguments | What it does | | --- | --- | --- | | `/tidegap:defer` | ` [--by ] [--region ] [--budget ]` | Queue a task for the cleanest grid hour inside the deadline. | | `/tidegap:plan` | ` [--region ] [--budget ]` | Preview the window the scheduler would pick, without queueing. | | `/tidegap:check` | `[task_id] [--all]` | List tasks, or show one task with its carbon receipt. | | `/tidegap:cancel` | `` | Cancel a queued or scheduled task. | | `/tidegap:expedite` | `` | Send a scheduled task now, skipping its window. | | `/tidegap:reschedule` | ` ` | Score a task again against a new deadline. | | `/tidegap:retry` | `` | Run a failed task again, a command task included, as attempt 1 of a new count. | | `/tidegap:grid` | ` [--hours N]` | Show the carbon intensity now and the forecast for a region. | | `/tidegap:later` | ` ` | Run a queued task later: `1h`, `tonight`, `tomorrow_morning`, `after_limit_reset`, or an exact time. | | `/tidegap:usage` | `[--spend]` | Show the Claude Code 5-hour and weekly limit use. | ### Commands | Command | What it does | | --- | --- | | `tidegap tick` | Send due tasks to their provider. `--once` (default) or `--daemon --interval `. | | `tidegap install` | Add the OS tick job. `--laptop` adds wake events, `--server` does not. | | `tidegap status` | Will queued tasks run? Daemon, last tick, runners and pending tasks; exit 1 when not. `--json` prints the readiness object. | | `tidegap queue list` | List tasks. Filter with `--status`, `--unread`, `--series `, `--session ` (the tasks one Claude Code session queued); `--json` for scripts. | | `tidegap queue add ` | Queue one task and print its id on the first line: a prompt (`--runner claude-code\|anthropic\|openai\|gemini\|ollama`), or a shell command with `--runner command`. `--by ` is required (a duration, an ISO-8601 time or `quota-reset`). Also `--cwd`, `--profile read\|web\|none`, `--model`, `--result-path`, `--not-before`, `--after-limit-reset`, `--command-timeout`, `--llm-timeout` (the run's time limit, or `none`; see [Run limits](#limits)), `--retries` and `--retry-delay` (automatic retries of a failed run; `--retries 0` runs it once), `--wake` (wake this idle session when the task finishes), `--json`; `-` reads the text from stdin. Exit 2 on a usage error or a refused folder or path. See [Agent handoff](#handoff-queue). | | `tidegap queue show ` | Show the prompt (or a one-off's command), the runner, folder, profile, tools, result file, the result and the receipt. Marks a finished task read. | | `tidegap queue events ` | Print a task's events, oldest first, each with its id. `--after ` prints only newer ones; `--json` adds the task's status and timing. See [Agent handoff](#handoff-watch). | | `tidegap queue wait ` | Block until the task ends, and its result file is written when it asked for one, and print its result. Exit 0 completed, 1 failed, cancelled or result file not written, 2 usage, unknown id or unreadable ledger, 3 at `--timeout `. `--events` prints each new event to stderr. | | `tidegap queue notices` | Print the notice of this session's finished tasks and record that the session saw them. The plugin's prompt hook runs it with `--hook`; `--peek` only prints. The plugin's Stop hook runs `--wait --rewake`, which waits for a task queued with `--wake` and exits 2 with the notice on stderr. See [Wake an idle session](#handoff-wake). | | `tidegap queue cancel ` | Cancel a pending task. `--series` also ends a repeating series. | | `tidegap queue reschedule ` | Move a task: `--by `, `--at ` or `--day `. | | `tidegap queue later ` | Push a queued or scheduled task later; it never runs earlier than its planned start. `--until ` or `--preset `. | | `tidegap queue run-now ` | Mark a task due now. The next tick sends it. | | `tidegap queue retry ` | Retry a failed task, a command task included: it is due now, the next tick runs it as attempt 1 of a new count, and its deadline does not hold it back. A job run is refused: the job retries its runs itself. | | `tidegap queue reply ` | Queue a follow-up with the earlier conversation plus your text. | | `tidegap queue unread ` | Mark a task unread again, so it shows in the inbox. | | `tidegap receipts list` | List the receipts of completed tasks. `--since ` filters. | | `tidegap usage` | Claude subscription limits: 5-hour and weekly percent used and their resets; Codex limits. `--json`, `--spend` adds the current 5-hour window's tokens and cost estimate. | | `tidegap usage hook [command...]` | Claude Code statusLine command: records `rate_limits` to `~/.tidegap/usage.json`. After `--`, it runs your own statusline command. `usage install-hook` stores it guarded: the guard runs your own command itself with the same input, so a Tidegap that fails, moves or is removed never changes your status line (one that hangs still delays it). | | `tidegap usage install-hook` | Register the usage hook as the Claude Code statusLine in `~/.claude/settings.json`. Your own statusLine is wrapped and keeps working; the old file is kept as `settings.json.tidegap.bak`. `--dry-run` prints the state and the command it would store and writes nothing; `--remove` restores your own command. | | `tidegap limits show` / `set ` / `reset ` | `tidegap limits` alone shows too. The run limits in `~/.tidegap/config`: `command-timeout`, `llm-timeout`, `retries` and `retry-delay` (`--runner ` for one runner), with each value and its source, and the lines that are ignored. A time limit is a duration from 1s to 7d or `none`; retries are 0 to 10; a retry delay is a duration. See [Run limits](#limits). `--json` on `show`, `set` and `reset`. | | `tidegap region show` / `set ` / `detect` / `list` | The grid region every surface uses. `show` prints the zone, where it came from and its data source; `set` stores a supported zone in `~/.tidegap/config` (`set auto` clears it); `detect` prints the time-zone guess and stores nothing; `list` prints the supported zones. `--json` on each. | | `tidegap stats` | Show local impact stats from the ledger. | | `tidegap verify [task-id]` | Check a receipt signature. `--file ` for a receipt file. | | `tidegap register-wake ` | Add a macOS wake event 30 s before a task's window. | | `tidegap ui` | Open the local task page on 127.0.0.1. See [UI & apps](#apps). | | `tidegap channels add ` | Set up a notification channel in one step: it checks the values, sends a test message, then saves. Kinds: `webhook`, `slack`, `discord`, `ntfy`, `pushover`, `email`, `shortcuts` (macOS), `command`, and `telegram` (pairs a chat; see [Telegram](/docs#telegram)). Steps and fields per kind: [Notifications](/docs#notifications). Flags mirror the card's fields; secrets come from `--secrets-stdin` (one JSON object) or a hidden prompt, never from flags. | | `tidegap channels kinds` | List each kind's flags, secrets and presets on this computer. `--json` for JSON. | | `tidegap channels connect ` / `test ` / `disconnect ` | Connect again with the stored settings, send a test message, or stop sending and keep the settings. | | `tidegap channels set ` | Change the events (`--events task_done,task_failed,digest`; `digest` is the daily summary) and quiet hours (`--quiet night` or `off`). No test message. | | `tidegap channels digest` | Show the daily summary's send time and the channels that get it. `--at HH:MM` sets the local send time (default `09:00`, the end of quiet hours). | | `tidegap channels list` / `remove ` | List the channels with state, last delivery and target (secrets as hints only; `--json`), or remove one with its secrets. | | `tidegap channels serve` | Run the Telegram listener (the listener unit runs this). `--once` polls one cycle. | | `tidegap jobs list` / `show ` | Recurring jobs: list active and paused jobs (`--all` adds removed ones; `tidegap jobs` alone lists them too), or show one with its guarantee, next and last run. `--json` on each. | | `tidegap jobs add` / `edit ` | Create or change a job: a cadence (`--daily`, `--weekdays`, `--weekly mon,thu` or `--every 6h`), an optional `--window 00:00-08:00`, and `--prompt ` or `--command ` (with `--summarize ` for a tool-less LLM step and `--secret ` per secret). `--file ` reads the job from JSON. `edit` changes only the flags given. | | `tidegap jobs pause` / `resume` / `run` / `remove ` | Stop a job, start it again from now, run its next occurrence on the next tick, or end it (history stays). | | `tidegap jobs history ` | Past runs with their receipt ids, newest first. `--limit N`. | | `tidegap jobs secrets list` / `set ` / `remove ` | Secrets for command jobs, by name. `set` reads the value from stdin (a hidden prompt in a terminal); values are never printed. | | `tidegap jobs snippet [--host ]` | Print the block that makes a coding agent schedule recurring work through Tidegap instead of cron: the generic `AGENTS.md` block, or with `--host` (`claude`, `opencode`, `codex`, `cursor`, `gemini`) the files that host reads. `tidegap install` prints the generic block too. | | `tidegap clients add` / `list` / `revoke ` | Manage the tokens of the browser extension and the Mac app. | Every queue command takes `--db ` to use a ledger other than `~/.tidegap/queue.db`. ### Grid region `tidegap region` shows and sets the grid region that every surface uses. The rules and the zone list are in [Config](#region). | Command | What it does | | --- | --- | | `tidegap region show` | The zone, its name, where it came from (`flag`, `env`, `setting`, `timezone` or `fallback`) and its data source. A stored setting that an override hides is named too. | | `tidegap region set ` | Store a supported zone in `~/.tidegap/config` as `TIDEGAP_DEFAULT_REGION`. Any case; `UK` stores `GB`. The other lines of the file stay as they are. An unknown zone exits 2 with the closest zones and a request link. | | `tidegap region set auto` | Remove the stored zone, so the time-zone guess applies again. | | `tidegap region detect` | The time-zone guess alone. Stores nothing. | | `tidegap region list` | The supported zones with country, grid operator and data source. | Each command takes `--json`. `show --json` prints the same object as `GET /api/settings/region`, without `catalog`. ```text $ tidegap region set ua Unknown zone ua. Closest: PL. Request a region: https://github.com/tidegap/tidegap/issues/new?template=region_request.md&title=Region+request:+ua $ tidegap region set fr Region set to France (FR). FR France — stored setting (tidegap region set) Data: ENTSO-E (sample curve: add TIDEGAP_ENTSOE_SECURITY_TOKEN) ``` A running `tidegap ui`, tick daemon or Telegram listener uses the new zone on its next request or tick, with no restart. ## MCP tools Every MCP host gets the same tools. Each tool's JSON schema documents its parameters. | Tool | What it does | | --- | --- | | `get_grid_forecast` | Return the hour-by-hour grid carbon intensity forecast for one region, up to 72 hours ahead. | | `recommend_window` | Preview the cleanest run window before a task's deadline, without queuing it. | | `schedule_task` | Queue an AI task or recurring job to run at the cleanest grid hour before its deadline; long deadlines may use the provider Batch API. | | `check_queue_status` | Show the local queue and jobs: every task in brief or one in full. | | `tidegap_usage` | Report this machine's Claude Code limits: 5-hour and weekly percent used, reset times, and Codex limits if present. | | `cancel_task` | Cancel one task by task_id; for all pending, use cancel_all. | | `expedite_task` | Run one queued or scheduled task now, skipping its clean window. | | `update_deadline` | Change the deadline of one queued or scheduled task and re-pick its cleanest window inside it. | | `postpone_task` | Move one queued or scheduled task later; it never runs earlier than planned. | | `reply_task` | Send a follow-up message in a completed task's conversation, as a new queued task. | | `retry_task` | Run a failed task again, a command or claude-code task included, as attempt 1 of a new count. | | `cancel_all` | Cancel every queued and scheduled task in the local queue at once; for a single task use cancel_task. | ### Region in tool calls - On the MCP server, `get_grid_forecast` and `recommend_window` need a `region`. `schedule_task` takes it as an option. Without it, the task gets the default region: `TIDEGAP_DEFAULT_REGION` in the server's environment, then the stored setting (`tidegap region set`), then the time-zone guess, then `GB`. - The `schedule_task` reply has a `region_source:` line: `flag` (the argument), `env`, `setting`, `timezone` or `fallback`. - The MCP server reads `TIDEGAP_DEFAULT_REGION` only from its own process environment, which is the host's `env` block. It never reads `~/.config/tidegap/env`. It reads the stored setting again on each call, so `tidegap region set` needs no host restart. - A `region` outside the supported zones fails with the closest zones and a request link: `Unknown zone UA. Closest: PL. Request a region: `. With an Electricity Maps key, any other zone passes, except the ENTSO-E zone `IT`, which needs `TIDEGAP_ENTSOE_SECURITY_TOKEN`. - OpenClaw: `region` is optional on every tool that takes it. The plugin's `defaultRegion` takes the place of `TIDEGAP_DEFAULT_REGION` and reports `region_source: "config"`. The full rules and the zone list: [Grid region](#region). ### Recurring work in tool calls - `schedule_task` with `repeat` set to `daily`, `weekdays`, `weekly` or `every_n_hours` creates a [job](#jobs): each run is a new task with the same prompt, at the cleanest hour of its period. Set `every_hours`, `days`, `window` and `time_zone` to shape it. - A job takes prompts only. Command jobs are written by the user on the page or in the CLI, and a command argument is rejected. - `repeat: quota_reset` stays the older series that follows the quota reset. - `llm_timeout` sets the time limit of a task, or of each run of a job: a duration from 1s to 7d, such as `45m`, or `none`; `0` is refused. Without it the [run limits](#limits) setting applies. `check_queue_status` with a `task_id` shows each time limit and its source. On a task whose deadline is over 24 hours away and that may go to a provider Batch API, the reply notes that a Batch run applies no time limit. - `retries` (0 to 10) and `retry_delay` (a duration, doubling for each later retry) set how a failed run is tried again, for a task or each run of a job; without them the setting applies, else one retry after 30 minutes ([Retries](#retries)). `check_queue_status` shows the policy and one `attempt_` line per failed attempt that was tried again. Only the final outcome sends a notice. - `retry_task` runs a failed task again as attempt 1 of a new count. With the provider's key in the server env it runs the call now; a `command` or `claude-code` task, or one with no key there, is due now and the next `tidegap tick` runs it. A job run is refused. - `cancel_task` with `series: true` ends a job or a series. A cancel of a running task stops its command, `claude -p` run or API call. ### Handed-off work in tool calls - `schedule_task` on the MCP server takes the work shape of a task: `runner` (another name for `provider`; a call whose `runner` and `provider` differ is refused), `cwd` (the folder a `claude-code` run works in), `permission_profile` (`read`, `web` or `none`; `read` when only `cwd` is given) and `result_path` (a new file Tidegap writes the result text to). The reply adds `cwd:`, `profile:`, `tools:` and `result_path:` lines, and `check_queue_status` with a `task_id` shows them. - `runner` or `provider` `command` is refused, and nothing is queued: a shell command task is the user's call, and the reply names `tidegap queue add --runner command --cwd --by ''`. - `result_path` and `output_path` must be inside `cwd`, the session's project folder or the temp folder, in a folder that exists and is yours below that folder, with no name below that folder starting with `.`, and outside `~/.tidegap`, `~/.config`, `~/.claude`, `~/.ssh`, `~/.gnupg`, `~/.aws`, `~/Library` and `.git` folders (in any letter case and under any other name). The home folder and `/` never count as the session's project folder. A refusal names the allowed folders. `result_path` must be a new file; `output_path` may replace a regular file you own that has no second name. Both are checked again before the write. - `wake_session: true` wakes this Claude Code session when the task finishes, if it sits idle, within 12 hours after its last turn ended. The reply and `check_queue_status` add a `wake: on` line. It is refused outside a Claude Code session (also with an `origin_session_id` the server cannot check). A wake starts a model turn while nobody may be watching, so it is off by default; without it the notice comes with the next prompt. See [Wake an idle session](#handoff-wake). - A job repeat refuses `cwd`, `permission_profile`, `result_path` and `wake_session`, like the other per-task options. A series repeat (with `deadline_kind` `quota_reset`) refuses `result_path`: each run would write the same new file. The profiles, the folder rules and the result files: [Agent handoff](#handoff-queue). ## UI & apps `tidegap ui` is a local page for your queue: timeline, inbox, task detail and actions. The browser extension and the Mac app are clients of the same local server. ### tidegap ui ```bash npx -y @tidegap/cli ui # opens http://127.0.0.1:47821/ npx -y @tidegap/cli ui --no-open # prints the link only ``` - It listens on 127.0.0.1 only, on port 47821 unless that port is taken. `--port ` sets the port. - It never sends tasks to a provider. The tick does that. - While it runs, `~/.tidegap/ui.json` holds its port and pid, and no token. ### Settings → Grid region The **Grid region** card in Settings shows the zone in use, where it came from and its data source, for example "From time zone Europe/Kyiv." - Type in **Search** to narrow the **Region** list by zone code, name, country, grid operator or data source ("pol" finds Poland, "pjm" finds `US-MIDA-PJM`). Press **Save**. The page and its timeline use the new zone at once; the tick, the queue and the MCP server use it on their next tick or call. - **Auto (time zone)** in the list removes the stored zone, so the time-zone guess applies again. - When `tidegap ui --region` or `TIDEGAP_DEFAULT_REGION` sets the region, the card names the override and **Save** is off. The stored zone applies again when the override is removed. - When the guess is approximate (a Ukrainian time zone gives `PL`: "No Ukrainian grid data yet") or falls back to `GB`, the card shows a note and a **Request your region** link. The card is in the page and in the Mac app's Settings. The browser extension cannot change the region. The same setting from the terminal: [tidegap region](#cli-region). ### Settings → Run limits The **Run limits** card in Settings shows the four [run limits](#limits) in a table: one row for all runners and one per runner. Each cell shows the value a run gets now and where it comes from: set here, all runners, this runner, or the default. - Press **Edit** in a cell, type a duration (`90s`, `30m`, `1.5h`, `2d`) or a retry count, and press **Save**. A time limit also takes **No limit**, which stores `none`; the card then says that such a run holds every other due task while it runs. **Use default** removes the line, so the next layer applies. - A refused value shows the server's sentence under the cell. `0` is never a time limit: use **No limit**. - Lines of `~/.tidegap/config` that are not used show under the table, with the reason. The card is in the page and in the Mac app's Settings; the browser extension cannot change it. A change applies to the next run. The same settings from the terminal: `tidegap limits`. ### Retry a failed task A failed task that is no run of a job shows **Retry** in its detail and in the row's menu. The retry is due on the next tick, as attempt 1 of a new count, and ignores the deadline. A `command` task runs its command again, so the page shows the command and asks first. The detail lists each failed attempt of the current count, the next attempt time while a retry waits, and the task's time limits and retries with their sources. A job retries its own runs: use **Run now** on the job instead. ### Connect an app Apps use a client token. Mint one in the page ("Connect an app") or on the command line: ```bash tidegap clients add --name browser --kind extension ``` The token is printed once. `tidegap clients revoke ` stops it at once. ### Jobs view The **Jobs** tab of `tidegap ui` lists recurring jobs with their guarantee, the next and the last run. Open a job for its history, or create one with **New job**. A preview shows the guarantee and the first planned hour before you save. Deep links: `#/jobs`, `#/jobs/new`, `#/jobs/`. More: [Jobs](#jobs). ### Browser extension Preview. One extension for Chrome, Edge, Firefox and Safari: the queue and the next clean window in the toolbar. It never creates tasks. A Jobs section lists the jobs with **Pause**, **Resume** and **Run now**; **Manage jobs** opens the page. The extension cannot create or edit jobs. Build it from source and paste the client token in its options. Steps: [apps/extension/README.md](https://github.com/tidegap/tidegap/blob/main/apps/extension/README.md). ### Tidegap for Mac Preview. A menu bar app for macOS 14 or later, with the Safari extension inside. It runs the `tidegap` CLI, starts `tidegap ui` and pairs itself on first launch, so there is no token to copy. A Jobs submenu lists the jobs with Run now, Pause and Resume; **New job on page…** and **Edit on page…** open the Jobs page. On first launch the app offers once to start at login; the right-click menu and Settings > App turn it on or off. A "Task failed" notification for a task that can be retried has a **Retry** action, which queues the task for the next tick; a command task is retried from the window, which shows the command first. Install the CLI globally first. Steps: [apps/macos/README.md](https://github.com/tidegap/tidegap/blob/main/apps/macos/README.md). ### Client API Both apps use the API in [docs/spec/ui-client-api.md](https://github.com/tidegap/tidegap/blob/main/docs/spec/ui-client-api.md). Every `/api/*` request sends `Authorization: Bearer `. ## Notifications Tidegap can tell you when a task finishes, when a task fails, when a clean window starts and when queued tasks cannot run. It can also send one daily summary. Each place it sends to is a **channel**: Telegram, email, Slack, Discord, ntfy, Pushover, a webhook, a macOS Shortcut or a program on your computer. Desktop notifications (`os`) are built in and need no setup. Set up a channel in Settings → Integrations, in the page that `tidegap ui` opens or in the Mac app. Each kind has a card with "where to get this" steps, the fields it needs and one **Connect** button. Connect checks the fields, sends a test message, saves the settings and turns the channel on. The CLI does the same with `tidegap channels add ` (see [CLI](#notify-cli)). `tidegap tick` sends the messages. A channel works only while the tick runs (`tidegap install` sets it up; `tidegap status` tells you if it runs). ### Events and quiet hours A connected card shows the events as chips. Turn a chip off to stop that event for that channel. | Chip | Event | When it is sent | | --- | --- | --- | | Task finished | `task_done` | A task completed at this tick. | | Task failed | `task_failed` | A task failed at this tick. | | Clean window starts | `clean_window` | A clean window started (live forecast only, once per window). | | Tasks cannot run | `not_ready` | Queued tasks cannot run, for example no runner for a provider. Once per change. | | Daily summary | `digest` | Once a day. See [Daily summary](#notify-digest). | **Quiet at night (22:00–09:00)** holds every event but the daily summary during those local hours. A "tasks cannot run" alert that starts at night is sent after 09:00. A task finished at night is not sent on its own; turn on the daily summary to see it in the morning. ### Not ready The "tasks cannot run" alert (`not_ready`) is sent once per change. For the tick daemon, Tidegap counts only the time the computer was awake: | Cause | What you get | | --- | --- | | The computer slept between ticks | No alert. `tidegap status` says "Tasks will run" and notes "the tick daemon paused while the Mac slept (11:05–11:24)". | | No tick for more than two intervals (10 minutes) while awake | "Tidegap: the tick daemon is not running." Right after a sleep, one more interval is allowed. | | The daemon unit is missing or not loaded | The alert says: Run `tidegap install`. | | The unit is loaded but the tick stopped or failed | The alert gives the last exit code when launchd knows it and says: Run `tidegap tick --once` and check the error. | When the daemon runs again after an alert, the next tick the daemon starts sends one "Tidegap: the tick daemon is running again." It is sent only if the alert was sent. A `tidegap tick --once` you run yourself does not send it, because it does not show that the daemon runs. Quiet hours apply to it, and the daily summary does not replace it. `tidegap status` shows the same cause and advice. ### Daily summary The daily summary is one message a day. It goes to each channel with the **Daily summary** chip on. The default time is 09:00 local time, the end of the quiet hours. See or change it with `tidegap channels digest` and `tidegap channels digest --at 07:30`, or in Settings → Integrations: type the time in **Daily summary at** and press Save. The summary lists: - the tasks done, failed and postponed since the previous summary, at most 10 titles per group, then "and N more"; - the carbon of the done tasks; - the problems that still stop queued tasks; - the number of queued tasks and the next clean window. A day with nothing to report sends nothing. If the computer sleeps through the send time, the summary goes out at the next tick. One summary covers at most 48 hours, so a long sleep gives one summary, not several. If every send fails, the channel waits, then tries again (see [Failed sends](#notify-backoff)). The `last` value in `GET /api/integrations` is the time a summary last reached a channel. On a channel that gets the summary, an alert for something the summary lists is not sent again on its own. An alert held overnight arrives once, inside the summary. An alert for something the summary does not list still arrives after 09:00. If the summary fails on one channel and reaches another, the failed channel gets its alerts on their own. ### Failed sends A channel whose send fails waits before the next try: 1 minute, then 2, 4 and so on, at most 1 hour. While it waits, it gets no events. After the wait it gets the daily summary and a "tasks cannot run" alert, each only if no other channel got it, and a clean-window alert if the window is still open. A task finished during the wait gets no message of its own; the daily summary lists it. The card shows "Retrying in N min". A successful send, Connect or Send test ends the wait; a failed Send test does not. ### Test message Connect and **Send test** send one test message: "Test message from Tidegap. Notifications work." In the Tidegap JSON format (webhook and command) it has `"event": "test"`. Ignore that event in your own code, or use it to check the path. The result is the channel's last delivery: the card and `tidegap channels list` show its time and, on failure, its code. ### Telegram Telegram has its own page: [Telegram](#telegram). It pairs a chat instead of taking a URL, and the chat also takes commands (`/queue`, `/later`, `/run`, `/cancel`, `/result`). Messages from your own bot, with buttons to run, postpone or cancel tasks. Where to get this (the card shows the same steps): 1. Open @BotFather in Telegram. [Open](https://t.me/BotFather) 2. Send /newbot and pick a name. Use a new bot for Tidegap only. 3. Copy the token it sends and paste it here. | Field | Key | Required | Secret | Default | Notes | | --- | --- | --- | --- | --- | --- | | Bot token | `bot_token` | yes | yes | - | - | Events on by default: `task_done`, `task_failed`, `clean_window`, `not_ready`. ### Email Mail through your own SMTP account: Gmail, iCloud, Fastmail or any provider. Where to get this (the card shows the same steps): 1. Gmail: turn on 2-Step Verification, then create an app password named Tidegap. [Open](https://myaccount.google.com/apppasswords) 2. iCloud: Sign-In and Security → App-Specific Passwords → Generate. [Open](https://account.apple.com/) 3. Fastmail: Settings → Privacy & Security → App passwords → New, with SMTP access. [Open](https://www.fastmail.com/help/clients/apppassword.html) 4. Other providers: find the SMTP server, port and security on their help pages. Outlook.com and Hotmail personal accounts are not supported. | Field | Key | Required | Secret | Default | Notes | | --- | --- | --- | --- | --- | --- | | Email address | `user` | yes | no | - | Usually your email address; some relays use a username or 'apikey'. It signs in to the mail server, and it is the sender and the recipient unless you change them below. | | App password | `password` | no | yes | - | An app password, not your normal password. Leave empty only for a server that needs no login. | | SMTP server | `host` | yes | no | - | Under **Advanced**. | | Port | `port` | yes | no | `465` | Under **Advanced**. | | Security | `security` | no | no | `tls` | Under **Advanced**. Values: `tls`, `starttls`, `none`. | | From | `from` | no | no | - | Under **Advanced**. | | Send to | `to` | no | no | - | Under **Advanced**. | | Preset | `--preset` | Server, port, security | Note | | --- | --- | --- | --- | | Gmail | `gmail` | smtp.gmail.com, 465, tls | Turn on 2-Step Verification, then create an app password at myaccount.google.com/apppasswords. Spaces in it are fine. | | iCloud Mail | `icloud` | smtp.mail.me.com, 587, starttls | At account.apple.com: Sign-In and Security → App-Specific Passwords → Generate. Use your full iCloud address. | | Fastmail | `fastmail` | smtp.fastmail.com, 465, tls | Settings → Privacy & Security → App passwords → New, with SMTP access. | | Microsoft 365 (work) | `m365` | smtp.office365.com, 587, starttls | Works only if your admin allows SMTP AUTH. Outlook.com and Hotmail personal accounts are not supported. | Events on by default: `task_failed`, `not_ready`, `digest`. | Code | The card says | Field | | --- | --- | --- | | `auth` | The mail server refused the user name or password. Gmail, iCloud and Fastmail need an app password. | `password` | | `auth_required` | The mail server needs a login. Type the app password. | `password` | | `auth_unsupported` | The mail server offers no login method Tidegap knows (PLAIN or LOGIN). Check the server and the security setting. | `security` | | `starttls_unsupported` | The mail server does not offer STARTTLS on this port. Pick SSL/TLS, or check the port. | `security` | | `tls` | The mail server's certificate is not trusted. Check the server name and the security setting. | `host` | | `network` | Tidegap could not reach the mail server. Check the server name and the port. | `host` | | `timeout` | The mail server did not answer in time. Check the port and the security setting. | `port` | | `smtp_sender` | The mail server refused the sender address. Use your own address in From. | `from` | | `smtp_recipient` | The mail server refused the recipient address. Check Send to. | `to` | | `smtp_policy` | The mail server refused the mail by policy. Check that the account may send mail through SMTP. | - | Use an app password, not your normal password. Gmail and iCloud need 2-step sign-in before they give one. The login is usually your email address. Some relays use a user name instead: SendGrid uses `apikey`, Amazon SES its SMTP user name. With such a login, type your address in **From** (under "Server and addresses"). The login is not kept as a secret: the card and `tidegap channels list` show it in full, so never type a token or a password as the login. Outlook.com and Hotmail personal accounts are not supported: Microsoft turned off password sign-in for SMTP on them. Microsoft 365 work accounts work only when the admin allows SMTP AUTH. Tidegap always checks the server's certificate. It signs in only over TLS, or to a mail server on this computer (`127.0.0.1`, security `none`). ```bash tidegap channels add email --preset gmail --user you@gmail.com --secrets-stdin <<< '{"password": "abcd efgh ijkl mnop"}' ``` ### Slack Messages in a Slack channel through an Incoming Webhook. Where to get this (the card shows the same steps): 1. Open your Slack apps and create one: Create New App → From scratch. [Open](https://api.slack.com/apps) 2. Open Incoming Webhooks and turn them on. 3. Add New Webhook, then pick the channel for Tidegap messages. 4. Copy the webhook URL, paste it here and press Connect. | Field | Key | Required | Secret | Default | Notes | | --- | --- | --- | --- | --- | --- | | Webhook URL | `url` | yes | yes | - | - | Events on by default: `task_done`, `task_failed`, `not_ready`. | Code | The card says | Field | | --- | --- | --- | | `auth` | Slack did not accept this URL. Create a new webhook in Slack and paste it again. | `url` | | `http_404` | Slack removed this webhook. Add a new one in your Slack app and paste it here. | `url` | | `http_410` | The Slack channel of this webhook is archived. Add a webhook for another channel and paste it here. | `url` | | `http_400` | Slack refused the message format. Update Tidegap and try again. | - | | `slack_payload` | Slack refused the message format. Update Tidegap and try again. | - | | `slack_webhook_gone` | Slack removed this webhook. Add a new one in your Slack app and paste it here. | `url` | | `slack_channel_not_found` | The Slack channel of this webhook no longer exists. Add a webhook for another channel and paste it here. | `url` | | `slack_channel_archived` | The Slack channel of this webhook is archived. Add a webhook for another channel and paste it here. | `url` | | `slack_action_prohibited` | A Slack admin restricted posting to this channel. Ask the admin, or add a webhook for another channel. | `url` | The URL must be on `hooks.slack.com/services/`. Task titles cannot link or mention people in Slack. ### Discord Messages in a Discord channel through a webhook. Where to get this (the card shows the same steps): 1. In Discord, open Server Settings → Integrations. 2. Open Webhooks → New Webhook, then pick the channel for Tidegap messages. 3. Press Copy Webhook URL, paste it here and press Connect. | Field | Key | Required | Secret | Default | Notes | | --- | --- | --- | --- | --- | --- | | Webhook URL | `url` | yes | yes | - | - | Events on by default: `task_done`, `task_failed`, `not_ready`. | Code | The card says | Field | | --- | --- | --- | | `auth` | Discord does not know this webhook. Copy the URL again from Server Settings → Integrations → Webhooks. | `url` | | `http_404` | Discord does not know this webhook. Copy the URL again from Server Settings → Integrations → Webhooks. | `url` | | `http_400` | Discord refused the message format. Update Tidegap and try again. | - | The URL must be on `discord.com` (or `discordapp.com`, `canary.discord.com`, `ptb.discord.com`). Messages never mention people. ### ntfy Push notifications to your phone through ntfy, on ntfy.sh or your own server. Where to get this (the card shows the same steps): 1. Install the ntfy app (App Store or Google Play), or open the ntfy web app. [Open](https://ntfy.sh/app) 2. In the app, subscribe to the topic shown here. Copy it with the Copy button. 3. Press Connect. A test notification arrives on your phone. 4. Own server: change the server address, and add an access token if it needs login. [Open](https://docs.ntfy.sh/config/#access-tokens) | Field | Key | Required | Secret | Default | Notes | | --- | --- | --- | --- | --- | --- | | Server | `server` | yes | no | `https://ntfy.sh` | Keep https://ntfy.sh, or type the address of your own ntfy server. | | Topic | `topic` | yes | yes | - | Anyone who knows the topic can read it on a public server. Keep the random name. | | Access token | `token` | no | yes | - | Only for a server or topic that needs login. Leave empty for ntfy.sh. | | Priority | `priority` | no | no | `auto` | Under **Advanced**. Values: `auto`, `5`, `4`, `3`, `2`, `1`. | Events on by default: `task_done`, `task_failed`, `not_ready`. | Code | The card says | Field | | --- | --- | --- | | `auth` | The token was refused. Create a new access token in your ntfy account and paste it here. | `token` | | `ntfy_token_needed` | This topic needs a token. Create an access token in your ntfy account and paste it here. | `token` | | `http_404` | This address is not an ntfy server. Check the server address. | `server` | | `http_400` | The ntfy server refused the topic or the message. Check the topic. | `topic` | | `rate_limited` | The ntfy server limits messages. Wait a few minutes, or use an account token or your own server. | - | | `http_507` | The ntfy server is out of space for this topic. Try again tomorrow, or use your own server. | - | On a public server such as ntfy.sh, anyone who knows the topic can read your messages. Keep the random topic that the card makes, and treat it like a password. ```bash tidegap channels add ntfy --server https://ntfy.sh --secrets-stdin <<< '{"topic": "tidegap-"}' ``` ### Pushover Push notifications to your phone through your own Pushover account. Where to get this (the card shows the same steps): 1. Log in at pushover.net and copy Your User Key from the dashboard. [Open](https://pushover.net/) 2. Create an Application/API Token. Name it Tidegap. [Open](https://pushover.net/apps/build) 3. Copy the API token of that application. 4. Paste both here and press Connect. Pushover is a one-time purchase per platform after a 30-day trial. | Field | Key | Required | Secret | Default | Notes | | --- | --- | --- | --- | --- | --- | | User key | `user_key` | yes | yes | - | - | | API token | `app_token` | yes | yes | - | - | Events on by default: `task_done`, `task_failed`, `not_ready`. | Code | The card says | Field | | --- | --- | --- | | `pushover_user` | Pushover does not know this user key. Copy it again from your Pushover dashboard. | `user_key` | | `pushover_token` | Pushover refused the API token. Copy it again from the application page, or create a new one. | `app_token` | | `http_400` | Pushover refused the message. Check the user key and the API token. | - | | `rate_limited` | Your Pushover application reached its monthly message limit. Wait for the next month, or upgrade it in Pushover. | - | ### Webhook A POST to any URL you own: your server, n8n, Home Assistant, Teams, Google Chat. Also works with Microsoft Teams (Workflows), Google Chat, Mattermost and Matrix (hookshot). Where to get this (the card shows the same steps): 1. Create an incoming webhook in the receiving app and copy its URL. Teams: in the channel, Workflows → "Post to a channel when a webhook request is received". 2. Pick the body format: Tidegap JSON for your own code, n8n or Home Assistant; Plain text for Google Chat, Mattermost and Matrix; Teams card for Teams. 3. Optional: add a signing secret or headers such as Authorization. 4. Press Connect. Tidegap sends a test message with "event": "test"; answer it with any 2xx status. | Field | Key | Required | Secret | Default | Notes | | --- | --- | --- | --- | --- | --- | | Webhook URL | `url` | yes | yes | - | - | | Body format | `format` | no | no | `tidegap` | Values: `tidegap`, `text`, `teams`. Tidegap JSON is {"version": 1, "event", "level", "title", "text", "at", "task"}. The Connect and Send test message has "event": "test". | | Signing secret | `secret` | no | yes | - | Under **Advanced**. Optional. Adds X-Tidegap-Timestamp and X-Tidegap-Signature: sha256=HMAC-SHA256(secret, "."). | | Extra headers | `headers` | no | yes | - | Under **Advanced**. Optional. One "Name: value" per line, for example an Authorization header. Stored as a secret. | Events on by default: `task_done`, `task_failed`, `clean_window`, `not_ready`. | Code | The card says | Field | | --- | --- | --- | | `http_413` | The receiver refused the message as too large. Raise its body limit, or pick the Plain text format. | - | | `http_400` | The receiver refused the message body (HTTP 400). Check that the body format matches the receiver. | `format` | The Tidegap JSON body (`"version": 1`): ```json { "version": 1, "event": "task_done", "level": "success", "title": "Done: Weekly report", "text": "Done: Weekly report …", "at": "2026-10-20T07:00:00.000Z", "task": { "id": "t_…", "title": "Weekly report", "status": "completed", "grams": 1.4 } } ``` `event` is `task_done`, `task_failed`, `clean_window`, `not_ready`, `digest` or `test`. `level` is `success`, `error`, `info` or `warning`. `task` is present for task events only. A `not_ready` body with `"recovered": true` is the "running again" message, not an alert. `title` and `text` are plain text from the task; escape them before you show them as HTML. Every attempt of one message has the same `X-Tidegap-Delivery: ` header, so your receiver can drop duplicates. Tidegap tries up to 3 times on a network error, a 5xx or a 429, inside 20 seconds. It does not follow redirects. With a signing secret, each request also has `X-Tidegap-Timestamp: ` and `X-Tidegap-Signature: sha256=`, the HMAC-SHA256 of `"."`. Check the signature over the raw body, and refuse a timestamp older than 5 minutes. ```js // Node import { createHmac, timingSafeEqual } from "node:crypto"; function verify(secret, rawBody, headers) { const ts = headers["x-tidegap-timestamp"]; const sig = headers["x-tidegap-signature"] ?? ""; if (!ts || Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false; const want = "sha256=" + createHmac("sha256", secret).update(`${ts}.${rawBody}`).digest("hex"); const a = Buffer.from(sig), b = Buffer.from(want); return a.length === b.length && timingSafeEqual(a, b); } ``` ```python # Python import hashlib, hmac, time def verify(secret: bytes, raw_body: bytes, headers) -> bool: ts = headers.get("X-Tidegap-Timestamp", "") sig = headers.get("X-Tidegap-Signature", "") if not (ts.isascii() and ts.isdigit()) or abs(time.time() - int(ts)) > 300: return False want = "sha256=" + hmac.new(secret, ts.encode() + b"." + raw_body, hashlib.sha256).hexdigest() return hmac.compare_digest(sig, want) ``` ```bash tidegap channels add webhook --format tidegap --secrets-stdin <<< '{"url": "https://example.com/hooks/tidegap", "secret": ""}' ``` ### Shortcuts Runs a macOS Shortcut with the message as its input: send an iMessage, add a reminder, turn on a light. Works on macOS only. Where to get this (the card shows the same steps): 1. Open the Shortcuts app and create a new shortcut. [Open](https://support.apple.com/guide/shortcuts-mac/create-a-custom-shortcut-apd84c576f8c/mac) 2. Add an action that uses Shortcut Input, for example Send Message or Add New Reminder. 3. Name the shortcut Tidegap. 4. Type the name here and press Connect. The shortcut runs once with a test message. | Field | Key | Required | Secret | Default | Notes | | --- | --- | --- | --- | --- | --- | | Shortcut name | `name` | yes | no | - | - | Events on by default: `task_done`, `task_failed`, `not_ready`. | Code | The card says | Field | | --- | --- | --- | | `not_found` | The Shortcuts app has no shortcut with this name. Check the spelling and the capital letters. | `name` | | `no_shortcuts` | The shortcuts tool was not found. Shortcuts needs macOS 12 or later. | - | | `timeout` | The shortcut did not finish in 20 seconds. Remove actions that wait for you, such as Ask for Input. | `name` | | `shortcut_failed` | The shortcut stopped with an error. Run it once in the Shortcuts app to see the error. | `name` | Tidegap runs `/usr/bin/shortcuts run ` with the message in a temporary file as the input, with no shell. The shortcut must finish in 20 seconds and must not wait for you (no Ask for Input). ### Command Runs a program on this computer with each message as JSON on its standard input. Works on macOS and Linux only. Where to get this (the card shows the same steps): 1. Write a program or script that reads JSON from its standard input. Make it executable and writable only by you (chmod 755). 2. The JSON is {"version": 1, "event", "level", "title", "text", "at", "task"}; the test message has "event": "test". 3. It runs in your home folder with only PATH, HOME, LANG and TMPDIR set, and must finish in 20 seconds. 4. Type the full path here and press Connect. Exit code 0 means delivered. | Field | Key | Required | Secret | Default | Notes | | --- | --- | --- | --- | --- | --- | | Program | `path` | yes | no | - | The full path of an executable file that you own. Tidegap runs it directly, with no shell. | | Arguments | `args` | no | no | - | Under **Advanced**. Optional. One argument per line, at most 10; no quotes needed. They are not secret: other programs on this computer can see them. | Events on by default: `task_done`, `task_failed`, `not_ready`. | Code | The card says | Field | | --- | --- | --- | | `not_found` | There is no program at this path. Check the path. | `path` | | `not_executable` | This file is not executable. Run chmod +x on it, or pick another file. | `path` | | `unsafe_path` | Tidegap runs only a program you own, in a folder only you can change. Run chmod go-w on the file and its folder. | `path` | | `timeout` | The program did not finish in 20 seconds. Make it exit sooner, or start slow work in the background. | `path` | | `command_failed` | The program exited with an error. Run it by hand with a test message on its input to see why. | `path` | The program gets the Tidegap JSON body (the [webhook](#notify-webhook) format) on its standard input. Exit code 0 means delivered. See the rules in [Security](#notify-security). ```bash #!/bin/sh # ~/bin/tidegap-notify: one line per message to a log file /usr/bin/tee -a "$HOME/tidegap-notify.log" > /dev/null ``` ```bash chmod 755 ~/bin/tidegap-notify tidegap channels add command --path "$HOME/bin/tidegap-notify" ``` ### CLI Every card action has a command. Channel ids are the kind (`webhook`, `email`…) or `telegram-`. Exit codes: 0 success, 1 a refused value or a failed test, 2 a usage error (for example an unknown kind, or an unknown flag on a kind other than Telegram). ```bash tidegap channels kinds # each kind's flags, secrets and presets here tidegap channels add slack # prompts for the webhook URL, hidden tidegap channels list # ID, KIND, STATE, EVENTS, LAST, TARGET (--json for JSON) tidegap channels test slack # send a test message tidegap channels set slack --events task_failed,digest --quiet night tidegap channels disconnect slack # stop; settings and secrets stay tidegap channels connect slack # test message, then send again tidegap channels digest --at 08:00 # the daily summary's send time tidegap channels remove slack # remove the channel and its secrets ``` Secrets never go in flags. On a terminal, `channels add` asks for each missing secret with hidden input. Else pass one JSON object with `--secrets-stdin`. An unknown flag such as `--url` stops with exit 2 and never prints its value. `channels add telegram` takes no kind fields and ignores other flags. `tidegap channels --help`: ``` Usage: tidegap channels [options] [command] Notification channels: add (Telegram, webhook, Slack, Discord, ntfy, Pushover, email, Shortcuts, command), test, connect, disconnect, set, remove, list, digest Options: -h, --help display help for command Commands: add [options] Set up a channel in one step: validate, send a test message, then save. Telegram prints a pairing code instead. Secrets come from --secrets-stdin (one JSON object) or a hidden prompt, never from flags. `tidegap channels kinds` lists each kind's flags kinds [options] List the kinds `channels add` takes here, with their flags, secrets and presets connect [options] Connect a disconnected channel with its stored settings: one test message, then it sends again test [options] Send a test message to a connected channel; the result is its last delivery disconnect [options] Stop sending; settings and secrets stay for `channels connect` set [options] Change a channel's events and quiet hours (no test message); Telegram chats too list [options] List the channels with their state, events, last delivery and target (secrets as hints only) remove [options] Remove a channel and its secrets; removing the last telegram channel unloads the listener digest [options] Show or set the daily summary's local send time (default 09:00, the end of quiet hours); channels get it with the digest event serve [options] Run the Telegram listener (the listener unit runs this); --once polls one cycle help [command] display help for command ``` `tidegap channels add --help`: ``` Usage: tidegap channels add [options] Set up a channel in one step: validate, send a test message, then save. Telegram prints a pairing code instead. Secrets come from --secrets-stdin (one JSON object) or a hidden prompt, never from flags. `tidegap channels kinds` lists each kind's flags Options: --db SQLite queue path --no-load Telegram: pair only; do not install or load the listener unit --secrets-stdin Read the secret fields as one JSON object on stdin, e.g. {"url": "https://…"} --events Comma-separated: task_done,task_failed,clean_window,not_ready,digest (default: the kind's) --quiet night (no messages 22:00–09:00 but the daily summary) or off --clear Comma-separated optional secrets to remove (an empty secret otherwise keeps the stored one) --preset Email: gmail, icloud, fastmail or m365 fills the server, port and security --user Email address (email) --host SMTP server (email) --port Port (email) --security Security (email) --from From (email) --to Send to (email) --server Server (ntfy) --priority Priority (ntfy) --format Body format (webhook) --name Shortcut name (shortcuts) --path Program (command) --args Arguments (command); repeat for each line -h, --help display help for command ``` `tidegap channels set --help`: ``` Usage: tidegap channels set [options] Change a channel's events and quiet hours (no test message); Telegram chats too Options: --db SQLite queue path --events Comma-separated: task_done,task_failed,clean_window,not_ready,digest; an empty string sends nothing --quiet night or off -h, --help display help for command ``` `tidegap channels digest --help`: ``` Usage: tidegap channels digest [options] Show or set the daily summary's local send time (default 09:00, the end of quiet hours); channels get it with the digest event Options: --db SQLite queue path --at Local send time, 00:00 to 23:59 -h, --help display help for command ``` ### Security - **Where secrets live.** Secret fields (URLs with tokens, passwords, topics, keys) go to `~/.config/tidegap/channel-secrets.json`, mode `0600` in a `0700` folder. The ledger and every API answer hold only non-secret settings and hints such as `··abcd`. The Telegram bot token lives in `~/.config/tidegap/env`. `tidegap channels remove ` deletes the channel's secrets. There is no uninstall command: delete both files by hand to remove every secret. - **URL policy.** Webhook, Slack, Discord, ntfy and Pushover send to `http` and `https` only. Your own network is allowed (Home Assistant, n8n, a self-hosted ntfy). Tidegap refuses a user name or password inside the URL, link-local and cloud metadata addresses (`169.254.0.0/16`, `fe80::/10`), the unspecified address and the port of the `tidegap ui` page itself. It checks the address again on every send, after the DNS lookup. Plain `http` to a public host works, but the card warns that the message travels unencrypted. - **Public ntfy topics.** On ntfy.sh a topic is the only key. Keep it random and secret, or use your own server with an access token. - **Shortcuts and Command run on this computer.** Tidegap runs the program directly, never through a shell, with only `PATH`, `HOME`, `LANG` and `TMPDIR` set, in your home folder, and stops it after 20 seconds. Shortcuts runs the system program `/usr/bin/shortcuts`. For Command, before every run Tidegap checks that the file (and the target of a symlink) is a regular executable file that you own, and that no other user can write to it or its folder. A program owned by `root`, such as `/usr/bin/say`, is refused (`unsafe_path`): write a small script that you own and call the program from it. Arguments are not secret; other programs on this computer can see them. - **`PATH` under launchd.** The tick that the LaunchAgent starts has a short `PATH` (`/usr/bin:/bin:/usr/sbin:/sbin`). Use full paths inside your script, for example `/opt/homebrew/bin/jq`. - **What leaves the computer.** A message has the task title, its status and, for a done task, a preview of the result. A task with `redact_in_receipt` gets no preview. Pick channels you trust with that text. ## Telegram Tidegap can send task events to a Telegram chat. You can also run commands from that chat. This is a channel. The events, quiet hours, daily summary and the other channels are on [Notifications](#notifications). Set it up in Settings → Integrations, in the `tidegap ui` page or the Mac app. The CLI does the same from a terminal. ### What you get The bot sends a message when a task finishes or fails. It also tells you when a clean window starts and when queued tasks cannot run. A done message has a Result button. These commands work in the paired chat: | Command | What it does | | --- | --- | | `/queue` | The next 10 tasks, numbered. | | `/later <1h\|tonight\|tomorrow\|reset [HH:MM]\|HH:MM>` | Run a task later. `HH:MM` is your local time. | | `/run ` | Run a task at the next tick. | | `/cancel ` | Cancel a task. | | `/result ` | The result of a finished task. | | `/jobs [pause\|resume\|run ]` | Recurring jobs, numbered, with the next and the last run in each job's time zone. `pause`, `resume` and `run` act on one job. Create and edit jobs on the page. | | `/help` | This list. | Task numbers come from the last `/queue`, job numbers from the last `/jobs`. They stay valid for 10 minutes. Run the list again to get new numbers. ### Set up In the page or the Mac app: 1. Open Settings. In the page that `tidegap ui` opens, it is the Settings button at the top right. In the Mac app, choose **Integrations…** in the menu. 2. Create a bot with [@BotFather](https://t.me/BotFather): send `/newbot` and pick a name. Use this bot only for Tidegap. 3. Paste the token that @BotFather sends into the **Bot token** field and press **Connect** (or Enter). One click does everything: Tidegap tests the token, saves it, sets the bot's description, short description and command menu, and shows the pairing code. If Telegram refuses the token, the card says so under the field. Tidegap saves the token in `~/.config/tidegap/env` and never shows it again. If setting the profile fails, the card says so; pairing still works. 4. The card shows a 6-digit code, the `/pair ` command, the link and a QR code. Click the bot name, the code, the command or the link to copy it; **Open in Telegram** opens the link. Scan the QR code with the phone, or open the link. Telegram opens the bot; press **Start**. The code is valid for 10 minutes. 5. The card shows "Paired with @you". Press **Send test message** to check it. 6. Optional: press **Download avatar** on the card, then send `/setuserpic` to @BotFather and choose the file. The Bot API cannot set a bot's picture. Only the page and the Mac app can open these settings. The browser extensions cannot. What the card can show, and what to do: | The card says | Do this | | --- | --- | | Telegram refused this token | Copy the token again from @BotFather and save it. | | Another program reads this bot's messages | Another program polls the same bot. Create a new bot for Tidegap. | | Listener not running | Press **Start listener**. | | The listener cannot reach Telegram | Check the internet connection. | | Listener runs by hand on this computer | Windows has no listener service. Keep `tidegap channels serve` running in a terminal. | **Disconnect** removes the paired chat and stops the listener. Tick **Also delete the token** to remove the token from the env file too. A token for a different bot removes the paired chat; connect again after you save it. From the terminal: 1. Create a bot with [@BotFather](https://t.me/BotFather). Use this bot only for Tidegap. If another program polls the bot, Telegram gives it a `409` error. Pairing then stops. 2. Put the bot token in `~/.config/tidegap/env`. Keep the file at mode `0600`: ``` TIDEGAP_TELEGRAM_BOT_TOKEN= ``` Tidegap ignores a token that you only export in the shell. The listener runs without your shell, so it reads this file only. 3. Run `tidegap channels add telegram`. It prints a 6-digit code. The code is valid for 10 minutes. 4. Send `/pair ` to the bot in a private chat. You can also open `https://t.me/?start=`. Groups are ignored. Five wrong codes stop the pairing. Pairing installs and starts the listener. On macOS it is the LaunchAgent `com.tidegap.channels`. On Linux it is the systemd user unit `tidegap-channels.service`. Both run `tidegap channels serve` and restart it if it stops. On Windows, keep `tidegap channels serve` running yourself. ### Manage ```bash tidegap channels list # paired channels (--json for JSON) tidegap channels remove # unpair; the last Telegram channel stops the listener ``` The bot answers only the paired chat. Everyone else gets no reply. If pairing or the listener reports `409`, another program uses the same bot. Create a new bot for Tidegap. A done message shows the first 600 characters of the result. That text goes to Telegram. A task with `redact_in_receipt` gets no preview. The token never appears in logs or errors. ## Receipts & carbon Every task that runs gets a carbon receipt, signed with a key that stays on your machine. Anyone can check a receipt offline. ### Signed receipts - The keys are `~/.tidegap/signing.key` (private, mode `0600`) and `signing.key.pub`. The first dispatch creates them. - The receipt carries `signerPublicKey`, so a consumer can pin the key the first time it sees it. - The verifier returns `valid`, `tampered`, `legacy-unsigned` (a receipt from before signing existed) or `key-mismatch`. The CLI exit codes are 0, 1, 2 and 3. - A receipt that carries one field under two key renderings, for example `actualCarbonGCo2` and `actual_carbon_g_co2`, is `tampered`. No signer writes both. ### Verify a receipt ```bash # A task in the local ledger tidegap verify t-ef2354ee-eff0-431c-b11e-6edfcb8299b0 # A receipt file, pinned to the signer you expect tidegap verify --file ./receipt.json --trusted-public-key ``` `tidegap verify ` checks the bytes stored in the ledger. An exported receipt (`tidegap queue show --json`, the page) is a copy with camelCase keys. A Python receipt signed by v0.11 or older verifies only from the ledger. For such a file, `tidegap verify --file` reports `tampered` and names `tidegap verify `. From code: ```ts import { loadOrCreateSigningKey, signReceipt, verifyReceipt } from "@tidegap/core"; const signed = signReceipt(receipt, loadOrCreateSigningKey()); verifyReceipt(signed); // { outcome: "valid" | "tampered" | "legacy-unsigned" | "key-mismatch", ... } ``` ```python # pip install "tidegap[signing]" from tidegap import load_or_create_signing_key, sign_receipt, verify_receipt signed = sign_receipt(receipt_dict, load_or_create_signing_key()) verify_receipt(signed) # VerifyResult(outcome='valid', ...) ``` ### A real run One run on GB, 2026-09-30, with the live National Grid ESO feed and a local Ollama `llama3.2:1b`. The forecast peak was 183 gCO2/kWh. For a 72 h deadline the recommended window was 88 gCO2/kWh. At dispatch the live feed measured 158 gCO2/kWh, and the receipt records that value. Raw output and the reproducer: [docs/examples/2026-09-30-GB-tick](https://github.com/tidegap/tidegap/tree/main/docs/examples/2026-09-30-GB-tick). ### Energy per model A receipt's grams come from the grid intensity times an energy estimate for the model. The coefficients come from Patterson et al. 2021 (arXiv:2104.10350), Luccioni, Jernite and Strubell 2024, "Power Hungry Processing" (arXiv:2311.16863), and the Hugging Face AI Energy Score. | Model class | Wh / input token | Wh / output token | Typical call* | Source | | --- | --- | --- | --- | --- | | claude-opus-5 · claude-fable-5-1 · gpt-6-astra · o3 | 0.003 | 0.015 | ~10.4 Wh | estimated | | gpt-4o · gemini-3.1-pro | 0.002 | 0.01 | ~6.9 Wh | estimated | | claude-sonnet-5 · gpt-6-sol · llama-3.1-70b | 0.001 | 0.005 | ~3.5 Wh | estimated | | claude-haiku-4-5 · gpt-6-luna · gemini-3.8-flash · gpt-4o-mini | 0.0003 | 0.0015 | ~1.0 Wh | estimated | | llama-3.1-8b · mistral-7b | 0.0002 | 0.001 | ~0.7 Wh | measured | | llama-3.1-405b · gpt-4 | 0.005 | 0.025 | ~17.3 Wh | measured | \* Typical call: 500 input and 500 output tokens, times `DEFAULT_PUE` = 1.15. A token count that a run does not report is billed as 500 tokens, with one model or several. A count that is negative, not finite or too large for a double counts as not reported. An input reported only in part, for example a fresh input next to a missing cache-write count, is billed at the larger of its reported parts and 500. The receipt then carries `tokenCounts`, inside the signed payload: `partial` when some count or input part was reported, `typical` when none was. A single-model receipt with `tokenCounts` has no `totalTokens`. A receipt that reports every count has no `tokenCounts`, and its bytes are the same as before. When the grid intensity at dispatch is not known, the receipt has no `intensityGCo2PerKwh` and its grams are the schedule-time estimate; `tokenCounts` still describes only the counts the run reported. Closed-model coefficients are inferred from public parameter counts and the Luccioni scaling curve, and may be off by ±50%. Each coefficient has a `source` of `measured`, `estimated` or `fallback`. ### Runs that use several models A Claude Code run can use more than one model, for example a helper model that reads web pages, or a subagent. The receipt then bills each model's tokens with that model's own coefficients, and lists the models in `models`. - Each entry has `model`, `inputTokens` (fresh input plus cache writes), `outputTokens`, `carbonGCo2`, `energySource` and `energyResolution`. - A count that a model did not report is billed at the typical count, 500 tokens. The entry then has no field for that count, and `totalTokens` leaves it out. When no model reported a count, the receipt has no `totalTokens`. For the order, a missing output count is 0. - The entries are in order of output tokens, most first. The receipt's `model` is the first entry. - `actualCarbonGCo2` and `totalTokens` are sums over the entries. `energySource` and `energyResolution` are the weakest values across the entries. - Each entry's `carbonGCo2` is rounded to 0.01 g and the total to 0.1 g, so the entries may not add up exactly to the total. When the grid intensity at dispatch is not known, the entries have no `carbonGCo2`. - The list is inside the signed payload: a change to any entry makes the receipt `tampered`. - `tokenCounts` at the top of the receipt covers every entry. An entry that lacks a count makes the receipt `partial`, or `typical` when no entry reported a count. - A run with one model has no `models` field. Receipts signed before this field existed verify as before. - `tidegap queue show --json` prints the full receipt with the list. ### What the numbers mean - **Grid intensity** is measured when a live feed covers the region. Without an API key, regions other than GB use a deterministic mock curve, and the receipt names the feed in `grid_source`. - **Savings** depend on the region, the hour and the deadline. A short deadline leaves little room to move. - **Batch pricing** is the provider's published list price for its Batch API (projected), not a measured bill. ## Config Tidegap works with no keys and no config. Keys unlock live grid data for more regions and let the tick send tasks to a provider. ### Paths | Path | What it holds | | --- | --- | | `~/.tidegap/queue.db` | The SQLite ledger: the queue and the carbon receipts. The CLI, the MCP server and `tidegap ui` share it. | | `~/.tidegap/signing.key` | The private key that signs receipts (`0600`), with `signing.key.pub` next to it. It never leaves the machine. | | `~/.tidegap/telemetry.key` | Reserved for a planned opt-in leaderboard. Not created until you opt in, and never sent. | | `~/.tidegap/ui.json` | The port and pid of a running `tidegap ui`. No token. | | `~/.tidegap/sessions/` | Files of the Claude Code plugin (folder `0700`, files `0600`): `claude-.json`, which session a running Claude Code process is in, and `notices/`, present while that session has finished tasks it was not told about. See [Agent handoff](#handoff-notices). | | `~/.tidegap/config` | Settings as `KEY=value` lines. `tidegap region set` writes `TIDEGAP_DEFAULT_REGION` here, and `tidegap limits set` the [run limits](#limits). | | `~/.config/tidegap/env` | Keys and secrets as `KEY=value` lines (`0600`). The CLI reads it; the MCP server does not. A variable in the real environment wins over the file. | | `~/.config/tidegap/channel-secrets.json` | The secret fields of the notification channels (`0600`): webhook URLs, passwords, ntfy topics, Pushover keys. `tidegap channels remove ` deletes a channel's entry. There is no uninstall command: delete this file and the env file by hand. See [Notifications](#notify-security). | ### Environment Set these in the MCP host's `env` block, or in the shell that runs the tick. GB is always live through National Grid ESO, with no key. | Variable | What it unlocks | OpenClaw config key | | --- | --- | --- | | `TIDEGAP_EIA_API_KEY` | Live average-emissions data for the US ISOs (EIA). Free at eia.gov/opendata. | `eiaApiKey` | | `WATTTIME_USERNAME`, `WATTTIME_PASSWORD` | Live marginal-emissions forecasts for the US ISOs (WattTime v3). Wins over EIA where it covers a region. | `wattTimeUsername`, `wattTimePassword` | | `TIDEGAP_ENTSOE_SECURITY_TOKEN` | Live data for European zones (ENTSO-E Transparency Platform). | `entsoeSecurityToken` | | `TIDEGAP_ELECTRICITY_MAPS_API_KEY` | Electricity Maps free tier, the fallback for any other zone. | `electricityMapsApiKey` | | `ANTHROPIC_API_KEY`, `OPENAI_API_KEY` | Dispatch to Anthropic or OpenAI. Both can use the Batch API when the deadline allows. | `anthropicApiKey`, `openaiApiKey` | | `GEMINI_API_KEY`, `GOOGLE_API_KEY` | Dispatch to Google Gemini. `GEMINI_API_KEY` wins. | `geminiApiKey`, `googleApiKey` | | `OLLAMA_HOST`, `OLLAMA_MODELS` | Dispatch to a local Ollama server (default `http://localhost:11434`). No key needed. | `ollamaHost`, `ollamaModels` | | `TIDEGAP_PUSHOVER_API_BASE` | Tests only: a loopback `http://` address that replaces the Pushover API. Any other value is ignored with one log line. | - | | `TIDEGAP_DEFAULT_REGION` | The grid region when nothing more specific names one. Overrides the stored setting. See [Grid region](#region). | `defaultRegion` | Without a grid key, a region other than GB uses a deterministic mock curve. Without a provider key, tasks are queued but not sent. ### OpenClaw plugin config The OpenClaw plugin reads no environment variables. Set the keys from the last column under `plugins.entries.tidegap.config` in the gateway config. OpenClaw resolves `"${ENV_VAR}"` in those fields, so the values can still come from the environment. ### Grid region Tidegap plans every task against the forecast of one grid region. Set it once and every surface uses it: the tick, the queue, `tidegap ui`, the Mac app, the browser extension, the Telegram listener, the MCP server and the OpenClaw plugin. ```bash tidegap region show # the zone, where it came from, its data source tidegap region set FR # store a zone (any case; UK means GB) tidegap region set auto # clear it; the time-zone guess applies again ``` In the page and the Mac app: **Settings → Grid region**. See [UI & apps](#region-card). The first rule that gives a region wins. `tidegap region show`, `/api/summary`, `/api/status` and the `schedule_task` reply of the MCP server and the OpenClaw plugin name the rule that applied (`source` or `region_source`). | Order | `region_source` | Where the region comes from | | --- | --- | --- | | 1 | `flag` | `tidegap tick --region` or `tidegap ui --region`, or the `region` argument of a tool call. | | 2 | `env` | `TIDEGAP_DEFAULT_REGION` in the environment. The CLI also reads it from `~/.config/tidegap/env`. | | 2 | `config` | OpenClaw only, in place of `env`: the plugin's `defaultRegion`. | | 3 | `setting` | `TIDEGAP_DEFAULT_REGION` in `~/.tidegap/config`, written by `tidegap region set` or the Settings card. | | 4 | `timezone` | A guess from the machine's time zone. Only time zones with one clear grid are mapped (see the table below). | | 5 | `fallback` | `GB`, which has live data with no key. | A change applies without a restart. Tasks already queued keep their region. | Surface | Reads `TIDEGAP_DEFAULT_REGION` from | A changed setting applies | | --- | --- | --- | | `tidegap tick`, `tidegap ui`, the Telegram listener | The environment and `~/.config/tidegap/env`, read again on each tick, request or command | On the next tick, request or command | | `tidegap region`, `tidegap queue` | The environment and `~/.config/tidegap/env`, on each run | On the next run | | Mac app, browser extension | Through the `tidegap ui` they connect to | On the next request | | MCP server (`@tidegap/mcp`) | The process environment only: the host's `env` block. It never reads `~/.config/tidegap/env`. A changed value needs a host restart | On the next tool call | | OpenClaw plugin | No environment: the plugin `defaultRegion` instead | On the next tool call | **Unknown zone.** `tidegap region set`, the Settings card and a tool's `region` argument accept only the zones below, in any case. Anything else fails with the closest zones and a link to request a region, for example `Unknown zone UA. Closest: PL. Request a region: `. A tool argument for another zone passes when a key serves it live: any zone except `IT` with `TIDEGAP_ELECTRICITY_MAPS_API_KEY`, and `IT`, an ENTSO-E zone, only with `TIDEGAP_ENTSOE_SECURITY_TOKEN`. A stored value that is not a supported zone is ignored and reported, and the next rule applies. **Ukraine.** There is no Ukrainian grid data yet. A time zone in Ukraine (`Europe/Kyiv`, `Europe/Kiev`, `Europe/Uzhgorod`, `Europe/Zaporozhye`) maps to `PL`, the nearest supported grid in the same synchronous area. The hour-of-day timing carries over; the absolute grams do not. `tidegap region show` and the card say "No Ukrainian grid data yet" and link to a region request. **Supported zones.** Live data needs the key in the "Key" column (US zones also go live with `WATTTIME_USERNAME` and `WATTTIME_PASSWORD`); without it the zone uses a deterministic sample curve. `tidegap region list` prints the same list. | Zone | Name | Country | Grid operator | Live data | Key | Time-zone guess | | --- | --- | --- | --- | --- | --- | --- | | `US-CAL-CISO` | California | United States (US) | California ISO (CAISO) | WattTime or US EIA | `TIDEGAP_EIA_API_KEY` | `America/Los_Angeles` | | `US-TEX-ERCO` | Texas | United States (US) | ERCOT | WattTime or US EIA | `TIDEGAP_EIA_API_KEY` | - | | `US-NE-ISNE` | New England | United States (US) | ISO New England | WattTime or US EIA | `TIDEGAP_EIA_API_KEY` | - | | `US-MIDA-PJM` | PJM Mid-Atlantic | United States (US) | PJM Interconnection | WattTime or US EIA | `TIDEGAP_EIA_API_KEY` | `America/New_York`, `America/Detroit` | | `GB` | Great Britain | United Kingdom (GB) | National Energy System Operator (NESO) | NESO Carbon Intensity API | none | `Europe/London` | | `FR` | France | France (FR) | RTE | ENTSO-E | `TIDEGAP_ENTSOE_SECURITY_TOKEN` | `Europe/Paris` | | `DE` | Germany | Germany (DE) | 50Hertz, Amprion, TenneT, TransnetBW | ENTSO-E | `TIDEGAP_ENTSOE_SECURITY_TOKEN` | `Europe/Berlin`, `Europe/Busingen` | | `IE` | Ireland | Ireland (IE) | EirGrid | Electricity Maps | `TIDEGAP_ELECTRICITY_MAPS_API_KEY` | `Europe/Dublin` | | `NL` | Netherlands | Netherlands (NL) | TenneT | ENTSO-E | `TIDEGAP_ENTSOE_SECURITY_TOKEN` | `Europe/Amsterdam` | | `ES` | Spain | Spain (ES) | Red Eléctrica (REE) | ENTSO-E | `TIDEGAP_ENTSOE_SECURITY_TOKEN` | `Europe/Madrid` | | `BE` | Belgium | Belgium (BE) | Elia | Electricity Maps | `TIDEGAP_ELECTRICITY_MAPS_API_KEY` | `Europe/Brussels` | | `AT` | Austria | Austria (AT) | Austrian Power Grid (APG) | Electricity Maps | `TIDEGAP_ELECTRICITY_MAPS_API_KEY` | `Europe/Vienna` | | `PL` | Poland | Poland (PL) | PSE | Electricity Maps | `TIDEGAP_ELECTRICITY_MAPS_API_KEY` | `Europe/Warsaw`; approximate, no UA data: `Europe/Kyiv`, `Europe/Kiev`, `Europe/Uzhgorod`, `Europe/Zaporozhye` | | `JP-TK` | Tokyo | Japan (JP) | TEPCO Power Grid | Electricity Maps | `TIDEGAP_ELECTRICITY_MAPS_API_KEY` | - | | `KR` | South Korea | South Korea (KR) | Korea Power Exchange (KPX) | Electricity Maps | `TIDEGAP_ELECTRICITY_MAPS_API_KEY` | `Asia/Seoul` | | `SG` | Singapore | Singapore (SG) | Energy Market Authority (EMA) | Electricity Maps | `TIDEGAP_ELECTRICITY_MAPS_API_KEY` | `Asia/Singapore` | | `AU-NSW` | New South Wales | Australia (AU) | AEMO | Electricity Maps | `TIDEGAP_ELECTRICITY_MAPS_API_KEY` | `Australia/Sydney` | | `CA-ON` | Ontario | Canada (CA) | IESO | Electricity Maps | `TIDEGAP_ELECTRICITY_MAPS_API_KEY` | - | | `US-NY-NYIS` | New York | United States (US) | NYISO | WattTime or US EIA | `TIDEGAP_EIA_API_KEY` | - | | `US-MIDW-MISO` | Midcontinent | United States (US) | MISO | WattTime or US EIA | `TIDEGAP_EIA_API_KEY` | - | | `US-NW-BPAT` | Pacific Northwest | United States (US) | Bonneville Power Administration (BPA) | Electricity Maps | `TIDEGAP_ELECTRICITY_MAPS_API_KEY` | - | | `US-FLA-FPL` | Florida | United States (US) | Florida Power & Light (FPL) | Electricity Maps | `TIDEGAP_ELECTRICITY_MAPS_API_KEY` | - | | `IT-NO` | Northern Italy | Italy (IT) | Terna | Electricity Maps | `TIDEGAP_ELECTRICITY_MAPS_API_KEY` | - | | `SE-SE3` | Central Sweden (SE3) | Sweden (SE) | Svenska kraftnät | Electricity Maps | `TIDEGAP_ELECTRICITY_MAPS_API_KEY` | - | | `NO-NO1` | Southeast Norway (NO1) | Norway (NO) | Statnett | Electricity Maps | `TIDEGAP_ELECTRICITY_MAPS_API_KEY` | - | | `FI` | Finland | Finland (FI) | Fingrid | Electricity Maps | `TIDEGAP_ELECTRICITY_MAPS_API_KEY` | `Europe/Helsinki` | | `DK-DK1` | West Denmark (DK1) | Denmark (DK) | Energinet | Electricity Maps | `TIDEGAP_ELECTRICITY_MAPS_API_KEY` | - | | `IN-WE` | Western India | India (IN) | Grid Controller of India | Electricity Maps | `TIDEGAP_ELECTRICITY_MAPS_API_KEY` | - | | `ZA` | South Africa | South Africa (ZA) | Eskom | Electricity Maps | `TIDEGAP_ELECTRICITY_MAPS_API_KEY` | `Africa/Johannesburg` | | `AE` | United Arab Emirates | United Arab Emirates (AE) | EWEC and DEWA | Electricity Maps | `TIDEGAP_ELECTRICITY_MAPS_API_KEY` | `Asia/Dubai` | | `NZ` | New Zealand | New Zealand (NZ) | Transpower | Electricity Maps | `TIDEGAP_ELECTRICITY_MAPS_API_KEY` | `Pacific/Auckland` | ### Run limits Each run of a task or a job has a time limit, and a failed run is tried again by its retry policy. The limits and the retry policy are settings in `~/.tidegap/config`: raise one, set it per runner, or switch a time limit off with `none`. | Setting | `~/.tidegap/config` keys | Per-task flag and field | Value | Built-in default | `none` and `0` | | --- | --- | --- | --- | --- | --- | | Command time limit | `TIDEGAP_COMMAND_TIMEOUT` | `--command-timeout` (`queue add`, `jobs`); HTTP `command_timeout_s` | duration | `30m` | `none`: no limit. `0`: refused. | | LLM time limit | `TIDEGAP_LLM_TIMEOUT`, `TIDEGAP_LLM_TIMEOUT_` | `--llm-timeout` (`queue add`, `jobs`); MCP and OpenClaw `llm_timeout`; HTTP `llm_timeout_s` | duration | `claude-code` `30m`; `anthropic`, `openai`, `gemini`, `ollama` `10m` | `none`: no limit. `0`: refused. | | Retries | `TIDEGAP_RETRIES`, `TIDEGAP_RETRIES_` | `--retries` (`queue add`, `jobs`); MCP and OpenClaw `retries`; HTTP `retries` | whole number 0-10 | `1` | `0`: no automatic retry. `none`: refused. | | Retry delay | `TIDEGAP_RETRY_DELAY`, `TIDEGAP_RETRY_DELAY_` | `--retry-delay` (`queue add`, `jobs`); MCP and OpenClaw `retry_delay`; HTTP `retry_delay_s` | duration; retry k waits delay × 2^(k−1) | `30m` | Both refused. | - **Duration:** a number and a unit, `s`, `m` (or `min`), `h` or `d`, in any case: `90s`, `30m`, `1.5h`, `2d`. A bare number is seconds. From 1 second to 7 days. For a longer run, use `none`. - **``:** `COMMAND`, `CLAUDE_CODE`, `ANTHROPIC`, `OPENAI`, `GEMINI` or `OLLAMA`. The LLM time limit takes the five model runners; retries and the retry delay take all six. A command job's LLM step uses the LLM time limit of its provider. - **Precedence:** the task's or job's own value, then `_`, then ``, then the built-in default. Each view names the source: `task`, `setting:`, `setting` or `default`. - **Machine form:** HTTP JSON carries a time limit or the retry delay as seconds in an `_s` key, a time limit also as the string `"none"`, and retries as a number. In an input, `null` removes the job's own value, so the next layer applies. Show and change the settings with `tidegap limits`: ``` tidegap limits tidegap limits set llm-timeout 1h --runner claude-code tidegap limits set command-timeout none tidegap limits set retries 0 --runner command tidegap limits reset command-timeout ``` A change applies to the next run, with no restart. The tick, the MCP server, the OpenClaw plugin and the Python package read the file each time a run starts. A line that is not a valid limit, such as `TIDEGAP_COMMAND_TIMEOUT=0`, is ignored and the next layer applies; `tidegap limits` lists it with the reason. `tidegap queue add` prints the limit and the retry policy that apply now. The `dispatched` event of each run records each setting and its source; `tidegap queue show`, `check_queue_status` and `tidegap jobs show` print them. A time limit is the whole limit of an API call: each call gets its own HTTP timeouts from it (none for `none`), so no hidden ceiling, such as Node's 300-second wait for response headers, ends it earlier. Three cases keep that 300-second wait: an SDK package too old to take per-call fetch options (the `openai` package before version 5, older `@anthropic-ai/sdk` releases), a host that replaced the global `fetch` (an instrumentation layer), whose `fetch` is used as is, and the OpenClaw plugin's own model calls (a provider key in its config, Gemini, Ollama), since its bundle leaves out the HTTP client that sets the timeouts. Calls through the OpenClaw runtime do not use it. A task that goes to a provider Batch API (a deadline over 24 hours away) has no time limit: the provider owns the hour of a Batch run, so its own `llm_timeout` is not applied there, and the reply that queues it says so. **`none` holds other tasks.** The tick runs due tasks one at a time, so a run with no limit holds every other due task while it runs. `tidegap queue cancel ` stops it within 15 seconds, and `tidegap status` names a run that has run longer than two tick intervals. A job or a queued command task stored by an older version holds the old defaults (5 minutes for a command, 10 minutes for an LLM step). Those values follow the settings; a value you set yourself stays the task's own. ### Retries A failed run of any runner, a one-off shell command included, is tried again by its retry policy: - **When:** the failure must be one a retry can fix: a time limit, a command or Claude Code exit, a 429 or 5xx after the call's own quick resends, a 408 or 425 (by the task retry only), a network error, an errored or expired Batch, or a run a stopped tick interrupted. A permanent failure never retries: a refused request (a 4xx other than 408, 425 and 429, a content refusal), missing setup (a key, a secret, a folder, the `claude` binary), a spent budget, an LLM step that failed after its command ran, or a Batch submit a forced stop cut. - **How often:** up to `retries` times. Retry k starts no earlier than the retry delay times 2^(k−1) after the failure (30, 60, 120 minutes with the defaults), then at the cleanest hour before the deadline. A retry that cannot start before the deadline is not made, and the error ends with `(no time left before the deadline for a retry)`. - **What you see:** each failed attempt that is tried again writes an `attempt_failed` event with its attempt number, failure class, first error line and the next attempt's time; the task is `scheduled` again. Only the final outcome sends a notice, wakes a session or writes a result file; a final failure after more than one attempt ends with `(after N attempts)`. - **Commands:** a one-off command retries like every runner, so it may run twice. For a command that must not run twice, queue it with `--retries 0`, or set `tidegap limits set retries 0 --runner command`. `tidegap queue add --runner command` prints the retry line before the first run. - **Billing:** a retried API call after a network error or a time limit may be billed twice: the provider may have accepted the first call. - **By hand:** `tidegap queue retry ` (or `retry_task`, `/tidegap:retry`) runs a failed task again as attempt 1 of a new count, whatever its deadline. A job run is refused: the job retries its runs itself, by the same policy, as separate runs of its slot. ## Jobs A job is a recurring task that floats. You give it a cadence and an optional window of hours. Each run goes to the cleanest grid hour inside its period, not to a fixed clock time. Cron cannot do this. ### What a job is A job is one of two kinds: - **Prompt job.** Each run sends the prompt to the provider, started fresh. Tools are `none` (default), `files` (Read, Grep, Glob) or `web` (WebSearch, WebFetch). - **Command job.** Each run executes a shell command, with an optional LLM step over its output. The LLM step has no tools. Each run is an ordinary task with a carbon receipt. `tidegap verify ` checks it. A job keeps one pending run at a time. When a run ends, the next one is planned. A job has no region of its own: each run uses the [default grid region](#region) of the computer that ticks it. Create and edit jobs on the **Jobs** page (`tidegap ui`, then Jobs) or with [`tidegap jobs`](#cli-commands). Agents create prompt jobs only, through `schedule_task` with `repeat` (see [Agents](#jobs-agents)). ### Cadence and windows | Cadence | Meaning | | --- | --- | | `daily` | Once a day. | | `weekdays` | Once on each day from Monday to Friday. | | `weekly` | Once on each listed day, for example `mon,thu`. | | every N hours | At least every N hours, N from 2 to 168, counted from the last run. | A window (`HH:MM-HH:MM`, local time in the job's time zone) limits the hours a run may use. It can cross midnight: `22:00-06:00`. A window works with `daily`, `weekdays` and `weekly`. "Every night" is `daily` with the window `22:00-08:00`. Without a window, a run may use any hour of its period. Each job shows its guarantee in one sentence. These are the shapes: - `runs every day between 22:00 and 08:00` - `runs once every weekday (Mon-Fri), any time of day` - `runs every Mon and Thu between 09:00 and 17:00` - `runs at least every 6 h, never sooner than 3 h after the last run` A job with a window, `weekdays` or `weekly` is tied to the calendar: it runs once in each slot. A job with `daily` or every N hours and no window is tied to its last run: the next run is due one period after the last started, and never sooner than half a period after it. Daylight saving time moves a local time that does not exist to the next valid minute. A repeated local time uses its first instant. ### Commands A command job runs with `/bin/sh -c`. Only you write the command, on the page or in the CLI. Agents cannot create command jobs. - The command runs as you. It can read every file you can read, including Tidegap's own secrets files. Treat a command like a line in your crontab. - The environment holds only `PATH`, `HOME`, `USER`, `LOGNAME`, `SHELL`, `LANG`, `LC_*`, `TMPDIR` and `TZ`, plus the secrets the job names. - Output is capped (10 MiB); errors keep their last 4 KiB. The time limit is 30 minutes by default (see [Run limits](#limits)). At the limit, the command's process group is stopped. - A stopped tick stops its commands. On SIGTERM or SIGINT, each command's process group gets SIGTERM, then SIGKILL after a short grace. A cancel of a running task stops its command or `claude -p` run the same way within 15 seconds, and the tick goes on to the next due task. A tick that exits sends SIGKILL at once. `tidegap tick --daemon` then dispatches nothing more and exits; rows it did not reach stay queued for the next tick. A `claude -p` run in flight finishes first. A second SIGINT or SIGTERM, at least 1 second after the first, ends `tidegap tick --daemon` at once, and the row in flight ends by what it was doing. A provider call fails as interrupted, and its command or `claude -p` process group is killed. A Batch poll goes back to `submitted` with its batch id, and the next tick polls it again. A Batch submit fails with an error that says the provider may have accepted the batch. No retry runs that row again, the job's own retry included: check the provider's batch list, and enqueue the task again only if no batch exists. - Some processes outlive the cap. A background child (`cmd &`) keeps running after the command exits normally. A child that leaves the process group with `setsid` is not stopped at the cap. A tick ended by SIGKILL or a crash runs no handler, so its running command goes on until it ends. The next tick that holds the tick lock frees a row that such a tick left `running`, a one-off task's row too, once that tick's process is gone (checked by its pid and start time). A job's row without that record (from an older version or another host), or whose tick's start time cannot be read, is freed by the job sweep once it is older than the time limits its run started with (a Batch row counts from its deadline, and `none` adds nothing there: no LLM time limit applies to a Batch run); any other run with no time limit (`none`) is freed only by the tick lock rule. A Batch row that has a batch id goes back to `submitted` and is polled again. Any other row fails as interrupted, a Batch submit included: the provider may have accepted that batch, so check its batch list before you enqueue the task again. - Exit code 127 means the shell did not find the command. The daemon has a short `PATH`, so use an absolute path. - The LLM step reads the scrubbed output (the last 200 KiB) with a prompt you write. If a usage limit defers that step, the run goes back to the queue and the command runs again on the deferred dispatch. ### Secrets A command that needs a password gets it as an environment variable. Store the value once: ``` tidegap jobs secrets set IMAP_PASSWORD ``` The value is read from standard input (a hidden prompt in a terminal). It is never an argument and never printed. The page and the CLI list names only. A job names the secrets it needs with `--secret `. Names start with an upper-case letter, then upper-case letters, digits and `_`. Tidegap scrubs every secret value out of the output, the errors, the receipt and the messages. The scrub matches exact values (at least 4 characters). A command that prints a changed form of a secret, such as its base64 or URL-encoded text, is not scrubbed. Do not print secrets. ### Caps and auto-pause Each run has caps: a command time limit (30 minutes), an LLM time limit (30 minutes for `claude-code`, 10 minutes for an API provider), an LLM budget (1 USD) and an output cap. Change them for one job with `--command-timeout`, `--llm-timeout`, `--retries`, `--retry-delay` and `--budget`, or for every job and task with `tidegap limits` ([Run limits](#limits)). A time limit takes `none` for no limit. A job without its own time limit follows the setting at each run. The summarize budget is an estimated ceiling: the cost is estimated from tokens, so a model with costly output can go a little over it. By default a failed run gets one retry 30 minutes later, when its slot has time left. The job's retries and retry delay, or the settings, change that ([Run limits](#limits)): retry k waits the delay times 2^(k-1), so with `--retries 3` the slot gets runs `~1r`, `~1r2` and `~1r3`. A failed command runs again in a retry; `--retries 0` runs it once. A run whose LLM step fails after the command ran gets no retry, so that command does not run twice in one slot. Nor does a permanent failure: a missing secret, folder or key, a refused request. After three failed slots in a row, the job pauses. The notice that it paused replaces the failure alert of that run. Fix the cause, then resume the job. ### After sleep A job needs `tidegap tick` to run. When the computer sleeps through a slot, the run is due at the next tick. The next run counts from that run's start. There is no backlog: a job that missed three days runs once. Resume starts a job again from now. ### Notifications A job's `--notify` level has three values: - `every` (default): each run sends its result. - `failures`: only a failed run sends a message. - `summary`: results appear only in the [daily summary](#notifications). Channels get the same events as for any task. Telegram also lists jobs with `/jobs`. ### Agents and schedule_task `schedule_task` with `repeat` creates a job. The agent sends the prompt, and each run starts fresh in the same project. | Parameter | Meaning | | --- | --- | | `repeat` | `daily`, `weekdays`, `weekly` or `every_n_hours`. | | `every_hours` | N for `every_n_hours`, 2 to 168. | | `days` | Days for `weekly`: `mon` to `sun`. | | `window` | Local hours, `HH:MM-HH:MM`. | | `time_zone` | IANA zone. Default: this computer's. | A job rejects per-task options such as `region`, `carbon_budget_g` and `candidates`. End a job with `cancel_task` and `series: true`. The older `repeat: quota_reset` (with `deadline_kind: quota_reset`) still starts a series that follows the quota reset. It is not a job. To make your agent choose Tidegap instead of cron, open the **Agent rules** tab in the [install box](/#install) on the home page, or run `tidegap jobs snippet --host claude|opencode|codex|cursor|gemini`. The Claude Code plugin also asks before a command that edits the crontab, loads a launchd job or enables a systemd user unit, and hints at `schedule_task` when a prompt asks for recurring work. ### Surfaces The Jobs page, the Mac app, the browser extension and Telegram (`/jobs`) show jobs and can pause, resume and run them. Only the page and the CLI create and edit jobs. See [UI & apps](#apps) and [Telegram](#telegram). The page's API takes at most 60 job writes (create, edit, remove) and 20 previews per minute for each token. Over that, it answers 429 `rate_limited` with `retry_after_s`. ### macOS and `~/Documents` macOS asks once before a program reads `~/Documents`, `~/Desktop` or `~/Downloads`. The prompt belongs to the daemon's `node`. If nobody answers it, the command waits and then stops at its time limit. Tidegap never opens these folders to check. On macOS, a run that stops at its time limit gets a hint when it printed nothing for its final 2 minutes (or for the whole run, when the limit is shorter), or when it printed no stderr and its `--cwd` or command names one of these folders. The first line of the failure reason ends with `macOS: if it reads a protected folder, allow node in Files & Folders`. The second line names the daemon's `node` path. The hint is a condition, not a finding: a command can be quiet for other reasons. If the script reads one of these folders, open System Settings, Privacy & Security, Files & Folders, and allow that `node`. Or keep the folder the script reads outside these folders. A retry before you allow the access hangs again. `tidegap install` on macOS warns when the daemon's `node` or entry script (or `TIDEGAP_BINARY`) is in one of these folders or in iCloud Drive (`~/Library/Mobile Documents`): install the CLI with `npm install -g @tidegap/cli`, or keep the runtime outside these folders. ### SSH keys The daemon runs under launchd or systemd and has no `SSH_AUTH_SOCK`. A command that needs `ssh` or `git` over SSH cannot reach your agent. Use a key without a passphrase that only this command uses, or point the command at the socket itself. ### Mixed versions and the Python ticker Upgrade every ticker that shares the ledger before you add command jobs. An older `tidegap tick`, or a Python ticker, cannot run a `command` row. Both tickers leave a row they cannot serve queued for another ticker, but they hold different sets. The Python ticker (`tidegap` on PyPI) never runs a job: it holds every job run, whatever its provider, and every `command` or `claude-code` row it has no adapter for. `tidegap tick` holds a `command` row when it has no command runner, and any other row only when it has no LLM provider at all; with a provider, a row for a provider it lacks fails. Each Python tick lists the rows it holds in `TickResult.held_for_node`, the active jobs in `TickResult.active_jobs` and the last Node tick in `TickResult.node_last_tick_at`, and logs one warning when it holds a row or a job is active. If it cannot read the ledger after its sweeps, `TickResult.node_report_error` names the error and `held_for_node` lists the rows it held at the start of the tick. Jobs run only on the Node daemon, with their limits: run `tidegap install`, then check `tidegap status`. Python `expedite_task` and `retry_task` refuse a job run. To run a queued or scheduled run now, use `tidegap queue run-now `; to run the job again, `tidegap jobs run `. A job retries a failed run itself. ## FAQ Short answers. Each one names the file it rests on. ### Is it safe for my agent to install? Yes. Tidegap is open source (Apache-2.0), and install.md is plain text that the agent can read before it runs anything. The install adds one MCP server entry to the host's config and makes no other system changes. ### Does it send my data anywhere? Nothing goes to Tidegap's authors. Tasks and receipts stay in `~/.tidegap/queue.db` on your machine. Tidegap fetches grid forecasts from public grid feeds, and a task's prompt goes only to the AI provider you configured, when the task runs. ### Do I need an account? No. There is no Tidegap account. Provider and grid API keys are optional and stay in your own config. ### Do tasks run while my computer sleeps? Not while it is asleep. On macOS, `tidegap install --laptop` adds a wake event 30 s before a task's window. Otherwise the tick runs every due task on its first pass after the computer wakes. ### How much carbon does it save? It depends on the region, the hour and the deadline. In one real GB run the forecast peak was 183 gCO2/kWh and the chosen window 88 gCO2/kWh. Every receipt records the intensity at dispatch, and the per-model energy estimates may be off by ±50%. ### Which providers and grid feeds does it use? Tasks go to Anthropic, OpenAI, Google Gemini or a local Ollama server. Grid data comes from National Grid ESO (GB, no key), EIA, WattTime, ENTSO-E and Electricity Maps. A region with no live feed uses a deterministic mock curve. ### What if the deadline is too close? When no forecast hour fits between now and the deadline, Tidegap runs the task at once rather than miss the deadline. If you set a carbon budget that no hour meets, the task fails with a budget error instead. ## Agent handoff A Claude Code session can hand a task to Tidegap and get the outcome back in the same session. Nobody has to relay it. This page covers how the session queues the work, how it hears that a task finished, how it watches or waits for a task, and what it may read from the ledger. ### Queue a task `tidegap queue add` queues one task from a shell or the session's Bash tool and prints the task id alone on the first line: ```bash tidegap queue add --runner claude-code --cwd . --profile read --result-path ./review.md --by 2h "Review the diff on this branch" tidegap queue add --runner command --cwd /tmp --by 10m "echo hello > /tmp/tg-hello.txt" ``` - The text is the prompt, or the shell command of `--runner command`. `-` reads it from stdin (at most 1 MiB; a command at most 32,000 characters). A command is kept like a prompt: when the task completes or is cancelled, key-shaped secrets in it are redacted in the ledger. - Runners: `claude-code`, `anthropic`, `openai`, `gemini`, `ollama` and `command`. Without `--runner` it is `claude-code` inside a Claude Code session, else `anthropic`. - `--by` is required: a duration (`30m`, `2h`, `3d`, `1w`), an ISO-8601 time, or `quota-reset` (with `--quota-provider