wakehook → your agent

wakehook is a tiny self-hosted service that watches the user's sleep data (Google Health or Fitbit), detects the moment they woke up, and POSTs the user's agent a neutral user.awake event so the morning routine runs itself, at most once per morning. The agent maps that event into a wake or agent action (its native pattern), so wakehook stays vendor-neutral.

This works with OpenClaw and Hermes Agent. They both ingest a webhook and template it. Everything below is shared except step 1, where you pick the agent. Work through the steps in order. Ask the user at the decision points instead of assuming. Do not improvise from the README , these steps are verified.

intent

use wakehook when the user wants automations triggered by sleep data, explicitly mentions wakehook, or asks to "do something when I wake up". the skill installs a self-hosted webhook listener that polls Google Health or Fitbit for sleep transitions, fires once per morning when the user wakes, and POSTs a neutral event to the agent's inbound webhook so the agent can run a morning routine. works with OpenClaw (via mapped hooks) or Hermes Agent (via webhook routes). the entire setup (auth, config, agent wiring) is a one-time cost; after that, wakehook runs as a daemon and fires silently every morning.

inputs

required context:

• user's agent type (OpenClaw or Hermes Agent, not both)
• user's timezone (IANA zone string, e.g., Europe/Brussels)
• user's wake window (time range when they typically wake, e.g., 06:00-10:00)
• user's agent's inbound webhook address and port
• user's agent's webhook auth token or secret (set by user in agent config)

external connections (setup):

• Google Cloud OAuth 2.0 client: requires an existing Google Cloud project with Health API enabled. user must create an OAuth 2.0 client (not an API key; sleep data requires user consent), get the client ID and client secret, and ensure http://localhost:8080/oauth/callback is registered as an authorized redirect URI. store GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, and GOOGLE_REDIRECT_URI in .env.
• OpenClaw gateway (if selected): user must know the gateway host and port (docs example: 127.0.0.1:18789), and have the hooks.enabled: true setting with a strong random hooks.token set. wakehook will POST to /hooks/wakehook with bearer auth.
• Hermes Agent (if selected): user must know the agent's webhook port (docs example: 8644), and have a webhook route named wakehook with a secret field set. wakehook will POST to /webhooks/wakehook and sign with HMAC-SHA256.

infrastructure:

• Bun ≥ 1.3 (mandatory; Node.js will not work): confirm with bun --version. install from https://bun.sh/install if missing.
• persistent storage: ./wake.sqlite (created by wakehook, stores OAuth refresh token and wake history for deduplication).
• network: for poll mode, no inbound URL or port forwarding needed (outbound only). for webhook mode (unverified), wakehook must be accessible publicly over HTTPS.
• continuous runtime: wakehook must stay running (systemd service, Docker container, tmux session, etc.) to detect morning wakes.

procedure

step 1: wire wakehook to the agent (pick OpenClaw or Hermes, not both)

wakehook POSTs the raw user.awake event to the agent's inbound webhook; the agent templates it into a wake action. choose one subsection below (OpenClaw or Hermes). the output of this step is a JSON subscriber config that you will paste into config.json in step 3.

step 1a (OpenClaw only):

• ask the user: "what is the host and port of your OpenClaw gateway?" (typical answer: 127.0.0.1:18789).
• ask the user: "is hooks.enabled set to true in your gateway config?"
• ask the user: "what is your hooks.token (bearer auth)?" (a string they set; if missing, tell them to set one now in the gateway config, e.g., hooks: { enabled: true, path: "/hooks", token: "my-random-strong-token" }).
• in the OpenClaw gateway config, add or update the mapping:

  {
    hooks: {
      enabled: true,
      path: "/hooks",
      token: "<HOOKS_TOKEN>",
      mappings: [
        {
          match: { path: "wakehook" },
          action: "wake",
          wakeMode: "now",
          name: "wakehook",
          textTemplate: "You woke at {{wokeAt}} (slept {{session.durationMin}} min).",
        },
      ],
    },
  }
  

• output (for step 3): the subscriber JSON:

  { "id": "openclaw", "url": "http://<host>:<port>/hooks/wakehook", "headers": { "Authorization": "Bearer <HOOKS_TOKEN>" } }
  

  (replace <host>:<port> and <HOOKS_TOKEN> with the values from above).

step 1b (Hermes Agent only):

• ask the user: "what is the port of your Hermes webhook service?" (typical: 8644).
• ask the user: "do you have a webhook route named wakehook already?" (if yes, skip the next bullet; if no, tell them to add it now).
• in the Hermes webhook config, add or update the route:

  platforms:
    webhook:
      enabled: true
      extra:
        port: 8644
        routes:
          wakehook:
            secret: "<ROUTE_SECRET>"
            prompt: "The user woke at {wokeAt} (slept {session.durationMin} min). Run the morning routine."
  

  (where <ROUTE_SECRET> is a strong random string the user sets).
