Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0

## [Unreleased]

### Fixed

- `@agent-relay/events-shim`: a fresh Claude Code session set up with `setup --claude` is woken by webhook posts again, with nothing to tell it. Since 18.9.0 only a session that had called a `webhooks` MCP tool listened, so a new session never woke. Now the most recently started Claude Code session takes the inbox over at its start (not a `claude -p` run or a compaction), and the older session's listener stops before it takes another post. Calling a `webhooks` tool also takes the inbox over, and when the owning session has closed, the next session's hook takes it. Posts still go to one session only, and no hook listener takes posts while the inbox has a working relay wake link.
- `@agent-relay/events-shim`: `watch_webhooks` now says which Agent Relay agent a relay wake link wakes (`linked_agent`, `linked_at`) and tells the agent to compare that name with its own. Before, every session with the inbox's MCP server read `wake: linked` and was told "each post is injected into this session", so a session could claim a link that targets another agent. `link_relay_wake` takes the linking session's `agent` name and says when it moves the link away from another agent (`replaced_agent`). Links that events-shim makes for Codex and other CLIs woken through the core record the agent's name. The page feed reports it as `agent.wake_agent`. Hosts that persist `WakeTarget.agent` show the name; others report the link without one.
- `@agent-relay/events-shim setup`: each agent CLI keeps the inbox it was set up with (`inboxes` in `~/.config/agent-relay/webhooks.json`), so one machine can give Claude Code and Codex separate inboxes that wake each independently. Before, the last setup's inbox replaced every CLI's. One inbox wakes one session: setup now refuses to add a second waking CLI to an inbox another CLI already uses, or to an inbox linked to another agent, and points to making a separate inbox. `--share-inbox` adds the CLI anyway. When several CLIs share an inbox, setup says which session gets the posts and how that changes.

## [18.10.0] - 2026-11-17

### Added
Expand Down
32 changes: 26 additions & 6 deletions packages/events-shim/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,15 +12,25 @@ It adds the inbox's MCP server to every supported agent CLI on the machine, or o
`--claude`, `--codex`, `--copilot`, `--cursor`, `--droid`, `--amp`, `--opencode`, `--muse`, `--gemini`, `--grok`, `--devin` (or `--cli claude,codex`).
Each tool gets it its own way (`claude`/`codex`/`copilot`/`droid`/`amp`/`gemini`/`grok`/`devin`/`muse mcp add` at user scope; Cursor's
`~/.cursor/mcp.json`, opencode's config file), re-running replaces it, and Claude Code and Codex also get
the `agent-relay-webhooks` skill. The inbox is saved to `~/.config/agent-relay/webhooks.json` (0600). Then tell the
the `agent-relay-webhooks` skill. The inbox is saved to `~/.config/agent-relay/webhooks.json` (0600), per CLI. Then tell the
agent "watch for webhooks". Each post wakes it:

**One inbox wakes one session, not one per agent.** To wake Claude Code and Codex (or any two agents) independently,
make one inbox per agent and run `setup` once per agent with its own MCP URL (`setup '<inbox A>' --claude`, then
`setup '<inbox B>' --codex`). Each CLI keeps the inbox it was set up with. Setup refuses to add a second waking CLI to
an inbox another CLI already uses, or to an inbox linked to another agent's session, unless you pass `--share-inbox`.
When CLIs share an inbox, setup says which session gets the posts: a relay wake link (Codex and the other CLIs woken
through the core) takes every post while it works, and otherwise the hook listeners do.

- **Claude Code, with or without Agent Relay: nothing to do.** `setup --claude` also installs SessionStart and Stop
hooks (`async`, `asyncRewake`) in `~/.claude/settings.json` that run `events-shim listen --hook`. It waits for the
next post and exits 2 with it, which wakes the idle session with the post; each turn's Stop hook re-arms it. One
listener per session, and none for a closed session. The hooks run in every Claude Code session, but only a
session that used the `webhooks` MCP (its transcript shows a `watch_webhooks`, `link_relay_wake`,
`wait_for_webhook`, `get_webhook_events`, `ack_webhook_events` or `release_webhook_events` call) listens. While the inbox has a working relay wake link
listener per session, and none for a closed session. The hooks run in every Claude Code session, but the inbox
wakes one: the most recently started session takes it over at its start (not a `claude -p` run or a compaction),
and the older session's listener stops before it takes another post. A session that calls a `webhooks` MCP tool
(`watch_webhooks`, `link_relay_wake`, `wait_for_webhook`, `get_webhook_events`, `ack_webhook_events` or
`release_webhook_events`) takes it over too, so telling an older session "watch for webhooks" moves the posts to
it. When the owning session closes, the next session to start or finish a turn takes over. While the inbox has a working relay wake link
(`link_relay_wake`), no hook listener takes posts: the link delivers each one to the session that made it.
`npx @agent-relay/events-shim uninstall --claude` removes the hooks.
- **Codex, with or without Agent Relay Desktop: nothing to do.** `setup --codex` installs a SessionStart hook in
Expand Down Expand Up @@ -93,8 +103,8 @@ event arrives as a post naming the changed file (deduplicated per path and revis

| Tool | What it does |
| ------------------------ | ----------------------------------------------------------------------------------- |
| `watch_webhooks` | Start here: webhook URLs, wake state, waiting posts and next steps |
| `link_relay_wake` | Link the session's relay webhook (checked with a test post first) |
| `watch_webhooks` | Start here: webhook URLs, wake state and the agent a link wakes, waiting posts |
| `link_relay_wake` | Link the session's relay webhook (checked first); pass `agent`, your relay name |
| `unlink_relay_wake` | Stop forwarding |
| `get_webhook_events` | Unread posts (marks them read), or one post by id |
| `wait_for_webhook` | Block until a post arrives (≤ 50 s), then return it (marks it read, or leases it) |
Expand Down Expand Up @@ -124,6 +134,16 @@ it is handed to the session (or printed), and release it when the session let go
leases (no `claim_token` in the result, see Hosting) they keep the older behaviour: the posts are already read,
and a stop hook that let go keeps the post on disk for the next turn's hook.

### Which session a link wakes

Every session that has the inbox's MCP server reads the same wake state, so `watch_webhooks` names the Agent Relay
agent a working link wakes (`linked_agent`, with `linked_at`) and tells the agent to compare it with its own name
before saying the inbox is linked to it. `link_relay_wake` records its `agent` argument (events-shim's own links for
Codex and the other CLIs woken through the core always pass it) and answers `replaced_agent` when it moves the link
away from another session. A link made without a name is reported as `linked_agent: null`, and the agent is told to
assume it wakes another session unless it made the link itself. Hosts keep the name in `WakeTarget.agent`. The page
feed shows it as `agent.wake_agent`.

## Webhook URLs

`<base>/h/<token>` accepts anyone holding the URL. `/github`, `/stripe`, `/linear` and `/bearer` suffixes
Expand Down
Loading
Loading