npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@tidegap/cli

v0.21.0

Published

The tidegap command: runs queued Tidegap LLM tasks at the cleanest grid hour before their deadline.

Readme

@tidegap/cli

Renamed from @ebb-ai/cli in 0.18.0. The ebb command and the EBB_* variables were removed in 0.19; use tidegap and TIDEGAP_*. If npm reports EEXIST on install, run npm uninstall -g @ebb-ai/cli first. See Renamed from Ebb AI.

The tidegap command: runs your queued Tidegap tasks when their cleanest grid hour arrives.

tidegap drains the Tidegap task queue on a timer. A task that your agent deferred runs at the lowest-carbon hour before its deadline, also when no agent session is open.

  • tidegap tick dispatches every task that is due. tidegap install writes and loads it as a launchd agent (macOS) or systemd timer (Linux); tidegap status says whether queued tasks will run.
  • tidegap queue list and tidegap receipts list show queued tasks and their carbon receipts.
  • tidegap verify <task-id> checks a receipt's Ed25519 signature offline.
npm install -g @tidegap/cli
tidegap install                   # run `tidegap tick` on a schedule (picks --laptop on a Mac with a battery)
tidegap status                    # will queued tasks run? exit 1 when not
tidegap queue list                # what is waiting, and for which hour
tidegap tick --region GB          # dispatch what is due now
tidegap receipts list             # one carbon receipt per completed task
tidegap verify <task-id>          # check the receipt signature

Proof: one real GB run, 2026-09-30 (tidegap tick + tidegap verify). Forecast peak 183 gCO2/kWh vs recommended window 88 gCO2/kWh, about 52 % lower for this run only (forecast, projected). The task had a 5-minute deadline and ran at once; its receipt records 158 gCO2/kWh (measured). Raw output: https://github.com/tidegap/tidegap/tree/main/docs/examples/2026-09-30-GB-tick

Commands

tidegap tick           — drain due tasks via provider adapters; one OS notification per finished task (--no-notify, or TIDEGAP_NO_NOTIFY=1)
tidegap install        — write and load the daemon: launchd (macOS), systemd (Linux); print a schtasks template (Windows). --laptop | --server (default: by battery), --no-load
tidegap status         — will queued tasks run? daemon, last tick, runners, pending tasks; exit 0 ready, 1 not (--json)
tidegap queue list     — print tasks (--unread, --kind absolute|quota_reset, --session <id|current>, --json, --hook)
tidegap queue add      — queue one task: a prompt (--runner claude-code|anthropic|openai|gemini|ollama) or a shell command (--runner command); --by <when|quota-reset> required; --cwd, --profile read|web|none, --model, --result-path, --not-before, --after-limit-reset, --command-timeout, --llm-timeout, --retries, --retry-delay, --wake, --json; prints the task id first, the time limit and the retry policy that apply
tidegap queue show     — print one task's prompt (or command), runner, folder, profile, tools, time limits, retries and failed attempts, result file, result and receipt; marks it read
tidegap queue unread   — mark a task unread again
tidegap queue events   — print one task's events with their ids (--json, --after <event-id>)
tidegap queue wait     — block until a task ends (and its result file is written) and print its result; exit 0 completed, 1 failed, cancelled or result file not written, 2 usage, unknown id, unreadable ledger or outcome not written to stdout, 3 timeout (--timeout, --json, --events)
tidegap queue notices  — print and record the notice of this session's finished tasks (--hook for the plugin's prompt hook, --peek to only print, --wait --rewake for the plugin's Stop hook: wait for a --wake task, exit 2 with the notice)
tidegap queue cancel   — cancel a pending task (--series ends a repeating series)
tidegap queue retry    — retry a failed task, a command task included: due now, the next tick runs it as attempt 1 of a new count
tidegap jobs          — recurring jobs that float to the cleanest hour of each period: list | show | add | edit | pause | resume | run | remove | history | secrets | snippet
tidegap limits        — run limits and retries in ~/.tidegap/config: show | set <command-timeout|llm-timeout|retries|retry-delay> <value> [--runner <r>] | reset; a change applies to the next run
tidegap queue later    — push a task later, never earlier: --until <+2h|tonight|tomorrow|tomorrow HH:MM|HH:MM|ISO|after-limit-reset>, --preset <1h|tonight|tomorrow_morning|after_limit_reset>, or --delay <minutes>; --reset-at <HH:MM|ISO>
tidegap queue reschedule — move a task: --at <ISO>, --day <yyyy-mm-dd>, or --after-limit-reset; --by <2h|ISO> is an alias of `later --until`
tidegap queue run-now  — mark a task due; the next tick runs it
tidegap queue reply    — continue a completed task as a new task (--by, default 1h)
tidegap receipts list  — print carbon receipts for completed tasks
tidegap stats          — local-only personal-impact stats from the queue ledger
tidegap usage          — Claude Code 5-hour and weekly limits and their resets (--json)
tidegap usage hook     — Claude Code statusLine command that records the limits (-- <your statusline command>); stored guarded, so your own command still runs when this install is gone
tidegap usage install-hook — register the hook as the Claude Code statusLine, wrapping your own (--dry-run, --remove)
tidegap verify         — verify the Ed25519 signature on a carbon receipt
tidegap register-wake  — schedule a macOS wake event 30s before a task
tidegap ui             — local task page: agenda, journal, timeline, task detail and actions, and the Jobs view (127.0.0.1 only; port 47821 by default)
tidegap clients add    — mint a token for the browser extension or the Mac app (--name, --kind extension|macos, --json)
tidegap clients list   — list client ids, kinds and names (never tokens)
tidegap clients revoke — remove a client; its token stops working on the next request
tidegap channels add   — pair a Telegram chat (`add telegram`, one-time code) and load the listener unit (--no-load)
tidegap channels list  — list the paired channels (--json)
tidegap channels remove — remove a channel; the last telegram channel unloads the listener
tidegap channels serve — the Telegram listener the unit runs (--once: one poll cycle)

