@windyroad/connect 0.2.0-preview.31

package/.claude-plugin/plugin.json

@@ -0,0 +1,5 @@
+{
+  "name": "wr-connect",
+  "version": "0.1.0",
+  "description": "Connect Claude Code sessions across repos via Discord (experimental)"
+}

package/README.md

@@ -0,0 +1,110 @@
+# @windyroad/connect
+
+> **EXPERIMENTAL** — This plugin uses Claude Code's `--channels` feature, which is a
+> research preview as of April 2026. The API surface may change. See
+> [ADR-006](../../docs/decisions/006-connect-plugin.proposed.md) for details.
+
+Connect Claude Code sessions across repos via Discord so they can collaborate.
+
+## What It Does
+
+When running Claude Code sessions across multiple repos, this plugin lets sessions
+communicate — with zero idle token cost. Sessions can hand off findings, ask questions,
+share context, or coordinate work. The receiving session wakes up only when a message
+arrives, using Discord as the collaboration channel.
+
+**Example:** Session A (repo-a) discovers a bug in a package from repo-b. It sends a
+message via `/wr-connect:send`, and Session B (repo-b) receives it immediately through
+the Discord channel.
+
+## Install
+
+```bash
+npx @windyroad/connect
+```
+
+Or via the meta-installer:
+
+```bash
+npx @windyroad/agent-plugins --plugin connect
+```
+
+## Setup
+
+Run the interactive setup skill:
+
+```
+/wr-connect:setup
+```
+
+This walks you through:
+1. Creating a Discord bot
+2. Configuring environment variables (bot token, channel ID, session name)
+3. Installing the Discord channel plugin
+4. Configuring the security allowlist
+
+You can opt out at any point during setup.
+
+## Usage
+
+### Sending a message
+
+```
+/wr-connect:send BUG: Widget.parse() throws on null input at line 47
+```
+
+### Receiving messages
+
+Start Claude Code with the channels flag:
+
+```bash
+claude --channels plugin:discord@claude-plugins-official
+```
+
+No explicit "wait" command is needed. The session listens automatically and wakes
+when a message arrives.
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `WR_CONNECT_BOT_TOKEN` | Discord bot token |
+| `WR_CONNECT_CHANNEL_ID` | Discord channel ID |
+| `WR_CONNECT_SESSION_NAME` | Human-readable name for this session (e.g. `repo-b`) |
+
+Set these in your shell profile (`~/.zshrc`, `~/.bashrc`) or a `.env` file that is
+in `.gitignore`.
+
+## Hooks
+
+| Event | Script | Behaviour |
+|-------|--------|-----------|
+| SessionStart | `session-start.sh` | Warns if env vars are set but `--channels` is not active. Silent if env vars are not set. Never blocks. |
+
+## Security
+
+- **Bot token is a credential** — it gives anyone who has it the ability to send
+  messages to your Claude Code session (which has filesystem and shell access).
+  Treat it like a password.
+- **Environment variables only** — tokens are never stored in project files.
+  This is consistent with the suite's `secret-leak-gate`.
+- **Discord allowlist** — configure the Discord channel plugin to only accept
+  messages from your own Discord user ID.
+- **Private channel** — use a private Discord server or channel.
+- **Dedicated bot** — use one bot per developer, not a shared team bot.
+
+## Update
+
+```bash
+npx @windyroad/connect --update
+```
+
+## Uninstall
+
+```bash
+npx @windyroad/connect --uninstall
+```
+
+## Licence
+
+MIT

