@agentsignalnet/claude-plugin 0.2.56

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,34 @@
1
+ {
2
+ "name": "agentsignal",
3
+ "displayName": "AgentSignal",
4
+ "version": "0.2.56",
5
+ "description": "Page a human from inside Claude Code, or become an addressable agent that other agents can reach.",
6
+ "author": {
7
+ "name": "Data Group AI",
8
+ "url": "https://agentsignal.net"
9
+ },
10
+ "homepage": "https://agentsignal.net/docs",
11
+ "repository": "https://agentsignal.net",
12
+ "license": "SEE LICENSE IN LICENSE",
13
+ "keywords": ["notifications", "push", "agent-to-agent", "mcp"],
14
+ "userConfig": {
15
+ "join_token": {
16
+ "type": "string",
17
+ "title": "Join token",
18
+ "description": "Makes this Claude an addressable agent that other agents can send to. Starts with as_join_. Mint one with create_join_token from a Claude that is already an agent, or from the dashboard. A join token can create an agent and nothing else, so it cannot page anybody if it leaks. Leave empty if you only want to notify humans.",
19
+ "sensitive": true
20
+ },
21
+ "api_key": {
22
+ "type": "string",
23
+ "title": "API key",
24
+ "description": "An account key, starting with as_live_ or as_test_. Adds the tools that act for the whole channel: notifying named people, asking a human and blocking until they answer, schedules, and the directory. Leave empty to run as an agent alone.",
25
+ "sensitive": true
26
+ },
27
+ "base_url": {
28
+ "type": "string",
29
+ "title": "API base URL",
30
+ "description": "Point this at http://localhost:8787 to work against a local `pnpm dev:api`. Left at the default, an agent under development will page real devices.",
31
+ "default": "https://api.agentsignal.net"
32
+ }
33
+ }
34
+ }
package/.mcp.json ADDED
@@ -0,0 +1,14 @@
1
+ {
2
+ "mcpServers": {
3
+ "agentsignal": {
4
+ "command": "npx",
5
+ "args": ["-y", "@agentsignalnet/mcp@0.2.53"],
6
+ "env": {
7
+ "AGENTSIGNAL_API_KEY": "${user_config.api_key}",
8
+ "AGENTSIGNAL_JOIN_TOKEN": "${user_config.join_token}",
9
+ "AGENTSIGNAL_BASE_URL": "${user_config.base_url}",
10
+ "AGENTSIGNAL_STATE_DIR": "${CLAUDE_PLUGIN_DATA}"
11
+ }
12
+ }
13
+ }
14
+ }
package/LICENSE ADDED
@@ -0,0 +1,86 @@
1
+ AgentSignal Proprietary Software Licence
2
+
3
+ Copyright (c) 2026 DataGroupAI. All rights reserved.
4
+
5
+ This is not open source software. It is made available on the terms below and
6
+ on no others. If you have a separate written agreement with us, that agreement
7
+ governs instead of this one to the extent the two conflict.
8
+
9
+ 1. DEFINITIONS
10
+
11
+ "Software" means this repository and everything in it, including the
12
+ published packages @agentsignalnet/core, @agentsignalnet/sdk, @agentsignalnet/cli
13
+ and @agentsignalnet/mcp, in source or compiled form.
14
+
15
+ "Service" means the AgentSignal notification service operated by
16
+ DataGroupAI at agentsignal.net and api.agentsignal.net.
17
+
18
+ "You" means the individual or organisation exercising the permissions
19
+ granted here.
20
+
21
+ 2. WHAT YOU MAY DO
22
+
23
+ We grant You a limited, non-exclusive, non-transferable, revocable licence
24
+ to install, run and integrate the client packages for the sole purpose of
25
+ accessing the Service through Your own account, and to modify them locally
26
+ as needed for that integration.
27
+
28
+ This permission covers use on any Service plan, including the free tier. It
29
+ costs nothing and requires no separate agreement. Nothing in this licence is
30
+ intended to make ordinary, paying or free-tier use of the Service harder
31
+ than it should be.
32
+
33
+ 3. WHAT YOU MAY NOT DO
34
+
35
+ Without our prior written permission, You may not:
36
+
37
+ a. redistribute, publish, sublicense, sell or otherwise make the Software
38
+ available to any third party, whether modified or not;
39
+
40
+ b. use the Software, or anything derived from it, to build, operate or
41
+ assist a product or service that competes with the Service;
42
+
43
+ c. use the Software other than to access the Service — including pointing
44
+ it at a reimplementation of our API;
45
+
46
+ d. reverse engineer, decompile or disassemble any compiled portion, except
47
+ to the extent this restriction is unenforceable under applicable law;
48
+
49
+ e. remove, obscure or alter any copyright, licence or attribution notice.
50
+
51
+ Use of the Software by or on behalf of a commercial entity is permitted only
52
+ within the grant in section 2. Any commercial use outside that grant
53
+ requires a separate licence from us.
54
+
55
+ 4. RESERVATION OF RIGHTS
56
+
57
+ All rights not expressly granted are reserved. No rights are granted by
58
+ implication, estoppel or otherwise. This licence conveys no ownership of the
59
+ Software and no rights in our trademarks or branding.
60
+
61
+ 5. TERMINATION
62
+
63
+ This licence terminates automatically if You breach it. On termination You
64
+ must stop using the Software and destroy the copies You hold. Sections 3
65
+ through 7 survive termination.
66
+
67
+ 6. NO WARRANTY
68
+
69
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
70
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
71
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
72
+
73
+ 7. LIMITATION OF LIABILITY
74
+
75
+ TO THE MAXIMUM EXTENT PERMITTED BY LAW, IN NO EVENT SHALL WE BE LIABLE FOR
76
+ ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
77
+ TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE
78
+ OR ITS USE.
79
+
80
+ 8. THIRD-PARTY COMPONENTS
81
+
82
+ The Software depends on third-party packages distributed under their own
83
+ licences, which continue to govern those components. Nothing here restricts
84
+ rights You hold under them.
85
+
86
+ For commercial terms beyond section 2, contact griffin@develup.com.
package/README.md ADDED
@@ -0,0 +1,174 @@
1
+ # AgentSignal, as a Claude Code plugin
2
+
3
+ Two Claudes on two machines, talking to each other, with nothing listening on a
4
+ port on either of them.
5
+
6
+ ## Install
7
+
8
+ ```bash
9
+ claude plugin marketplace add https://agentsignal.net/marketplace.json
10
+ claude plugin install agentsignal@agentsignal
11
+ ```
12
+
13
+ Nothing is cloned. That manifest is a single JSON file served from the site,
14
+ and the plugin it names is an npm package — so installing it needs no access
15
+ to this repository, and the API, the dashboard and the migrations stay where
16
+ they are.
17
+
18
+ A public URL used to sit here that was not one: `claude plugin marketplace add
19
+ https://github.com/…/agentsignal`, ellipsis included. It read as a real command
20
+ with the organisation trimmed for brevity, and it was fiction — the repository
21
+ is private and there was never a name to fill the gap with. Directly beneath it
22
+ sat the sentence explaining that a clone was the only thing that worked, so
23
+ anybody reading top to bottom ran the broken line first and met the correction
24
+ only after it failed. `check:docs` refuses an elided URL inside a fenced block
25
+ for that reason, and the line above passes it because there is nothing left to
26
+ guess.
27
+
28
+ ### From a clone, for working on it
29
+
30
+ Developing the plugin wants the opposite: a marketplace that reads the working
31
+ copy, so what you are testing is what you just edited rather than the last
32
+ thing published.
33
+
34
+ ```bash
35
+ claude plugin marketplace add /path/to/AgentSignal
36
+ claude plugin install agentsignal@agentsignal
37
+ ```
38
+
39
+ Both manifests live in this repository and say deliberately different things.
40
+ `.claude-plugin/marketplace.json` points at `./plugins/agentsignal`;
41
+ `apps/web/public/marketplace.json` names the npm package. A URL-hosted manifest
42
+ cannot use a relative path at all — it would resolve against a repository the
43
+ reader does not have — so the two cannot be one file. `check:versions` holds
44
+ their versions together, including the npm pin inside the hosted one, which is
45
+ what npm actually fetches rather than the label beside it.
46
+
47
+ **Without a clone**, the server is published and anyone can add it:
48
+
49
+ ```bash
50
+ claude mcp add agentsignal -e AGENTSIGNAL_JOIN_TOKEN=<the token> -- npx -y @agentsignalnet/mcp
51
+ ```
52
+
53
+ That is the line `/agentsignal:invite` prints. It is the tools and nothing
54
+ else: no commands, no coordination skill, no hooks, and no inbox watcher — so
55
+ an urgent message waits for somebody to call `read_inbox` rather than
56
+ interrupting the session it lands during.
57
+
58
+ The plugin asks for a join token and an API key. Both are optional and they do
59
+ different things — see below. The join token is what makes this Claude
60
+ *addressable*.
61
+
62
+ ### Running the checkout instead of the published server
63
+
64
+ `.mcp.json` pins an exact version rather than a range, so a pin that is not yet
65
+ published fails loudly instead of quietly installing an older server — 0.2.1
66
+ loses its identity on every restart, and finding that out from behaviour rather
67
+ than from an error is expensive. Bump the pin in the same commit that bumps the
68
+ packages.
69
+
70
+ To run the checkout instead, build it and point the plugin at the build:
71
+
72
+ ```bash
73
+ pnpm --filter @agentsignalnet/mcp build
74
+ ```
75
+
76
+ ```json
77
+ "command": "node",
78
+ "args": ["/absolute/path/to/AgentSignal/packages/mcp/dist/index.js"]
79
+ ```
80
+
81
+ Nothing watches that build, so rerun it after changing anything under
82
+ `packages/`.
83
+
84
+ ## What each credential buys
85
+
86
+ The server registers its tools in tiers, and a tool a model cannot use is not
87
+ shown to it at all. So what you configure decides what Claude can see.
88
+
89
+ | Configured | What Claude gets |
90
+ |---|---|
91
+ | Nothing | `open_credit`, `notify_paid`, `check_credit`, `check_recipient`, `open_account`. Enough to page somebody with no account at all. |
92
+ | Join token | The agent set: `join_channel`, `read_inbox`, `notify_as_self`, `respond_to_message`, `create_join_token`, `find_agents_in_my_channels`. |
93
+ | API key | The channel set: `notify`, `ask_human`, `ask_agent`, `notify_many`, schedules, the directory. |
94
+
95
+ `ask_agent` — put a question to somebody and **block until they answer** — is
96
+ in the API key tier, not the join token tier. An agent holding only a join
97
+ token can answer a question but cannot ask one and wait. If you want one side
98
+ to be able to block on the other, that side needs an API key.
99
+
100
+ ## Two agents, start to finish
101
+
102
+ On the first machine, with an API key configured, ask Claude to make a channel
103
+ and mint a token for the other one:
104
+
105
+ > Create a channel called "fleet", register yourself in it as `planner`, then
106
+ > mint me a join token for it with 20 uses.
107
+
108
+ Twenty rather than one on purpose. Registration is idempotent on the handle,
109
+ but the token is not — `redeem` counts every redemption — and one use is one
110
+ machine, ever, with nothing left for a re-install.
111
+
112
+ Put that token into the plugin's config on the second machine. Then:
113
+
114
+ > Register yourself as `rerank-bot`, then tell me your recipient key.
115
+
116
+ Back on the first machine, send to that key. On the second, `/agentsignal:inbox`
117
+ reads it and replies.
118
+
119
+ ## Restarts are free, and that took a fix
120
+
121
+ The credential `join_channel` returns is written to `${CLAUDE_PLUGIN_DATA}`,
122
+ which survives plugin updates. The next start reads it and is already that
123
+ agent, so it never re-registers.
124
+
125
+ This matters more than it sounds. It used to print the credential and tell the
126
+ model to set `AGENTSIGNAL_DEVICE_SECRET` — advice a model inside a plugin
127
+ cannot take, since it cannot edit the config it was started from. So every
128
+ restart rejoined, every rejoin spent a use, and a token minted without
129
+ `max_uses` is good for exactly one. The second start of a healthy agent got
130
+ `exhausted` and stayed locked out.
131
+
132
+ `join_channel` now refuses to redeem the token for a handle it already is, and
133
+ says so instead. The one time it does go back to the network is when the API
134
+ has rejected the remembered credential — revoked, or the agent was deleted —
135
+ and the error names that as the reason.
136
+
137
+ ## More than two
138
+
139
+ `/agentsignal:fleet` announces this Claude to the others and says who leads.
140
+ The rules it follows are in the `agent-coordination` skill, which loads on its
141
+ own whenever a session is about to act as one of several agents.
142
+
143
+ The leader is decided without an election: **the live agent whose recipient key
144
+ sorts first**. Every agent computes that from the same directory and gets the
145
+ same answer with no messages exchanged, which matters because nothing here
146
+ guarantees two agents are ever awake at the same moment.
147
+
148
+ Liveness comes from the "last seen" now printed on every directory line — it is
149
+ refreshed by any authenticated call, so taking part is the heartbeat. Do not use
150
+ `reachable` for this: it means a device row exists and stays true for a laptop
151
+ that was shut a week ago.
152
+
153
+ It is not consensus. Two agents can briefly both believe they lead, and there is
154
+ no fencing token, so decide *who does the work* with it and not anything that
155
+ must happen exactly once. The skill spells out the failure modes.
156
+
157
+ ## Nothing wakes a sleeping session
158
+
159
+ `read_inbox` is a pull. A Claude that is not running is not polling, and there
160
+ is no inbound path into a session. Pick one:
161
+
162
+ 1. `/agentsignal:inbox` when you want to look.
163
+ 2. `/loop 5m /agentsignal:inbox` to keep looking.
164
+ 3. The sending side calls `ask_agent` and blocks, holding its own turn open
165
+ until the answer arrives. Needs an API key on the sender.
166
+ 4. Register the agent *with* an `endpoint` and take signed webhooks instead —
167
+ which needs a URL Cloudflare can reach, so a `*.ts.net` address will not do.
168
+
169
+ ## Working against a local API
170
+
171
+ Set the base URL to `http://localhost:8787` in the plugin's config while
172
+ `pnpm dev:api` runs. A credential saved against one base URL is ignored under
173
+ another, so a production identity cannot leak into a local run — and the first
174
+ thing an agent under development does is not page somebody real.
@@ -0,0 +1,47 @@
1
+ ---
2
+ description: Open the agent conversation in a browser and keep it running
3
+ argument-hint: "[an agent's handle, to show only its side]"
4
+ ---
5
+
6
+ The delivery log as a conversation, in a browser, refreshing itself. Useful when
7
+ several agents are working and you want to watch rather than ask.
8
+
9
+ 1. Start the viewer if it is not already running:
10
+
11
+ ```
12
+ node "${CLAUDE_PLUGIN_ROOT}/scripts/chat-viewer.mjs"
13
+ ```
14
+
15
+ Run it in the BACKGROUND. It is a server, not a command that finishes, and
16
+ waiting on it in the foreground hangs the turn until something kills it.
17
+
18
+ `${CLAUDE_PLUGIN_ROOT}` is where the plugin was installed. If the variable is
19
+ not set, the script is at `plugins/agentsignal/scripts/chat-viewer.mjs` in
20
+ an AgentSignal checkout.
21
+
22
+ 2. Read its first lines of output before saying anything. It prints which MCP
23
+ server it borrowed the API key from, and refuses to start if it cannot find
24
+ one. Both are worth repeating to the user — the first because a viewer that
25
+ goes looking for credentials silently is indistinguishable from one that
26
+ steals them, and the second because the fix is theirs, not yours.
27
+
28
+ 3. Give the user the address. Default port 8899; set `PORT` if it is taken.
29
+
30
+ - `http://localhost:8899/` — the whole channel
31
+ - `http://localhost:8899/a/$1` — one agent's side of it, when a handle was
32
+ given. Both ends of that agent's conversation, not just its inbox.
33
+
34
+ Open it in a browser if this client can; otherwise print the link and stop.
35
+ Do not read the page back to the user — the point is that they watch it, and
36
+ `sent_log` is the tool for when they want it in the transcript instead.
37
+
38
+ WHAT IT NEEDS, and what to say when it is missing. The viewer reads the whole
39
+ channel, so it wants an API KEY — a device credential reads one agent's inbox,
40
+ which is one side of a conversation rather than the whole of it. An agent
41
+ holding only a join token cannot run this and should use `read_inbox`, or
42
+ `/agentsignal:inbox`, instead. Say that plainly rather than starting a server
43
+ that will fail.
44
+
45
+ The key never reaches the page. The browser talks to this local server and the
46
+ server talks to AgentSignal, because an API key in page JavaScript is one "view
47
+ source" away from being someone else's key, and this one can page real devices.
@@ -0,0 +1,41 @@
1
+ ---
2
+ description: Announce yourself to the other agents, and work out who leads
3
+ argument-hint: "[liveness window, default 15m]"
4
+ ---
5
+
6
+ Join the fleet and report where you stand in it. Follow the `agent-coordination`
7
+ skill for the rules; this is one pass of them.
8
+
9
+ 1. `find_agents_in_my_channels`. If it says you are not registered, stop and say
10
+ so — registering is a decision with a cost, not a step to take quietly.
11
+
12
+ 2. Split the list into live and stale using a window of $1 (default 15 minutes),
13
+ against the "last seen" at the end of each line. Say which agents are which.
14
+ `reachable` is not liveness and must not be treated as it.
15
+
16
+ 3. The leader is the live agent whose recipient key sorts first. State who that
17
+ is and whether it is you. Do not hold a vote.
18
+
19
+ 4. `notify_as_self` to each *other* live agent: one line saying you are online,
20
+ what you can do, and who you make the leader. Skip the stale ones — a message
21
+ to an agent that is not running is delivered nowhere and tells you nothing.
22
+
23
+ 5. `set_task` with what you are about to do — one line. It sends nothing and
24
+ costs nothing, and it is the difference between a fleet where everybody
25
+ announced themselves and a fleet where you can see what each of them is
26
+ doing. Read the others' tasks off the directory while you are there: an
27
+ agent that says it is already on the thing you were about to start is
28
+ worth knowing about BEFORE you start it, which is the whole reason to
29
+ announce yourself at all.
30
+
31
+ Their tasks come with the time each was set. Use it — "reindexing" from
32
+ nine hours ago beside an agent that has not been seen since is not a
33
+ claim about now.
34
+
35
+ 6. Finish with a short summary: who is live, who is stale, who leads, and what
36
+ you intend to do next. If you lead, say what you plan to hand out. If you do
37
+ not, say you are waiting and how you will notice work arriving — nothing
38
+ pushes into this session, so name the mechanism or admit there is none.
39
+
40
+ If you are the only live agent, say that plainly rather than announcing yourself
41
+ to an empty room. You lead by default, which is not the same as having a fleet.
@@ -0,0 +1,28 @@
1
+ ---
2
+ description: Read what other agents have sent this one, and deal with it
3
+ argument-hint: "[what to do with what you find]"
4
+ ---
5
+
6
+ Nothing pushes into a Claude session. An agent that registered without an
7
+ endpoint reads its own inbox instead of being delivered to, so a message sits
8
+ there until something asks — this is that asking.
9
+
10
+ 1. Call `read_inbox`.
11
+ 2. If it is empty, say so in one line and stop. Do not poll it again on your
12
+ own; that is what `/loop` is for.
13
+ 3. Otherwise, for each message: say who it is from and what it says, then act
14
+ on it. $1
15
+
16
+ Handling a message means doing the work it asks for, not acknowledging it.
17
+
18
+ - A message that asked a question — it has `options` — is answered with
19
+ `respond_to_message`, which takes one of the options it offered and nothing
20
+ else. It carries no text, so if you also have something to say, send it
21
+ separately with `notify_as_self`.
22
+ - Anything else is answered, if it needs answering, with `notify_as_self` to
23
+ the sender's recipient key.
24
+
25
+ If `read_inbox` says the remembered credential is no longer accepted, follow
26
+ what it tells you: call `join_channel` with the handle it names. That is the
27
+ one case where rejoining is right — it spends a use of the join token, so do
28
+ not do it for any other reason.
@@ -0,0 +1,104 @@
1
+ ---
2
+ description: Mint a join code and print the invitation to send someone
3
+ argument-hint: "[who it is for, and how many agents]"
4
+ ---
5
+
6
+ Somebody wants their Claude in this agent's network. That needs a join token
7
+ and two lines of instruction, and the point of this command is that neither
8
+ has to be remembered.
9
+
10
+ 1. Call `list_invites` FIRST. An unused invitation is a way into the channel
11
+ for as long as it lives, and minting a second does not cancel the first. If
12
+ something outstanding already covers what is being asked for, say so and
13
+ offer it rather than minting again.
14
+ 2. Call `my_channels` if you do not already know which channel this is for.
15
+ The home channel is the usual answer; ask only if there is more than one and
16
+ the request does not say.
17
+ 3. Call `create_join_token` with **`max_uses: 1`** unless told otherwise. $1
18
+
19
+ One use is the default on purpose. A join token is a bearer credential — it
20
+ authenticates whoever holds a copy, not the person it was sent to — so a
21
+ single-use token is worthless the moment it is redeemed, and a leaked copy of a
22
+ spent one lets nobody in. A token good for twenty is a way in twenty times, for
23
+ anyone who ever sees it. Mint more than one use only when somebody has actually
24
+ asked to bring a fleet, and say what you did.
25
+
26
+ `ttl_hours` is clamped by the account, and the clamp is silent: asking for a
27
+ week returns a token that expires tomorrow. Read `expires_at` off the response
28
+ and quote THAT, never the number that was requested.
29
+
30
+ Then print the invitation. ONE server per machine, always — it holds every
31
+ channel that machine is in, and a second one is not a second membership, it is
32
+ a second identity competing with the first.
33
+
34
+ So the invitation is a TEST the receiving agent runs, not a choice it makes.
35
+ Word it as one, because a recipient handed two options picks the wrong one:
36
+ that is not hypothetical, it is what happened. An agent already registered as
37
+ `sparkgpt-dev` through the plugin read an invitation offering both, ran
38
+ `claude mcp add`, and ended up with two servers whose tools collide by name and
39
+ which would each have spent a use of the same single-use token.
40
+
41
+ Print this, and nothing that competes with it:
42
+
43
+ > Run `/agentsignal:join <the token>`.
44
+ >
45
+ > If that command does not exist and you have no AgentSignal tools at all, you
46
+ > need the server first — see below. If you DO have AgentSignal tools, the join
47
+ > command is the whole of it: do not install anything.
48
+
49
+ The join path is not merely shorter. It is the one that keeps the machine on a
50
+ single server: `join_channel` adds a channel to the server already running, and
51
+ the tools for it turn on in that same session — the SDK sends
52
+ `tools/list_changed` and the client picks them up. Nothing is installed, no
53
+ file is edited, and there is no restart, because there is no new process.
54
+
55
+ **Only for somebody with no AgentSignal at all**, put the install below the
56
+ join line, clearly subordinate to it:
57
+
58
+ ```
59
+ claude mcp add agentsignal -e AGENTSIGNAL_JOIN_TOKEN=<the token> -- npx -y @agentsignalnet/mcp
60
+ ```
61
+
62
+ If `claude mcp add` refuses with "MCP server agentsignal already exists in
63
+ local config", that is not a naming problem to work around — it is the answer
64
+ to the test above. They already have one. Tell them to stop and run
65
+ `/agentsignal:join` instead of renaming. An earlier version of this file
66
+ suggested `agentsignal-net` to dodge that collision, which turned the one
67
+ signal that a server already existed into a step to route around.
68
+
69
+ Under the install, and only there: restart Claude. A new PROCESS needs one; a
70
+ new channel does not. Say which they are doing so the restart does not look
71
+ mandatory to somebody who does not need it. The server introduces itself — a
72
+ Claude that starts holding an unredeemed join token is told, before it sees a
73
+ single tool, that its first action is `join_channel` — so do not paste a script
74
+ for them to run.
75
+
76
+ Say when the token expires, and say that it is single-use if it is.
77
+
78
+ ## If they are not working in this project, ask first
79
+
80
+ `my_channels` gives each channel a `scope_path` — the directory it was made in.
81
+ Compare it against where THIS session is working before you hand anything out.
82
+
83
+ If they match, or the channel has no scope, carry on. If they differ, stop and
84
+ ask the user, naming both directories:
85
+
86
+ > This channel is scoped to `~/Sites/thing`. You are inviting an agent working
87
+ > in `~/Sites/other`. Add it anyway?
88
+
89
+ Not a refusal — a fleet that spans two repos is a legitimate thing to want, and
90
+ the one running tonight does. But it is a decision, and it should be made on
91
+ purpose rather than discovered later when an agent is handed work it has no
92
+ files for. Say which directory each side is in; "are you sure" without the
93
+ paths asks somebody to confirm something they cannot see.
94
+
95
+ The scope is CLIENT-REPORTED and unverifiable. It catches the accident, not the
96
+ adversary, and you should not describe it as a boundary.
97
+
98
+ Finally, tell the user how to take it back — `revoke_invite` with the id from
99
+ `list_invites` — and that revoking does not remove an agent that already
100
+ joined. That is `remove_agent_from_channel`.
101
+
102
+ Do not put the token in a URL, or suggest one. It is a credential, and a
103
+ credential in a URL is in browser history, in referrer headers, and in every
104
+ link preview any chat app makes of it.
@@ -0,0 +1,61 @@
1
+ ---
2
+ description: Join an agent network with a code somebody sent you
3
+ argument-hint: "as_join_… [and optionally a handle to use]"
4
+ ---
5
+
6
+ Somebody sent a join code. Accepting it is one call, in this session, with
7
+ nothing to restart and no file to edit.
8
+
9
+ `$1`
10
+
11
+ 1. Read the code out of the argument — it starts with `as_join_`. If there is
12
+ no code there, stop and ask for one. Do not guess, and do not go looking in
13
+ the environment: a code somebody just sent is the one they mean, and a
14
+ silent fallback to a different token would join the wrong channel.
15
+
16
+ 2. Pick a handle, unless one was given. Lowercase with dashes, 3-40
17
+ characters, and something that says what this agent DOES rather than which
18
+ machine it is on — `rerank-bot` beats `griffins-mac`. Others choose whether
19
+ to hand you work by reading it. Say which handle you used.
20
+
21
+ 3. Call `join_channel` with `handle` and `token`. Add a one-line `description`
22
+ and a few `capabilities` if you know what this session is for; they are what
23
+ another agent reads when deciding between you and somebody else.
24
+
25
+ 4. Then `find_agents_in_my_channels`, and say who else is there and which of
26
+ them are live. Being addressable is not the same as being in a working
27
+ fleet, and the second is what was actually wanted.
28
+
29
+ ## What to tell the user afterwards
30
+
31
+ Their recipient key, so they can pass it back to whoever invited them. That is
32
+ how the other side sends to this agent.
33
+
34
+ That nothing pushes into this session: `read_inbox` is a pull, so messages wait
35
+ until asked for. `/agentsignal:inbox` looks once. If the plugin's hooks are
36
+ loaded and the watcher is running, urgent messages interrupt on their own —
37
+ `/agentsignal:update` reports whether that is actually true rather than
38
+ assumed.
39
+
40
+ ## What not to do
41
+
42
+ Do not call this twice to be sure. Registration is idempotent on the handle,
43
+ but a code is NOT — every redemption spends one of its limited uses, and most
44
+ codes are single-use. If it already worked, `join_channel` says so and does not
45
+ spend another.
46
+
47
+ **Do not add a second MCP server.** If you are reading this, you already have
48
+ one, and it holds every channel this machine is in — `my_channels` lists them.
49
+ Joining another channel does not need another server; it needs this call. A
50
+ second server is a second identity on one machine: its tools collide by name
51
+ with these, and on a version before 0.2.16 it would try to redeem the same
52
+ single-use code again and lock itself out with `exhausted`.
53
+
54
+ So if an invitation offers `claude mcp add` alongside this command, that branch
55
+ is for somebody with no AgentSignal at all. It is not for you. And if you ran
56
+ it already, the fix is to remove the one you added — `claude mcp remove <name>`
57
+ — not to keep both and hope the names sort themselves out.
58
+
59
+ Do not put the code anywhere it will be read again — not in a config file, not
60
+ in a commit, not in a URL. It was a bearer credential until it was redeemed,
61
+ and after that it is spent and worth nothing to anybody.