@kvsm/blether 0.2.0 → 0.2.1

package/README.md

@@ -16,25 +16,40 @@ Teams also need a relay, which holds each agent's mailbox. It's published as the
 
 ## Quickstart
 
-You need Node 24, and an invite link from a teammate whose team already has a relay.
+You need Node 24, and an invite link from a teammate whose team already has a relay. To start a team instead, you need a relay: see [Run a relay](https://github.com/kvsm/blether#2-run-a-relay).
 
 ```sh
 npm install -g @kvsm/blether
 blether claude install                 # adds the plugin to Claude Code (the CLI and VS Code)
+```
 
-blether init --name <name>             # your identity, once per developer
-blether join <invite>                  # prints "Joined <team>."
-blether agent create <team> web        # an agent you own: a named mailbox
+Then open Claude Code in a project, with `claude` in the terminal or in VS Code, and run `/blether:setup`. Claude walks you through the rest, running the commands for you:
 
-cd ~/code/web-app                      # each project an agent works in
-blether use <team> web                 # sessions started here act as "web"
-```
+1. **Your identity:** your name, as teammates will see it. Once per developer.
+2. **Your team:** joins it with your invite, or creates a new one.
+3. **This project's agent:** the named mailbox your sessions here act as. Teammates' agents message it by name, so pick one that says what it works on, such as `web-app` or `payments-api`. You can give it roles, such as `frontend` or `reviewer`, so teammates can message every agent covering an area at once.
+4. **Connecting:** the session connects to Blether, and is told whenever a message arrives.
 
-Start a new Claude Code session in the project and run `/blether:connect`. Claude can now message your teammates' agents, and is told when messages arrive. Sessions you don't connect leave Blether out entirely.
+Claude can now message your teammates' agents. In later sessions, run `/blether:connect` when you want to work with your team. Sessions you don't connect leave Blether out entirely.
 
 By default Claude asks you before it sends any message, and before it acts on any request it receives. `blether policy` shows your Approval Policy, and `blether help` lists every command.
 
-To start a team or run a relay, see [Getting started](https://github.com/kvsm/blether#getting-started).
+### By hand
+
+To set up without the skill, or for an agent other than Claude Code, run the steps yourself:
+
+```sh
+blether init --name <name>             # your identity, once per developer
+blether join <invite>                  # prints "Joined <team>."
+blether role list <team>               # the team's roles, such as frontend or reviewer
+blether role add <team> <role>         # add one if what your agent does isn't listed
+blether agent create <team> <agent name> --role <role>   # an agent you own; --role is optional, and can repeat
+
+cd <project>                           # each project an agent works in
+blether use <team> <agent name>        # sessions started here act as <agent name>
+```
+
+In Claude Code, start a new session in the project and run `/blether:connect`. For other agents, see [Other agents](#other-agents) below. To start a team or run a relay, see [Getting started](https://github.com/kvsm/blether#getting-started).
 
 ## Other agents
 
@@ -58,7 +73,7 @@ blether --version                      # shows the version now installed
 blether claude install                 # if you use Claude Code: updates the plugin to match
 ```
 
-Then start new agent sessions: a running session keeps the bridge it started with. Your identity, teams and projects are left as they are. See [Updating](https://github.com/kvsm/blether#updating) for the details.
+Then restart your agent sessions. Your identity, teams and projects are left as they are. See [Updating](https://github.com/kvsm/blether#updating) for the details.
 
 ## Documentation
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kvsm/blether",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Agent-to-agent communication for distributed teams of human developers: the blether CLI, the bridge (an MCP server), and the Claude Code plugin.",
   "keywords": [
     "agents",
@@ -31,8 +31,8 @@
   "devDependencies": {
     "@modelcontextprotocol/sdk": "^1.31.0",
     "esbuild": "^0.28.2",
-    "@blether/bridge": "0.2.0",
-    "@blether/relay": "0.2.0"
+    "@blether/bridge": "0.2.1",
+    "@blether/relay": "0.2.1"
   },
   "publishConfig": {
     "access": "public"

package/plugin/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "blether",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "displayName": "Blether",
   "description": "Message your teammates' coding agents through Blether: the bridge, new-mail notices, and skills for when and how to reach out.",
   "author": {

package/plugin/dist/bridge.js

@@ -36960,7 +36960,7 @@ var DeviceGrant = external_exports.object({
 });
 
 // ../protocol/dist/version.js
-var BLETHER_VERSION = "0.2.0";
+var BLETHER_VERSION = "0.2.1";
 
 // ../protocol/dist/wire.js
 var AudienceHint = external_exports.object({
@@ -37681,11 +37681,11 @@ function readSessionFile(path2) {
   try {
     raw = JSON.parse(readFileSync6(path2, "utf8"));
   } catch (error62) {
-    throw new SessionFileError(`${path2} isn't valid JSON (${error62.message}). Write it again with \`blether use <team> <agent>\`.`);
+    throw new SessionFileError(`${path2} isn't valid JSON (${error62.message}). Write it again with \`blether use <team> <agent name>\`.`);
   }
   const parsed = SessionFileContents.safeParse(raw);
   if (!parsed.success) {
-    throw new SessionFileError(`${path2} doesn't name a team and agent. Write it again with \`blether use <team> <agent>\`.`);
+    throw new SessionFileError(`${path2} doesn't name a team and agent. Write it again with \`blether use <team> <agent name>\`.`);
   }
   return parsed.data;
 }
@@ -51148,7 +51148,7 @@ function createDormantServer(connect2) {
   const offerConnect = () => {
     const connectTool = server2.registerTool("connect", {
       title: "Connect to Blether",
-      description: "Connects this session to Blether, so you can message the agents of other developers on your team. Call it only when your developer runs /blether:connect or asks you to connect to Blether."
+      description: "Connects this session to Blether, so you can message the agents of other developers on your team. Call it ONLY when your developer runs /blether:connect or /blether:setup. Never call it otherwise, even if they ask you to connect: tell them to run /blether:connect instead."
     }, async () => {
       let connected;
       try {
@@ -51162,7 +51162,7 @@ function createDormantServer(connect2) {
       connectTool.remove();
       const disconnectTool = server2.registerTool("disconnect", {
         title: "Disconnect from Blether",
-        description: "Disconnects this session from Blether. Call it only when your developer runs /blether:disconnect or asks you to."
+        description: "Disconnects this session from Blether. Call it ONLY when your developer runs /blether:disconnect. Never call it otherwise, even if they ask you to disconnect: tell them to run /blether:disconnect instead."
       }, async () => {
         const result = await connected.disconnect();
         disconnectTool.remove();
@@ -51595,7 +51595,7 @@ var SetupProblem = class extends Error {
 };
 var REFUSAL_FIXES = {
   "agent-in-use": (agent) => `Only one session can act as ${agent} at a time. If the other one is still in use, close it (it may be in another terminal, or on another of your devices) or choose a different agent for this project with \`blether use\`. If this session should be ${agent} instead, use take_over_agent.`,
-  "agent-owned-by-another": (agent, team) => `${agent} is another developer's agent. Use one of yours (\`blether agent list ${team}\`) or create one with \`blether agent create ${team} <name>\`, then restart this session.`,
+  "agent-owned-by-another": (agent, team) => `${agent} is another developer's agent. Use one of yours (\`blether agent list ${team}\`) or create one with \`blether agent create ${team} <agent name>\`, then restart this session.`,
   "not-a-member": () => "Ask a teammate for an invite and run `blether join <invite>`, then restart this session.",
   "unknown-team": (_agent, team) => `The relay doesn't know ${team}; it may have been reset. Check the relay is the right one, or create the team again with \`blether team create\`.`,
   "authentication-failed": () => "This device's identity didn't verify. Check `blether whoami`; if it's damaged, set this device up again.",
@@ -51708,11 +51708,11 @@ async function connect(env, log, into) {
   }
   const agentName = env.BLETHER_AGENT ?? session?.contents.agent;
   if (agentName === void 0) {
-    throw new SetupProblem("No agent is chosen for this project. Run `blether use <team> <agent>` in the project (`blether agent list <team>` shows the agents), then restart this session.");
+    throw new SetupProblem("No agent is chosen for this project. Run `blether use <team> <agent name>` in the project (`blether agent list <team>` shows the agents), then restart this session.");
   }
   const agent = AgentName.safeParse(agentName);
   if (!agent.success) {
-    throw new SetupProblem(`BLETHER_AGENT is set to "${agentName}", which isn't an agent name (lowercase letters, digits and hyphens). Fix it in this agent's MCP config, or remove it and run \`blether use <team> <agent>\` in the project.`);
+    throw new SetupProblem(`BLETHER_AGENT is set to "${agentName}", which isn't an agent name (lowercase letters, digits and hyphens). Fix it in this agent's MCP config, or remove it and run \`blether use <team> <agent name>\` in the project.`);
   }
   if (session)
     log(`blether bridge using ${session.path}`);
@@ -51728,7 +51728,7 @@ async function connect(env, log, into) {
   }
   const teamName = env.BLETHER_TEAM ?? session?.contents.team;
   if (!teamName) {
-    throw new SetupProblem("No team is chosen for this project. Run `blether use <team> <agent>` in the project (`blether team list` shows your teams), then restart this session.");
+    throw new SetupProblem("No team is chosen for this project. Run `blether use <team> <agent name>` in the project (`blether team list` shows your teams), then restart this session.");
   }
   let team;
   try {

package/plugin/dist/cli.js

@@ -27618,7 +27618,7 @@ function parseDeviceGrant(text) {
 }
 
 // ../protocol/dist/version.js
-var BLETHER_VERSION = "0.2.0";
+var BLETHER_VERSION = "0.2.1";
 
 // ../protocol/dist/wire.js
 var AudienceHint = external_exports.object({
@@ -28877,13 +28877,16 @@ Commands:
   device list                        List your identity's devices
   device revoke <fingerprint>        Revoke a lost or stolen device, from another of yours
   role add <team> <role>             Add a role to the team's agreed list
-  agent create <team> <name> [--role <r>]...
+  role list <team>                   List the team's roles
+  agent create <team> <agent name> [--role <r>]...
                                      Create an agent you own, with roles from the team's list
-  agent roles <team> <name> [--role <r>]...
+  agent roles <team> <agent name> [--role <r>]...
                                      Replace the roles of one of your agents
   agent list <team>                  Show the team's agents and who is online
-  agent delete <team> <name>         Delete one of your agents (or any, as Team Admin)
-  use <team> <agent> [--dir <path>]  Make sessions started in this project (or <path>) act as <agent>
+  agent delete <team> <agent name>
+                                     Delete one of your agents (or any, as Team Admin)
+  use <team> <agent name> [--dir <path>]
+                                     Make sessions started in this project (or <path>) act as the agent
   claude install                     Install (or update) the Blether plugin in Claude Code
   watch --inbox <path> --session <id>
                                      Print a line whenever a connected session's agent gets mail
@@ -28969,6 +28972,8 @@ ${USAGE}`);
       const [sub, ...args] = rest;
       if (sub === "add")
         return roleAdd(args, ctx);
+      if (sub === "list")
+        return roleList(args, ctx);
       throw new CliError(`Unknown role command: ${sub ?? "(none)"}
 
 ${USAGE}`);
@@ -29424,6 +29429,19 @@ async function roleAdd(args, ctx) {
   ctx.io.out(`Added the ${role} role to ${record2.name}.`);
   return 0;
 }
+async function roleList(args, ctx) {
+  const record2 = loadTeam(ctx.teams, args[0]);
+  const credentials = loadCredentials(ctx.store);
+  const { team } = await withRelay(ctx, record2.relayUrl, credentials, (relay) => relay.getTeam(record2.id));
+  if (team.roles.length === 0) {
+    ctx.io.out(`${record2.name} has no roles yet. Add one with: blether role add ${record2.name} <role>`);
+    return 0;
+  }
+  ctx.io.out(`Roles in ${record2.name}:`);
+  for (const role of team.roles)
+    ctx.io.out(`  ${role}`);
+  return 0;
+}
 async function agentCreate(args, ctx) {
   const { values, positionals } = parseArgs({
     args,
@@ -29431,7 +29449,7 @@ async function agentCreate(args, ctx) {
     options: { role: { type: "string", multiple: true } }
   });
   const record2 = loadTeam(ctx.teams, positionals[0]);
-  const name = parseName(AgentName, positionals[1], "Usage: blether agent create <team> <name> [--role <role>]...");
+  const name = parseName(AgentName, positionals[1], "Usage: blether agent create <team> <agent name> [--role <role>]...");
   const roles = values.role ?? [];
   const credentials = loadCredentials(ctx.store);
   await withRelay(ctx, record2.relayUrl, credentials, async (relay) => {
@@ -29453,7 +29471,7 @@ async function agentRoles(args, ctx) {
     options: { role: { type: "string", multiple: true } }
   });
   const record2 = loadTeam(ctx.teams, positionals[0]);
-  const name = parseName(AgentName, positionals[1], "Usage: blether agent roles <team> <name> [--role <role>]...");
+  const name = parseName(AgentName, positionals[1], "Usage: blether agent roles <team> <agent name> [--role <role>]...");
   const roles = values.role ?? [];
   const credentials = loadCredentials(ctx.store);
   const me2 = verifyIdentityLog(credentials.identity).id;
@@ -29506,7 +29524,7 @@ async function teamRemove(args, ctx) {
 }
 async function agentDelete(args, ctx) {
   const record2 = loadTeam(ctx.teams, args[0]);
-  const name = parseName(AgentName, args[1], "Usage: blether agent delete <team> <name>");
+  const name = parseName(AgentName, args[1], "Usage: blether agent delete <team> <agent name>");
   const credentials = loadCredentials(ctx.store);
   const me2 = verifyIdentityLog(credentials.identity).id;
   await withRelay(ctx, record2.relayUrl, credentials, async (relay) => {
@@ -29563,7 +29581,7 @@ async function use(args, ctx) {
     allowPositionals: true,
     options: { dir: { type: "string" } }
   });
-  const usage = "Usage: blether use <team> <agent> [--dir <path>]";
+  const usage = "Usage: blether use <team> <agent name> [--dir <path>]";
   if (positionals.length === 0)
     throw new CliError(usage);
   const record2 = loadTeam(ctx.teams, positionals[0]);
@@ -29598,15 +29616,15 @@ async function agentList(args, ctx) {
     online: await relay.getPresence(record2.id)
   }));
   if (team.agents.length === 0) {
-    ctx.io.out(`${record2.name} has no agents yet. Create one with: blether agent create ${record2.name} <name>`);
-    return 0;
-  }
-  ctx.io.out(`Agents in ${record2.name}:`);
-  for (const agent of team.agents) {
-    const owner = identities.get(agent.owner)?.name ?? "(unknown)";
-    const roles = agent.roles.length > 0 ? agent.roles.join(", ") : "no roles";
-    const presence = online.includes(agent.name) ? "online" : "offline";
-    ctx.io.out(`  ${agent.name}  ${owner}, ${roles}, ${presence}`);
+    ctx.io.out(`${record2.name} has no agents yet. Create one with: blether agent create ${record2.name} <agent name>`);
+  } else {
+    ctx.io.out(`Agents in ${record2.name}:`);
+    for (const agent of team.agents) {
+      const owner = identities.get(agent.owner)?.name ?? "(unknown)";
+      const roles = agent.roles.length > 0 ? agent.roles.join(", ") : "no roles";
+      const presence = online.includes(agent.name) ? "online" : "offline";
+      ctx.io.out(`  ${agent.name}  ${owner}, ${roles}, ${presence}`);
+    }
   }
   if (team.roles.length > 0) {
     ctx.io.out(`Roles: ${team.roles.join(", ")}`);
@@ -29679,7 +29697,7 @@ async function join6(args, ctx) {
   });
   ctx.teams.save(record2);
   ctx.io.out(`Joined ${record2.name}.`);
-  ctx.io.out(`Create an agent with: blether agent create ${record2.name} <name>, then run blether use ${record2.name} <name> in your project.`);
+  ctx.io.out(`Create an agent with: blether agent create ${record2.name} <agent name>, then run blether use ${record2.name} <agent name> in your project.`);
   return 0;
 }
 function now(ctx) {

package/plugin/skills/connect/SKILL.md

@@ -8,7 +8,10 @@ disable-model-invocation: true
 
 The developer wants this session to use Blether. Until now the bridge has stayed out of it.
 
-1. Call the bridge's `connect` tool (`mcp__plugin_blether_blether__connect`; load it with ToolSearch first if it's deferred).
-2. If it fails, tell the developer what it says. If no agent is chosen for this project, offer `/blether:setup`.
-3. If it connects, do what its result says: read the mailbox, then start the watch with the Monitor tool, exactly as given.
-4. Tell the developer in two or three lines: which agent this session is, what's waiting in the mailbox, and that you'll hear about new mail while connected. If another session was using the agent, it has been disconnected.
+1. Check whether another session is using the agent. Connecting takes the agent over, and the other session is disconnected without warning.
+   - Read `.blether/session.json` in the project root for the team and agent. If there isn't one, skip this check: the `connect` tool says what's missing.
+   - Run `blether agent list <team>` (the plugin puts `blether` on your Bash `PATH`). If the agent shows as `online`, another session is using it, perhaps in another terminal or on another device. Tell the developer, and go on only if they say to take it over.
+2. Call the bridge's `connect` tool (`mcp__plugin_blether_blether__connect`; load it with ToolSearch first if it's deferred).
+3. If it fails, tell the developer what it says. If no agent is chosen for this project, offer `/blether:setup`.
+4. If it connects, do what its result says: read the mailbox, then start the watch with the Monitor tool, exactly as given.
+5. Tell the developer in two or three lines: which agent this session is, what's waiting in the mailbox, and that you'll hear about new mail while connected.

package/plugin/skills/setup/SKILL.md

@@ -31,15 +31,21 @@ Done when `team list` shows the team.
 
 ## 3. Agent for this project
 
-Run `agent list <team>` and ask which of **their** agents this project should act as, or what to call a new one. Agents are named for what they work on (`web`, `api`, `docs`), lowercase with hyphens. To create one, run `agent create <team> <name>`, adding `--role <role>` for roles the team already lists.
+First read `.blether/session.json` in the project root, if it exists: it names the team and agent the project already acts as. If so, tell them, and ask whether to keep it. Keeping it: go on to step 4, without running `use`.
 
-Then run `use <team> <agent>` in the project root. It writes `.blether/session.json`, which git ignores.
+Otherwise, run `agent list <team>` and ask which of **their** agents this project should act as, or what to call a new one. Teammates' agents message it by name, so suggest one that says what it works on (such as `web-app` or `payments-api`), lowercase with hyphens.
 
-Done when `use` reports the agent for this project.
+For a new agent, run `role list <team>` and ask which roles describe what it does. Roles let teammates message every agent covering an area at once, and are optional. If one they want isn't listed, run `role add <team> <role>`. Then run `agent create <team> <agent name>`, with `--role <role>` for each role.
+
+Then run `use <team> <agent name>` in the project root. It writes `.blether/session.json`, which git ignores.
+
+Done when the project has the agent they want, kept or set with `use`.
 
 ## 4. Connect and check
 
-Setting Blether up is a request to use it, so connect this session: call the bridge's `connect` tool (`mcp__plugin_blether_blether__connect`; load it with ToolSearch first if it's deferred). It reads the project's agent when called, so there's no need to restart.
+Setting Blether up is a request to use it, so connect this session. Connecting takes the agent over from any other session connected as it, which is then disconnected without warning. So first run `agent list <team>`: if the project's agent shows as `online`, another session (perhaps in another terminal, or on another device) is using it. Tell them, and connect only if they say to take it over.
+
+To connect, call the bridge's `connect` tool (`mcp__plugin_blether_blether__connect`; load it with ToolSearch first if it's deferred). It reads the project's agent when called, so there's no need to restart.
 
 Done when it connects and its result's instructions are followed (read the mailbox, start the watch). If it fails, fix what it says.
 
@@ -51,6 +57,6 @@ Tell them how Blether works from now on:
 
 Offer this option and set it up if they want it:
 
-- **Status line**: `blether status` prints a count of messages agents are holding for the developer's decision. Offer to add it to `statusLine` in `~/.claude/settings.json`, merging with any status line they already have.
+- **Status line**: `blether status` prints a count of messages agents are holding for the developer's decision. Read `statusLine` in `~/.claude/settings.json` first: if it already runs `blether status`, say so and skip this. Otherwise, offer to add it, merging with any status line they already have.
 
 Finish with a one-paragraph summary: who they are, which team, which agent this project acts as, and what's enabled.