agent-wake.

Wake agents from events. An event inbox remembers the work, a small wake watcher starts a fresh agent, and durable progress means a sleeping agent misses nothing.

GitHub → Try it in five minutes → The essay →

The problem

Agents today either poll (burn tokens asking “anything new?”) or hold always-on processes waiting for webhooks (fragile, needs a public URL, loses events on crash). agent-wake unifies push and pull: events live in a durable log, agents hold cursors, and a wake is just a hint that something is waiting. Push becomes a latency optimization over pull — so delivery needs no exactly-once machinery.

Three primitives

⚡ Event source

events ↓

▣ Event inbox

🔔 doorbell ↓

◷ Wake watcher

starts ↓

◆ Working agent

↖ reads work · records progress

Event inbox (hub)An append-only log of typed events with stable IDs, plus wake rules. One tiny process (or a service). The log is the truth.

Wake rule and bookmark (subscription + cursor)Which events matter, how far the agent got, and how often it may wake.

Doorbell (thin ping){hub, subscription, cursor, pending} — never a payload. It only tells the wake watcher that work is waiting.

Quickstart

# install (Node ≥ 20, zero dependencies)
npm install -g github:nicolaerusan/agent-wake

# terminal 1 — the hub: durable event log + mailbox
agent-wake hub

# terminal 2 — visible demo, no AI account required
agent-wake watch --echo

# or wake a real agent CLI on every event
agent-wake watch --claude    # Claude Code
agent-wake watch --codex     # ...or Codex
agent-wake watch --cmd 'node my-agent.mjs'   # ...or anything

# terminal 3 — play the world: emit an event
agent-wake emit task.created --data '{"title":"hello"}'

The wake watcher long-polls the event inbox over an outbound connection (NAT-proof, no public URL). When the doorbell rings, it starts a fresh working agent. Today that can be claude -p, codex exec, any local command, or a BB thread. Desktop and hosted services need product-specific adapters. See the concrete architecture guide.

Claude Code & Codex

# headless claude needs permission to curl the hub
agent-wake watch --claude -- --allowedTools 'Bash(curl:*)'

# codex needs network enabled in its sandbox
agent-wake watch --codex -- --sandbox workspace-write \
  -c 'sandbox_workspace_write.network_access=true'

BB

Using bb? The plugin wakes BB threads instead of CLI processes — one thread per ping, with your standing instructions in the prompt:

bb plugin install https://github.com/nicolaerusan/agent-wake --plugin agent-wake
bb wake emit task.created '{"title":"hello"}'

Why thin pings?

Polling is always a valid fallback — push is just lower latency, so nothing breaks when a webhook is missed.
At-least-once processing with durable progress — the cursor at the event inbox is the truth, not the doorbell; consumers use event IDs to make external writes idempotent.
Agents can be local processes or hosted jobs — the wake target is a small wake watcher; it can start claude -p, codex exec, a BB thread, a container, or a future cloud adapter.
Wake economics live in the subscription — min intervals and coalescing keep a chatty event source from becoming a token firehose.

Webhooks in, MCP out

Anything can send events in, and any MCP-capable agent can read them out — without waking a thing:

# receive webhooks from the outside world (auth required; localhost by default)
agent-wake ingest --token hunter2 [--github-secret "$SECRET"]
curl -X POST localhost:7788/hook/ci -H 'X-Wake-Token: hunter2' -d '{"status":"failed"}'

# let an assistant you are already talking to scan what arrived
claude mcp add agent-wake -- agent-wake mcp --read-only

The bridge derives the event type and source from the authenticated route, so a caller can never claim to be someone else, and unauthenticated requests never reach the inbox. The MCP server is ordered by authority: reading is always allowed, emitting is on by default, and wake_ack — the one call that can silently destroy work — stays off unless you ask for it.

Security, honestly

The reference hub is unauthenticated localhost plumbing — don’t bind it to the internet. Event data is prompt-injection surface, filters currently gate wakes but not reads, and cursor acknowledgements still need authentication and strict bounds. The wake watcher must use its configured event inbox rather than trust a URL inside the doorbell. Capabilities, subscription-scoped reads, source credentials, wake budgets, parking, and signed push are roadmap items, not shipped protections. The full threat model and shipping order live in SECURITY.md.

Prior art it steals from: CloudEvents (envelope) · Standard Webhooks (signing) · WebSub (subscribe/deliver) · ActivityPub (inbox as identity) · SMTP/MX (standardize addressability, not hosting).