package/bin/install.mjs

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+
+import { resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const utils = await import(resolve(__dirname, "../lib/install-utils.mjs"));
+
+const PLUGIN = "wr-connect";
+const DEPS = [];
+
+const flags = utils.parseStandardArgs(process.argv);
+
+if (flags.help) {
+  console.log(`
+Usage: npx @windyroad/connect [options]
+
+Connect Claude Code sessions across repos via Discord (experimental)
+
+Options:
+  --update     Update this plugin and its skills
+  --uninstall  Remove this plugin
+  --scope      Installation scope: project (default) or user
+  --dry-run    Show what would be done without executing
+  --help, -h   Show this help
+`);
+  process.exit(0);
+}
+
+if (flags.dryRun) {
+  utils.setDryRun(true);
+  console.log("[dry-run mode — no commands will be executed]\n");
+}
+
+utils.checkPrerequisites();
+
+if (flags.uninstall) {
+  utils.uninstallPackage(PLUGIN);
+} else if (flags.update) {
+  utils.updatePackage(PLUGIN);
+} else {
+  utils.installPackage(PLUGIN, { deps: DEPS, scope: flags.scope });
+}

package/hooks/hooks.json

@@ -0,0 +1,7 @@
+{
+  "hooks": {
+    "SessionStart": [
+      { "hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/session-start.sh" }] }
+    ]
+  }
+}

package/hooks/session-start.sh

@@ -0,0 +1,43 @@
+#!/bin/bash
+# wr-connect - SessionStart hook
+# Warns if env vars are configured but --channels is not active.
+# Always exits 0 (warns, never blocks).
+
+# If bot token is not set, plugin is inactive — exit silently
+if [ -z "${WR_CONNECT_BOT_TOKEN:-}" ]; then
+  exit 0
+fi
+
+# If --channels is active, output collaboration primer
+# NOTE: CLAUDE_CHANNELS is the expected env var when --channels is active.
+# This may change in future Claude Code versions; update if needed.
+if [ -n "${CLAUDE_CHANNELS:-}" ]; then
+  SESSION_NAME="${WR_CONNECT_SESSION_NAME:-unnamed}"
+  cat <<PRIMER
+wr-connect: Collaboration channel active. Your session name is "${SESSION_NAME}".
+
+You are connected to a shared channel with other Claude Code sessions and
+potentially human participants. Follow these guidelines:
+
+LISTENING:
+- Read all messages for context, but only respond if relevant to your work.
+- Messages containing @${SESSION_NAME} are directed at you — prioritise these.
+- Messages with @someone-else are for another session — read for context but
+  stay quiet unless you have something relevant to add.
+- Messages with no @ are broadcast — respond if relevant to your domain.
+
+SENDING:
+- Use /wr-connect:send to message the channel.
+- Use @<session-name> to direct a message to a specific session.
+- Be concise — other sessions will read your messages too.
+PRIMER
+  exit 0
+fi
+
+# Env vars set but --channels not active — warn
+cat <<'EOF'
+wr-connect: Environment configured but --channels is not active.
+To enable cross-repo collaboration, restart with:
+  claude --channels plugin:discord@claude-plugins-official
+EOF
+exit 0

package/hooks/test/session-start.bats

@@ -0,0 +1,48 @@
+#!/usr/bin/env bats
+
+# Tests for session-start.sh (SessionStart hook)
+# Verifies three states: no config, config without channels, config with channels.
+
+setup() {
+  SCRIPT_DIR="$(cd "$(dirname "$BATS_TEST_FILENAME")/.." && pwd)"
+  HOOK="$SCRIPT_DIR/session-start.sh"
+  # Clear env vars for each test
+  unset WR_CONNECT_BOT_TOKEN
+  unset WR_CONNECT_CHANNEL_ID
+  unset WR_CONNECT_SESSION_NAME
+  unset CLAUDE_CHANNELS
+}
+
+@test "no env vars: exits 0, no output" {
+  run "$HOOK"
+  [ "$status" -eq 0 ]
+  [ -z "$output" ]
+}
+
+@test "env vars set, no CLAUDE_CHANNELS: exits 0, warns about --channels" {
+  export WR_CONNECT_BOT_TOKEN="test-token"
+  run "$HOOK"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"--channels"* ]]
+  [[ "$output" == *"plugin:discord@claude-plugins-official"* ]]
+}
+
+@test "env vars set, CLAUDE_CHANNELS active: exits 0, outputs primer with session name" {
+  export WR_CONNECT_BOT_TOKEN="test-token"
+  export WR_CONNECT_SESSION_NAME="repo-b"
+  export CLAUDE_CHANNELS=1
+  run "$HOOK"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"repo-b"* ]]
+  [[ "$output" == *"@repo-b"* ]]
+}
+
+@test "primer tells agent to prioritise @mentions" {
+  export WR_CONNECT_BOT_TOKEN="test-token"
+  export WR_CONNECT_SESSION_NAME="my-repo"
+  export CLAUDE_CHANNELS=1
+  run "$HOOK"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"@my-repo"* ]]
+  [[ "$output" == *"relevant"* ]]
+}

