Agents
You don't write code for any agent. Wakeshift recognises which agent is subscribing and wakes it the way that agent can be woken. Clients that speak MCP Events, such as ChatGPT, subscribe natively; every other agent subscribes with the subscribe_events tool, or through a tool of yours that calls event.subscribe.
How each agent wakes
| Agent | Wakes while idle | Install | What the user approves | Typical wake |
|---|---|---|---|---|
| Claude Code | Yes | None (hooks are an optional upgrade) | A background monitor, when the agent first starts watching | Seconds |
| Codex | Yes | Once | Trusting the new hook (/hooks, then t) |
Seconds |
| Cursor (CLI and IDE) | Yes | None (hooks are optional) | Cursor may ask to allow a background command | Seconds |
| Cursor cloud agents | No: occurrences arrive with the agent's next call to a Wakeshift tool | None | Nothing | — |
| ChatGPT (Work chats) | Yes: each occurrence starts a run in the chat | None | The user asks ChatGPT to monitor the event, in a Work chat | Slower: each one starts a new run |
| GitHub Copilot CLI | Yes | None (hooks are optional) | One "Yes" each time it goes back to waiting, so once per wake, unless copilot runs with --allow-all-tools (which approves every tool) |
Seconds |
| opencode | Yes | Once | Nothing; restart opencode after the install | Seconds |
| Antigravity CLI | Yes | None (hooks are optional) | agy may ask to allow a background command |
Seconds |
| OpenClaw | Yes, while the gateway runs | Once | Nothing; on a gateway that listens beyond this computer, the installer asks first | Seconds |
| Hermes Agent | Yes, while Hermes runs (its API server or CLI) | Once | Hermes may ask to approve the install command | Seconds |
| Grok Bot | Only while it's waiting for events: it waits in the foreground, and talking to it interrupts the wait | None | Nothing | Seconds, while waiting |
| Goose, Cline | No: occurrences are held, and arrive when the agent next calls subscribe_events or list_subscriptions |
None | Nothing | — |
| Any other MCP client (your own, or one Wakeshift doesn't know) | Yes, if it can run a command in the background and is told when it exits; otherwise occurrences are held for its next call | None | Nothing | Seconds |
"Seconds" is the time to the agent's first words; most of it is the model starting its turn.
Wakeshift recognises agents from what their MCP clients send. Where calls look alike (Grok Bot and Cursor's cloud agents call as Cursor does), the agent says which program it runs in, and Wakeshift uses that only to choose between the programs the call could be.
The one-time install
Where an agent needs an install, the flow is the same for every agent:
- Your tool's result tells the agent that wake-ups need a one-time install.
- The agent asks its user. It runs the install only if they agree.
- The installer doesn't ask again. It changes only the files described below, keeps a backup of each one it edits, and then prints what it changed and the agent's own trust step, if it has one.
- Once it's running, the agent sees a note that starts with
Wakeshift: connected(for Codex,Wakeshift connector: connected).
The install command has this shape:
curl -fsSL https://app.wakeshift.ai/install/<agent>.sh | shIt puts wakeshift in ~/.wakeshift/bin, trusts only this Wakeshift, and adds what the agent needs to its settings. OpenClaw's and Hermes Agent's installers run where the agent runs (in its container, if it's in one) and add Wakeshift's plugin. OpenClaw's plugin turns on OpenClaw's own hooks endpoint, with a token of its own and for the conversations that connect through Wakeshift only; on a gateway that listens beyond this computer, the installer asks first, because that endpoint is reachable wherever the gateway is. Each installer leaves the rest of the agent's settings as they were. The script checks the download against a SHA-256 written into the script; both come from the same Wakeshift, so this catches a broken download, not a replaced one.
Trust steps
| Agent | After the install |
|---|---|
| Codex | Type /hooks and press t to trust the new hook. |
| Claude Code | Nothing to approve. In a folder Claude Code hasn't trusted yet, choose "Yes, I trust this folder" when it asks. |
| Cursor | Nothing to approve. Start a new chat, or restart cursor-agent. |
| GitHub Copilot CLI | Restart copilot. |
| opencode | Restart opencode. |
| Antigravity CLI | Restart agy. |
| OpenClaw | Nothing to approve, and no restart. The plugin starts with the next turn, so send any reply once it's installed. |
| Hermes Agent | Nothing to approve, and no restart. The plugin starts with the next turn, so send any reply once it's installed. If the installer couldn't enable it, run hermes plugins enable wakeshift where Hermes runs. |
Updates
Wakeshift's hooks and plugins report their version. When Wakeshift needs a newer one, your tool's result tells the agent to ask its user to update, with the same install command; until then, events are held for your tools' results. Running the install again replaces the hooks or plugin and keeps the agent's settings and connected conversations.
Uninstall
~/.wakeshift/bin/wakeshift uninstall --harness <agent><agent> is codex, claude-code, cursor, copilot, opencode, antigravity or hermes. It removes Wakeshift's hooks (for Hermes, its plugin). For OpenClaw, run curl -fsSL https://app.wakeshift.ai/install/openclaw-uninstall.sh | sh where the gateway runs: it removes the plugin, puts OpenClaw's hooks settings back as the plugin found them, and deletes ~/.openclaw/wakeshift. A settings file is deleted only if the install created it and nothing else has been added to it since.
Agents Wakeshift doesn't know
An agent Wakeshift doesn't recognise is told that its messages are held for it, and is offered an optional way to be woken: if it can run a command in the background and is told when that command exits, it starts the command Wakeshift gives it. The command waits until occurrences arrive, prints them and exits; the agent starts it again, then acts on them. The command is the same every time and runs in any POSIX shell (sh, bash, zsh). An agent that can't run commands this way skips it and gets its occurrences on its next call, as below. Either way, each occurrence arrives once.
Agents that can't be woken
Some MCP clients have no way to be woken from outside. For them, occurrences are held, and arrive, marked as outside information, when the agent next calls subscribe_events or list_subscriptions. To show them in your own tools' results too, spread ...wake.args into those tools' input and pass their results to wake.annotate(call, result). Wakeshift changes no tool or result you don't hand it.