Run tidegap <command> --help for flags.

tidegap clients add prints a tgc_… token once; store it then. The registry ~/.tidegap/ui-clients.json (mode 0600) keeps only the token's SHA-256. A client token works only against tidegap ui on 127.0.0.1, survives restarts and is never accepted on the client-management routes. The contract the extension and the Mac app code against is docs/spec/ui-client-api.md.

The write commands and tidegap ui change the ledger only; tidegap tick (or the OpenClaw loop) runs the task, and each command prints when the last tick ran. --day and a repeating task's next occurrence can lie beyond the 72-hour forecast. Such a task waits at a fallback hour (its current time of day, in the new day) until a tick re-plans it once the forecast covers the day. If no tick runs in that time, it runs at the fallback hour without a carbon choice.

Quickstart — keep tasks alive across laptop sleep

tidegap install --laptop
# writes and loads the agent, then prints the `tidegap status` lines

tidegap install resolves the daemon's invocation at install time to the exact node interpreter plus the real tidegap entry ([process.execPath, realpath(argv[1])]), so the launchd job / systemd unit does not depend on a bare PATH or a #!/usr/bin/env node shebang. Set TIDEGAP_BINARY to override with a single wrapper executable.

Secrets

Scope: the environment variables below configure this CLI (and the @tidegap/mcp server, which reads the same set). The CLI reads them at its own entry point and injects them into @tidegap/core, which is environment-pure. The @vitalini/tidegap OpenClaw plugin reads no environment variables at all — configure it under plugins.entries.tidegap.config in your gateway config (anthropicApiKey, openaiApiKey, geminiApiKey/googleApiKey, ollamaHost, ollamaModels, eiaApiKey, electricityMapsApiKey, entsoeSecurityToken, wattTimeUsername/wattTimePassword, carbonBudgetG, carbonBudgetWindow). OpenClaw resolves the "${ENV_VAR}" shorthand in those fields, so you can keep exporting the same variables and let the gateway read them on the plugin's behalf.

Provider (and grid-feed) API keys live in ~/.config/tidegap/env — KEY=VALUE lines, created 0600 with a commented template on first tidegap install. Both tidegap tick (loads it at startup) and the systemd unit (EnvironmentFile=) read it, so launchd, systemd, and manual cron all pick up keys the same way:

ANTHROPIC_API_KEY=sk-...
OPENAI_API_KEY=sk-...
GEMINI_API_KEY=...        # or GOOGLE_API_KEY — Gemini (generativelanguage.googleapis.com)
OLLAMA_HOST=http://localhost:11434   # local Ollama; presence opts the ollama provider in
TIDEGAP_TELEGRAM_BOT_TOKEN=123:abc   # a bot used only by Tidegap; TELEGRAM_BOT_TOKEN is the fallback

Settings → Integrations in tidegap ui (and the Mac app) writes the Telegram token to this file for you, pairs the chat with a code or a QR code, and loads the listener unit; tidegap channels add telegram is the terminal way.

Providers: anthropic and openai are batch-capable (their tasks can auto-route through a 50%-cheaper Batch API — projected, provider list price); gemini and ollama are sync-only. Gemini reads GEMINI_API_KEY, falling back to GOOGLE_API_KEY. Ollama is local and keyless — set OLLAMA_HOST (default http://localhost:11434) to enable it; optionally list local model ids in OLLAMA_MODELS (comma-separated) so schedule_task can infer the ollama provider from a bare model name.

tidegap tick prints a loud warning when pending tasks need a provider key that is not set. (Ollama is keyless, so a pending Ollama task is never flagged.)

Platform support

| Platform | Daemon install | Wake-from-sleep | | --- | --- | --- | | macOS | launchd plist (tidegap install) | pmset schedule wake via tidegap register-wake / the --laptop helper | | Linux | systemd user .service + .timer (tidegap install) | rtcwake via tidegap register-wake / the --laptop helper | | Windows | not auto-installed — tidegap install prints a ready-to-paste schtasks command; run tidegap tick under Task Scheduler or nssm yourself | not supported (use Task Scheduler's "wake the computer" option) |

Wake events (pmset / rtcwake) need root. When not running as root, tidegap register-wake prints the exact sudoers line to pre-authorize the command without a password prompt.

Develop

From the root of a clone of https://github.com/tidegap/tidegap:

pnpm install
pnpm --filter @tidegap/core build
pnpm --filter @tidegap/cli build
node packages/cli/dist/index.js --help