package/lib/install-utils.mjs

@@ -0,0 +1,143 @@
+/**
+ * Shared install utilities for @windyroad/* packages.
+ * Used by both per-plugin installers and the meta-installer.
+ */
+
+import { execSync } from "node:child_process";
+
+const MARKETPLACE_REPO = "windyroad/agent-plugins";
+const MARKETPLACE_NAME = "windyroad";
+
+let _dryRun = false;
+
+export { MARKETPLACE_REPO, MARKETPLACE_NAME };
+
+export function setDryRun(value) {
+  _dryRun = value;
+}
+
+export function isDryRun() {
+  return _dryRun;
+}
+
+export function run(cmd, label) {
+  console.log(`  ${label}...`);
+  if (_dryRun) {
+    console.log(`    [dry-run] ${cmd}`);
+    return true;
+  }
+  try {
+    execSync(cmd, { stdio: "inherit" });
+    return true;
+  } catch {
+    console.error(`  FAILED: ${label}`);
+    return false;
+  }
+}
+
+export function checkPrerequisites() {
+  if (_dryRun) return;
+
+  try {
+    execSync("claude --version", { stdio: "pipe" });
+  } catch {
+    console.error(
+      "Error: 'claude' CLI not found. Install Claude Code first:\n  https://docs.anthropic.com/en/docs/claude-code\n"
+    );
+    process.exit(1);
+  }
+}
+
+export function addMarketplace() {
+  return run(
+    `claude plugin marketplace add ${MARKETPLACE_REPO}`,
+    `Marketplace: ${MARKETPLACE_NAME}`
+  );
+}
+
+export function installPlugin(pluginName, { scope = "project" } = {}) {
+  return run(
+    `claude plugin install ${pluginName}@${MARKETPLACE_NAME} --scope ${scope}`,
+    pluginName
+  );
+}
+
+export function updatePlugin(pluginName) {
+  return run(`claude plugin update ${pluginName}`, pluginName);
+}
+
+export function uninstallPlugin(pluginName) {
+  return run(`claude plugin uninstall ${pluginName}`, `Removing ${pluginName}`);
+}
+
+/**
+ * Install a single package: marketplace add + plugin install.
+ */
+export function installPackage(pluginName, { deps = [], scope = "project" } = {}) {
+  console.log(`\nInstalling @windyroad/${pluginName.replace("wr-", "")} (${scope} scope)...\n`);
+
+  addMarketplace();
+  installPlugin(pluginName, { scope });
+
+  if (deps.length > 0) {
+    console.log(`\nNote: This plugin works best with:`);
+    for (const dep of deps) {
+      console.log(`  - @windyroad/${dep.replace("wr-", "")} (npx @windyroad/${dep.replace("wr-", "")})`);
+    }
+  }
+
+  console.log(
+    `\nDone! Restart Claude Code to activate.\n`
+  );
+}
+
+/**
+ * Update a single package.
+ */
+export function updatePackage(pluginName) {
+  console.log(`\nUpdating @windyroad/${pluginName.replace("wr-", "")}...\n`);
+
+  run(
+    `claude plugin marketplace update ${MARKETPLACE_NAME}`,
+    "Updating marketplace"
+  );
+  updatePlugin(pluginName);
+
+  console.log("\nDone! Restart Claude Code to apply updates.\n");
+}
+
+/**
+ * Uninstall a single package.
+ */
+export function uninstallPackage(pluginName) {
+  console.log(`\nUninstalling @windyroad/${pluginName.replace("wr-", "")}...\n`);
+
+  uninstallPlugin(pluginName);
+
+  console.log("\nDone. Restart Claude Code to apply changes.\n");
+}
+
+/**
+ * Parse standard flags used by all per-plugin installers.
+ */
+export function parseStandardArgs(argv) {
+  const args = argv.slice(2);
+  const flags = {
+    help: args.includes("--help") || args.includes("-h"),
+    uninstall: args.includes("--uninstall"),
+    update: args.includes("--update"),
+    dryRun: args.includes("--dry-run"),
+    scope: "project",
+  };
+  const scopeIdx = args.indexOf("--scope");
+  if (scopeIdx !== -1 && args[scopeIdx + 1]) {
+    const val = args[scopeIdx + 1];
+    if (["project", "user", "local"].includes(val)) {
+      flags.scope = val;
+    } else {
+      console.error("--scope requires: project, user, or local");
+      process.exit(1);
+    }
+  }
+  return flags;
+}

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@windyroad/connect",
+  "version": "0.2.0-preview.31",
+  "description": "Connect Claude Code sessions across repos via Discord (experimental)",
+  "bin": {
+    "windyroad-connect": "./bin/install.mjs"
+  },
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/windyroad/agent-plugins.git",
+    "directory": "packages/connect"
+  },
+  "keywords": [
+    "claude-code",
+    "claude-code-plugin",
+    "ai-agent",
+    "ai-coding",
+    "cross-repo",
+    "discord",
+    "collaboration"
+  ],
+  "files": [
+    "bin/",
+    "hooks/",
+    "skills/",
+    ".claude-plugin/",
+    "lib/"
+  ]
+}