• output (for step 3): the subscriber JSON:

  { "id": "hermes", "url": "http://<host>:8644/webhooks/wakehook", "secret": "<ROUTE_SECRET>", "signatureHeader": "X-Webhook-Signature", "signatureFormat": "hex" }
  

  (replace <host> and <ROUTE_SECRET>; or on loopback, drop secret/signatureHeader/signatureFormat and set Hermes's INSECURE_NO_AUTH: true).

step 2: choose poll or webhook mode (ask the user, don't assume)

ask the user: "do you want wakehook to pull sleep data from Google on a timer (poll, recommended, no public URL needed), or wait for Google to push the instant a sleep event lands (webhook, instant but requires a public HTTPS endpoint)?"

• if the user says "poll" or has no preference, continue with poll mode (default, verified end-to-end).
• if the user explicitly asks for "webhook" and can expose a public HTTPS endpoint, note that webhook mode is not yet verified, proceed with caution, and at step 3, set "google": { "mode": "webhook", "webhookAuthToken": "<random>" } instead. also set GOOGLE_WEBHOOK_AUTH_TOKEN=<random> in .env and register a Google Health sleep subscription pointing to your public endpoint + /webhook.
• output: the mode choice (poll or webhook) for step 3.

step 3: create config.json and .env

• create a file config.json in the working directory (where you will run wakehook):

  {
    "dbPath": "./wake.sqlite",
    "source": "google-health",
    "inference": {
      "timezone": "<user's IANA timezone>",
      "windowStart": "04:00",
      "windowEnd": "11:00",
      "minDurationMin": 180,
      "supersedeGapMin": 45
    },
    "google": { "mode": "poll", "pollIntervalMs": 300000, "pollLookbackMin": 720, "pollWindowOnly": true, "pollWindowMarginMin": 30 },
    "subscribers": [
      <insert the subscriber JSON from step 1 here>
    ]
  }
  

  • replace <user's IANA timezone> with the user's timezone (e.g., Europe/Brussels, America/New_York). confirm this is the timezone where the user sleeps and wakes, not their travel timezone.
  • the subscribers array should contain exactly one object: the OpenClaw or Hermes subscriber from step 1.
  • if the user chose webhook mode in step 2, replace the "google" section with:

    "google": { "mode": "webhook", "webhookAuthToken": "<random>" }
    

    (where <random> is a strong random string).
  • leave all other fields (windowStart, windowEnd, minDurationMin, etc.) as defaults unless the user says otherwise.

• create a file .env in the working directory:

  GOOGLE_CLIENT_ID=<client-id>
  GOOGLE_CLIENT_SECRET=<client-secret>
  GOOGLE_REDIRECT_URI=http://localhost:8080/oauth/callback
  

  • ask the user for their Google OAuth client ID and secret (from the Google Cloud project they set up).
  • if the user is running wakehook on a machine other than localhost, adjust the redirect URI to match (e.g., http://192.168.1.100:8080/oauth/callback); confirm this URI is registered on the OAuth client.
  • input: Google client ID, client secret from user. output: .env file with secrets.

step 4: authorize with Google (one-time, interactive)

• input: .env file from step 3, config.json from step 3.
• run: bunx wakehook-auth
• output: a Google consent URL printed to stdout.
• action: open the URL in a browser, sign in as the user, and approve access to sleep data. Google will redirect back to http://localhost:8080/oauth/callback with an auth code.
• result: wakehook stores a refresh token in ./wake.sqlite. the token is reused forever; this step never needs to repeat.
• error handling:
  • if Google returns HTTP 400 Bad Request, the redirect URI is not registered on the OAuth client. tell the user to add http://localhost:8080/oauth/callback (or the custom URI from step 3) to the OAuth client's authorized redirect URIs in Google Cloud Console, then retry bunx wakehook-auth.
  • if the user cannot access localhost:8080 (e.g., running in a remote container), adjust the redirect URI in step 3 and the Google Cloud config to match the accessible address.

step 5: run wakehook as a long-lived process

• input: config.json, .env, wake.sqlite (with valid refresh token from step 4).
• run: bunx wakehook
• or (Docker): docker run -v wakehook-data:/data --env-file .env ghcr.io/robbeverhelst/wakehook
• keep wakehook running 24/7 (systemd service, supervisor, screen/tmux, container orchestration, etc.).
• behavior (poll mode): wakehook polls Google Health every pollIntervalMs (default 300 seconds / 5 minutes). polling is restricted to the morning window only (pollWindowOnly: true, default range 04:00-11:00 in the user's timezone + 30-minute margin). once a wake is detected and fired in a given day, subsequent polls that day skip posting again (idempotent, once per morning). if pollWindowOnly: false, wakehook polls all day (higher cost, usually unnecessary).
• behavior (webhook mode): wakehook listens on /webhook for incoming Google Health push notifications. on a sleep event, it immediately decides if the user woke and posts the event. requires public HTTPS and Google subscription setup (unverified path).
• output: logs to stdout (check them; should see polling ticks in poll mode, or "listening on /webhook" in webhook mode).

step 6: shape the wake action on the agent side (optional, agent-dependent)

by default, the step 1 hook nudges the agent with a raw wake event. to make waking do something (read calendar, summarize messages, report weather, etc.), the user must configure the agent side, not wakehook. wakehook only supplies the trigger (user.awake event); the abilities are the agent's own skills.

OpenClaw:

• the lever is the mapping's textTemplate (for action: "wake") or messageTemplate (for action: "agent").
• example 1 (simple nudge): set the mapping's textTemplate to the instruction:

  {
    match: { path: "wakehook" },
    action: "wake",
    wakeMode: "now",
    textTemplate: "Good morning ({{wokeAt}}). Run the morning routine: review calendar, summarize messages, give weather.",
  }
  

• example 2 (dedicated agent): route to a separate agent that has morning skills installed:

  {
    match: { path: "wakehook" },
    action: "agent",
    agentId: "morning",
    wakeMode: "now",
    messageTemplate: "User woke at {{wokeAt}} (slept {{session.durationMin}} min). Produce the morning briefing.",
    deliver: true,
    channel: "last",
  }
  

Hermes Agent:

• the lever is the webhook route's prompt and optional deliver: (which channel receives the result).

• set the prompt to what you want the agent to do on wake:

  routes:
    wakehook:
      secret: "<ROUTE_SECRET>"
      prompt: "The user woke at {wokeAt}. Run the morning routine: check calendar, summarize overnight messages, report weather."
      deliver: telegram  # optional: send result to Telegram
  

• output: agent-side config (mapping or route) that defines the morning routine task.

• note: do not add a cron trigger alongside this. wakehook is the real wake signal; crons to a fixed time are guesswork. just run the task on the event.

step 7: verify without waiting for morning (optional, but recommended)

• input: wakehook running (from step 5), agent configured (from step 6).
• run: curl -X POST http://localhost:8080/test/replay -H 'Content-Type: application/json' -d '{}'
• expected response: HTTP 200, logs show a synthetic wake event posted to the subscriber.
• agent behavior: the agent receives the wake event and executes the morning routine (in OpenClaw the mapping triggers, in Hermes the route prompt runs).
• success: the agent completes a full morning routine run. if nothing happens, check step 1 (auth token/secret match), step 3 (subscriber URL is correct), and agent logs.

decision points

after step 1 (agent type):

• if the user has OpenClaw deployed, use step 1a (OpenClaw).
• if the user has Hermes Agent deployed, use step 1b (Hermes).
• if the user has both, ask which is the primary agent for morning automations. configure wakehook for that one (you can add a second subscriber to fan out, but start with one).
• if the user has neither, tell them to install one first.

after step 2 (poll vs webhook):

• if the user has no preference or says "poll", proceed with poll mode (recommended, verified, no public URL needed).
• if the user explicitly wants instant detection and can expose a public HTTPS endpoint, use webhook mode (unverified; warn the user).
• if the user is on a home network with no public IP, use poll mode.
• if the user is in a corporate/restricted network with outbound-only access, use poll mode.

during step 3 (timezone and window):

• if the user gives a timezone offset (e.g., "UTC+2"), convert it to an IANA zone (e.g., Europe/Brussels or Africa/Cairo). ask the user to confirm.
• if the user gives a different wake window (e.g., "I wake between 5 and 9 am"), adjust windowStart and windowEnd in the config and increase pollWindowMarginMin if they sometimes wake outside the tight range.
• if the user will travel, ask: will they want the morning routine to run in their home timezone or their travel timezone? (answer affects the timezone field). warn that changing timezone mid-travel requires a config restart.

during step 4 (Google OAuth):

• if the user sees "HTTP 400 Bad Request" from Google, they forgot to register the redirect URI on the OAuth client. walk them through adding it to Google Cloud Console.
• if the user cannot access localhost:8080 from their machine (e.g., running wakehook in a Docker container or remote VM), switch to a custom redirect URI in step 3 (e.g., http://<container-ip>:8080/oauth/callback or a tunnel). update Google Cloud config to match, then retry step 4.

during step 5 (running wakehook):

• if wakehook crashes or logs "network error" when polling Google, check internet connectivity and OAuth token validity. if the token expired (unlikely