package/skills/send/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: wr-connect:send
+description: Send a message to other Claude Code sessions via Discord.
+allowed-tools: Bash, AskUserQuestion
+---
+
+# Send Message
+
+Send a message from this session to other Claude Code sessions listening on the
+configured Discord channel.
+
+## Instructions
+
+### 1. Check environment variables
+
+Verify these environment variables are set:
+- `WR_CONNECT_BOT_TOKEN`
+- `WR_CONNECT_CHANNEL_ID`
+- `WR_CONNECT_SESSION_NAME`
+
+```bash
+[ -n "$WR_CONNECT_BOT_TOKEN" ] && [ -n "$WR_CONNECT_CHANNEL_ID" ] && [ -n "$WR_CONNECT_SESSION_NAME" ] && echo "OK" || echo "MISSING"
+```
+
+If any are missing, tell the user:
+
+> wr-connect is not configured. Run `/wr-connect:setup` first.
+
+Then stop.
+
+### 2. Get the message
+
+The message to send is provided via `$ARGUMENTS`.
+
+If `$ARGUMENTS` is empty, use AskUserQuestion to ask:
+
+> What message would you like to send to the other session(s)?
+> To direct your message to a specific session, start with @session-name.
+
+### 3. Send the message
+
+Format the message as: `[wr-connect] from: <SESSION_NAME> | <message>`
+
+**@mentions:** If the user's message starts with `@<name>`, preserve it as-is in the
+message body. This tells the target session to prioritise the message. Messages
+without an `@` are treated as broadcast to all listening sessions.
+
+Send via the Discord API:
+
+```bash
+curl -s -o /tmp/wr-connect-response.json -w "%{http_code}" \
+  -X POST "https://discord.com/api/v10/channels/${WR_CONNECT_CHANNEL_ID}/messages" \
+  -H "Authorization: Bot ${WR_CONNECT_BOT_TOKEN}" \
+  -H "Content-Type: application/json" \
+  -d "{\"content\": \"[wr-connect] from: ${WR_CONNECT_SESSION_NAME} | <MESSAGE>\"}"
+```
+
+Replace `<MESSAGE>` with the actual message content. Escape any double quotes in the
+message before inserting into the JSON payload.
+
+### 4. Report result
+
+Check the HTTP status code returned by curl:
+- **200** or **201**: Message sent successfully. Report the formatted message to the user.
+- **429**: Rate limited. Tell the user to wait a moment and try again.
+- **401** or **403**: Authentication failed. Tell the user to check their bot token.
+- **Other**: Report the status code and response body for debugging.
+
+## Examples
+
+**Broadcast (all sessions):**
+```
+/wr-connect:send BUG: Widget.parse() throws on null input at line 47
+```
+Sends:
+```
+[wr-connect] from: repo-a | BUG: Widget.parse() throws on null input at line 47
+```
+
+**Directed (specific session):**
+```
+/wr-connect:send @repo-b BUG: Widget.parse() throws on null input at line 47
+```
+Sends:
+```
+[wr-connect] from: repo-a | @repo-b BUG: Widget.parse() throws on null input at line 47
+```
+
+$ARGUMENTS

package/skills/setup/SKILL.md

@@ -0,0 +1,168 @@
+---
+name: wr-connect:setup
+description: Set up cross-repo collaboration via Discord. Interactive walkthrough with explicit opt-out before any configuration.
+allowed-tools: Read, Bash, Glob, Grep, AskUserQuestion
+---
+
+# Connect Setup
+
+> **EXPERIMENTAL:** This plugin uses Claude Code's `--channels` feature, which is a
+> research preview. The API surface may change. See ADR-006 for details.
+
+This skill configures Discord as a collaboration channel so Claude Code sessions
+across different repos can communicate with zero idle token cost.
+
+## Steps
+
+### 1. Explain what this does
+
+Tell the user:
+
+> This plugin connects your Claude Code sessions across repos so they can
+> collaborate. For example, if Session A discovers a bug in a package from repo-b,
+> it can notify Session B (which is working on repo-b) without Session B polling or
+> wasting tokens. Sessions can hand off findings, ask questions, share context, or
+> coordinate work.
+>
+> It works by using Discord as a message channel. You will need:
+> - A Discord account
+> - A Discord bot (created in the next step)
+> - A private Discord server or channel
+
+### 2. Opt-out checkpoint
+
+Use AskUserQuestion to ask the user:
+
+> Would you like to proceed with setting up cross-repo collaboration via Discord?
+> This will require creating a Discord bot and configuring environment variables.
+> No files will be written to your project.
+>
+> Reply **yes** to continue or **no** to skip.
+
+If the user says no, respond with:
+
+> Setup skipped. The connect plugin is inactive until configured.
+> Run `/wr-connect:setup` any time to start again.
+
+Then stop — do not proceed to any further steps.
+
+### 3. Create a Discord bot
+
+Guide the user through these steps:
+
+1. Go to https://discord.com/developers/applications
+2. Click **New Application** — name it something like `claude-connect`
+3. Go to **Bot** > click **Add Bot** > confirm
+4. Under **Token**, click **Reset Token** and copy it — they will need it in step 5
+5. Under **Privileged Gateway Intents**, enable **Message Content Intent**
+6. Go to **OAuth2 > URL Generator**:
+   - Scopes: `bot`
+   - Bot permissions: `Send Messages`, `Read Messages/View Channels`
+7. Copy the generated URL, open it in a browser, and add the bot to their server
+
+### 4. Get the channel ID
+
+Guide the user:
+
+1. In Discord, go to **User Settings > Advanced** and enable **Developer Mode**
+2. Right-click the channel to use for collaboration and click **Copy Channel ID**
+
+### 5. Configure environment variables
+
+Guide the user to add these to their shell profile (`~/.zshrc`, `~/.bashrc`) or a
+`.env` file that is already in `.gitignore`:
+
+```bash
+export WR_CONNECT_BOT_TOKEN="<the bot token from step 3>"
+export WR_CONNECT_CHANNEL_ID="<the channel ID from step 4>"
+export WR_CONNECT_SESSION_NAME="<a name for this session, e.g. repo-b>"
+```
+
+**Security warning:** The bot token gives anyone who has it the ability to send
+messages to your Claude Code session. Never commit it to source control. Use
+environment variables or a `.env` file that is in `.gitignore`.
+
+If the user chooses a `.env` file, verify `.env` is in `.gitignore`:
+
+```bash
+grep -q '\.env' .gitignore 2>/dev/null && echo ".env is in .gitignore" || echo "WARNING: .env is NOT in .gitignore — add it now"
+```
+
+### 6. Verify environment variables
+
+Check the env vars are set in the current shell:
+
+```bash
+[ -n "$WR_CONNECT_BOT_TOKEN" ] && echo "BOT_TOKEN: set" || echo "BOT_TOKEN: NOT SET"
+[ -n "$WR_CONNECT_CHANNEL_ID" ] && echo "CHANNEL_ID: set" || echo "CHANNEL_ID: NOT SET"
+[ -n "$WR_CONNECT_SESSION_NAME" ] && echo "SESSION_NAME: set" || echo "SESSION_NAME: NOT SET"
+```
+
+If any are not set, remind the user to `source ~/.zshrc` (or their profile) or
+restart their terminal before continuing.
+
+### 7. Install the Discord channel plugin
+
+```bash
+claude plugin install discord@claude-plugins-official
+```
+
+### 8. Restart with channels active
+
+Tell the user to restart Claude Code with:
+
+```bash
+claude --channels plugin:discord@claude-plugins-official
+```
+
+Claude will send a pairing code. Follow the prompts to pair the Discord account.
+
+### 9. Configure the Discord allowlist (security)
+
+This is critical. Without the allowlist, anyone who can message the bot can send
+instructions to the Claude Code session.
+
+Guide the user to configure the allowlist so only their own Discord user ID can
+send messages. The exact command depends on the Discord channel plugin's interface —
+check its documentation for the allowlist or access policy setting.
+
+Tell the user:
+
+> To find your Discord user ID: In Discord with Developer Mode enabled,
+> click your username at the bottom left, then click **Copy User ID**.
+
+### 10. Test the setup
+
+Ask the user if they would like to send a test message. If yes, tell them to use:
+
+```
+/wr-connect:send test message from setup
+```
+
+Or from another terminal:
+
+```bash
+curl -s -X POST "https://discord.com/api/v10/channels/$WR_CONNECT_CHANNEL_ID/messages" \
+  -H "Authorization: Bot $WR_CONNECT_BOT_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"content": "[wr-connect] from: test | setup verification"}'
+```
+
+If the session with `--channels` active receives the message, setup is complete.
+
+### 11. Explain collaboration behaviour
+
+Tell the user:
+
+> Your session is now part of a shared collaboration channel. Here's how it works:
+>
+> - **Multiple sessions and humans** can share the same Discord channel.
+> - Use `@session-name` in messages to direct them at a specific session
+>   (e.g. `/wr-connect:send @repo-b please fix Widget.parse()`).
+> - Messages without `@` are broadcast — all sessions see them.
+> - Each session reads everything for context but only responds when the message
+>   is relevant to its work.
+> - Your session name is whatever you set in `WR_CONNECT_SESSION_NAME`. Other
+>   sessions will use `@your-name` to get your attention.
+
+$ARGUMENTS