feat(setup): add Slack and iMessage channel flows (experimental)

Slack: interactive driver walks through app creation, validates the
bot token via auth.test, installs the adapter, and prints a
post-install checklist for the webhook URL + Event Subscriptions
config. No welcome DM since Slack needs a public URL before inbound
events work — the driver's own "finish in Slack" note replaces the
outro "check your DMs" banner.

iMessage: picks local (macOS) vs remote (Photon) mode. Local mode
opens the node binary's directory in Finder so the user can drag it
into Full Disk Access. Remote mode prompts for Photon URL + API key.
Asks for the operator's phone/email, then wires the first agent
including a welcome iMessage.

Both marked "(experimental)" in the askChannelChoice picker.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

setup/add-imessage.sh

@@ -0,0 +1,160 @@
+#!/usr/bin/env bash
+#
+# Install the iMessage adapter, persist mode/creds to .env + data/env/env,
+# and restart the service. Non-interactive — the Full Disk Access walkthrough
+# (local mode) and Photon URL/key prompts (remote mode) live in
+# setup/channels/imessage.ts. Creds come in via env vars:
+#   IMESSAGE_LOCAL   'true' | 'false'  (required)
+#   IMESSAGE_ENABLED 'true'            (required when IMESSAGE_LOCAL=true)
+#   IMESSAGE_SERVER_URL                (required when IMESSAGE_LOCAL=false)
+#   IMESSAGE_API_KEY                   (required when IMESSAGE_LOCAL=false)
+#
+# Emits exactly one status block on stdout (ADD_IMESSAGE) at the end.
+set -euo pipefail
+
+PROJECT_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+cd "$PROJECT_ROOT"
+
+# Keep in sync with .claude/skills/add-imessage/SKILL.md.
+ADAPTER_VERSION="chat-adapter-imessage@0.1.1"
+
+# Resolve which remote carries the channels branch — handles forks where
+# upstream lives on a different remote than `origin`.
+# shellcheck source=setup/lib/channels-remote.sh
+source "$PROJECT_ROOT/setup/lib/channels-remote.sh"
+CHANNELS_REMOTE=$(resolve_channels_remote)
+CHANNELS_BRANCH="${CHANNELS_REMOTE}/channels"
+
+emit_status() {
+  local status=$1 error=${2:-}
+  local already=${ADAPTER_ALREADY_INSTALLED:-false}
+  local mode=${IMESSAGE_LOCAL:-}
+  echo "=== NANOCLAW SETUP: ADD_IMESSAGE ==="
+  echo "STATUS: ${status}"
+  echo "ADAPTER_VERSION: ${ADAPTER_VERSION}"
+  echo "ADAPTER_ALREADY_INSTALLED: ${already}"
+  [ -n "$mode" ] && echo "MODE: $([ "$mode" = "true" ] && echo local || echo remote)"
+  [ -n "$error" ] && echo "ERROR: ${error}"
+  echo "=== END ==="
+}
+
+log() { echo "[add-imessage] $*" >&2; }
+
+# Validate creds based on mode.
+if [ -z "${IMESSAGE_LOCAL:-}" ]; then
+  emit_status failed "IMESSAGE_LOCAL env var not set (expected true|false)"
+  exit 1
+fi
+if [ "${IMESSAGE_LOCAL}" = "true" ]; then
+  if [ -z "${IMESSAGE_ENABLED:-}" ]; then
+    emit_status failed "IMESSAGE_ENABLED env var not set for local mode"
+    exit 1
+  fi
+  if [ "$(uname -s)" != "Darwin" ]; then
+    emit_status failed "local mode requires macOS"
+    exit 1
+  fi
+else
+  if [ -z "${IMESSAGE_SERVER_URL:-}" ]; then
+    emit_status failed "IMESSAGE_SERVER_URL env var not set for remote mode"
+    exit 1
+  fi
+  if [ -z "${IMESSAGE_API_KEY:-}" ]; then
+    emit_status failed "IMESSAGE_API_KEY env var not set for remote mode"
+    exit 1
+  fi
+fi
+
+need_install() {
+  [ ! -f src/channels/imessage.ts ] && return 0
+  ! grep -q "^import './imessage.js';" src/channels/index.ts 2>/dev/null && return 0
+  return 1
+}
+
+ADAPTER_ALREADY_INSTALLED=true
+if need_install; then
+  ADAPTER_ALREADY_INSTALLED=false
+  log "Fetching channels branch…"
+  git fetch "$CHANNELS_REMOTE" channels >&2 2>/dev/null || {
+    emit_status failed "git fetch ${CHANNELS_REMOTE} channels failed"
+    exit 1
+  }
+
+  log "Copying adapter from ${CHANNELS_BRANCH}…"
+  git show "${CHANNELS_BRANCH}:src/channels/imessage.ts" > src/channels/imessage.ts
+
+  # Append self-registration import if missing.
+  if ! grep -q "^import './imessage.js';" src/channels/index.ts; then
+    echo "import './imessage.js';" >> src/channels/index.ts
+  fi
+
+  log "Installing ${ADAPTER_VERSION}…"
+  pnpm install "${ADAPTER_VERSION}" >&2 2>/dev/null || {
+    emit_status failed "pnpm install ${ADAPTER_VERSION} failed"
+    exit 1
+  }
+
+  log "Building…"
+  pnpm run build >&2 2>/dev/null || {
+    emit_status failed "pnpm run build failed"
+    exit 1
+  }
+else
+  log "Adapter files already installed — skipping install phase."
+fi
+
+touch .env
+upsert_env() {
+  local key=$1 value=$2
+  if grep -q "^${key}=" .env; then
+    awk -v k="$key" -v v="$value" \
+        'BEGIN{FS=OFS="="} $1==k {print k "=" v; next} {print}' \
+      .env > .env.tmp && mv .env.tmp .env
+  else
+    echo "${key}=${value}" >> .env
+  fi
+}
+
+remove_env() {
+  local key=$1
+  if grep -q "^${key}=" .env 2>/dev/null; then
+    grep -v "^${key}=" .env > .env.tmp && mv .env.tmp .env
+  fi
+}
+
+# Write the canonical keys for the chosen mode, strip the opposite mode's
+# keys so stale values can't confuse the adapter's factory.
+upsert_env IMESSAGE_LOCAL "$IMESSAGE_LOCAL"
+if [ "$IMESSAGE_LOCAL" = "true" ]; then
+  upsert_env IMESSAGE_ENABLED "$IMESSAGE_ENABLED"
+  remove_env IMESSAGE_SERVER_URL
+  remove_env IMESSAGE_API_KEY
+else
+  upsert_env IMESSAGE_SERVER_URL "$IMESSAGE_SERVER_URL"
+  upsert_env IMESSAGE_API_KEY "$IMESSAGE_API_KEY"
+  remove_env IMESSAGE_ENABLED
+fi
+
+# Container reads from data/env/env (the host mounts it).
+mkdir -p data/env
+cp .env data/env/env
+
+log "Restarting service so the new adapter picks up the creds…"
+# shellcheck source=setup/lib/install-slug.sh
+source "$PROJECT_ROOT/setup/lib/install-slug.sh"
+case "$(uname -s)" in
+  Darwin)
+    launchctl kickstart -k "gui/$(id -u)/$(launchd_label)" >&2 2>/dev/null || true
+    ;;
+  Linux)
+    systemctl --user restart "$(systemd_unit)" >&2 2>/dev/null \
+      || sudo systemctl restart "$(systemd_unit)" >&2 2>/dev/null \
+      || true
+    ;;
+esac
+
+# Give the adapter a moment to open chat.db (local) or handshake with
+# Photon (remote) before emitting success.
+sleep 3
+
+emit_status success

setup/add-slack.sh

@@ -0,0 +1,125 @@
+#!/usr/bin/env bash
+#
+# Install the Slack adapter, persist SLACK_BOT_TOKEN + SLACK_SIGNING_SECRET to
+# .env + data/env/env, and restart the service. Non-interactive — the
+# operator-facing app creation walkthrough + credential paste live in
+# setup/channels/slack.ts. Credentials come in via env vars:
+# SLACK_BOT_TOKEN, SLACK_SIGNING_SECRET.
+#
+# Emits exactly one status block on stdout (ADD_SLACK) at the end. All chatty
+# progress messages go to stderr so setup:auto's raw-log capture sees the full
+# story without cluttering the final block for the parser.
+set -euo pipefail
+
+PROJECT_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+cd "$PROJECT_ROOT"
+
+# Keep in sync with .claude/skills/add-slack/SKILL.md.
+ADAPTER_VERSION="@chat-adapter/slack@4.26.0"
+
+# Resolve which remote carries the channels branch — handles forks where
+# upstream lives on a different remote than `origin`.
+# shellcheck source=setup/lib/channels-remote.sh
+source "$PROJECT_ROOT/setup/lib/channels-remote.sh"
+CHANNELS_REMOTE=$(resolve_channels_remote)
+CHANNELS_BRANCH="${CHANNELS_REMOTE}/channels"
+
+emit_status() {
+  local status=$1 error=${2:-}
+  local already=${ADAPTER_ALREADY_INSTALLED:-false}
+  echo "=== NANOCLAW SETUP: ADD_SLACK ==="
+  echo "STATUS: ${status}"
+  echo "ADAPTER_VERSION: ${ADAPTER_VERSION}"
+  echo "ADAPTER_ALREADY_INSTALLED: ${already}"
+  [ -n "$error" ] && echo "ERROR: ${error}"
+  echo "=== END ==="
+}
+
+log() { echo "[add-slack] $*" >&2; }
+
+if [ -z "${SLACK_BOT_TOKEN:-}" ]; then
+  emit_status failed "SLACK_BOT_TOKEN env var not set"
+  exit 1
+fi
+if [ -z "${SLACK_SIGNING_SECRET:-}" ]; then
+  emit_status failed "SLACK_SIGNING_SECRET env var not set"
+  exit 1
+fi
+
+need_install() {
+  [ ! -f src/channels/slack.ts ] && return 0
+  ! grep -q "^import './slack.js';" src/channels/index.ts 2>/dev/null && return 0
+  return 1
+}
+
+ADAPTER_ALREADY_INSTALLED=true
+if need_install; then
+  ADAPTER_ALREADY_INSTALLED=false
+  log "Fetching channels branch…"
+  git fetch "$CHANNELS_REMOTE" channels >&2 2>/dev/null || {
+    emit_status failed "git fetch ${CHANNELS_REMOTE} channels failed"
+    exit 1
+  }
+
+  log "Copying adapter from ${CHANNELS_BRANCH}…"
+  git show "${CHANNELS_BRANCH}:src/channels/slack.ts" > src/channels/slack.ts
+
+  # Append self-registration import if missing.
+  if ! grep -q "^import './slack.js';" src/channels/index.ts; then
+    echo "import './slack.js';" >> src/channels/index.ts
+  fi
+
+  log "Installing ${ADAPTER_VERSION}…"
+  pnpm install "${ADAPTER_VERSION}" >&2 2>/dev/null || {
+    emit_status failed "pnpm install ${ADAPTER_VERSION} failed"
+    exit 1
+  }
+
+  log "Building…"
+  pnpm run build >&2 2>/dev/null || {
+    emit_status failed "pnpm run build failed"
+    exit 1
+  }
+else
+  log "Adapter files already installed — skipping install phase."
+fi
+
+# Persist credentials. auto.ts validates via auth.test before this point, so
+# bad values here would be an internal bug rather than operator input.
+touch .env
+upsert_env() {
+  local key=$1 value=$2
+  if grep -q "^${key}=" .env; then
+    awk -v k="$key" -v v="$value" \
+        'BEGIN{FS=OFS="="} $1==k {print k "=" v; next} {print}' \
+      .env > .env.tmp && mv .env.tmp .env
+  else
+    echo "${key}=${value}" >> .env
+  fi
+}
+upsert_env SLACK_BOT_TOKEN "$SLACK_BOT_TOKEN"
+upsert_env SLACK_SIGNING_SECRET "$SLACK_SIGNING_SECRET"
+
+# Container reads from data/env/env (the host mounts it).
+mkdir -p data/env
+cp .env data/env/env
+
+log "Restarting service so the new adapter picks up the credentials…"
+# shellcheck source=setup/lib/install-slug.sh
+source "$PROJECT_ROOT/setup/lib/install-slug.sh"
+case "$(uname -s)" in
+  Darwin)
+    launchctl kickstart -k "gui/$(id -u)/$(launchd_label)" >&2 2>/dev/null || true
+    ;;
+  Linux)
+    systemctl --user restart "$(systemd_unit)" >&2 2>/dev/null \
+      || sudo systemctl restart "$(systemd_unit)" >&2 2>/dev/null \
+      || true
+    ;;
+esac
+
+# Give the Slack adapter a moment to finish starting the webhook listener
+# before emitting success.
+sleep 3
+
+emit_status success

setup/auto.ts

@@ -27,6 +27,8 @@ import * as p from '@clack/prompts';
 import k from 'kleur';
 
 import { runDiscordChannel } from './channels/discord.js';
+import { runIMessageChannel } from './channels/imessage.js';
+import { runSlackChannel } from './channels/slack.js';
 import { runTeamsChannel } from './channels/teams.js';
 import { runTelegramChannel } from './channels/telegram.js';
 import { runWhatsAppChannel } from './channels/whatsapp.js';
@@ -48,6 +50,15 @@ import { isValidTimezone } from '../src/timezone.js';
 const CLI_AGENT_NAME = 'Terminal Agent';
 const RUN_START = Date.now();
 
+type ChannelChoice =
+  | 'telegram'
+  | 'discord'
+  | 'whatsapp'
+  | 'teams'
+  | 'slack'
+  | 'imessage'
+  | 'skip';
+
 async function main(): Promise<void> {
   printIntro();
   initProgressionLog();
@@ -295,8 +306,7 @@ async function main(): Promise<void> {
     await runTimezoneStep();
   }
 
-  let channelChoice: 'telegram' | 'discord' | 'whatsapp' | 'teams' | 'skip' =
-    'skip';
+  let channelChoice: ChannelChoice = 'skip';
   if (!skip.has('channel')) {
     channelChoice = await askChannelChoice();
     if (channelChoice === 'telegram') {
@@ -307,10 +317,14 @@ async function main(): Promise<void> {
       await runWhatsAppChannel(displayName!);
     } else if (channelChoice === 'teams') {
       await runTeamsChannel(displayName!);
+    } else if (channelChoice === 'slack') {
+      await runSlackChannel(displayName!);
+    } else if (channelChoice === 'imessage') {
+      await runIMessageChannel(displayName!);
     } else {
       p.log.info(
         wrapForGutter(
-          'No messaging app for now. You can add one later (like Telegram, Discord, WhatsApp, Teams, or Slack).',
+          'No messaging app for now. You can add one later (like Telegram, Discord, WhatsApp, Teams, Slack, or iMessage).',
           4,
         ),
       );
@@ -420,9 +434,7 @@ async function main(): Promise<void> {
   }
 }
 
-function channelDmLabel(
-  choice: 'telegram' | 'discord' | 'whatsapp' | 'teams' | 'skip',
-): string | null {
+function channelDmLabel(choice: ChannelChoice): string | null {
   switch (choice) {
     case 'telegram':
       return 'Telegram';
@@ -432,6 +444,13 @@ function channelDmLabel(
       return 'WhatsApp';
     case 'teams':
       return 'Teams';
+    case 'imessage':
+      return 'iMessage';
+    case 'slack':
+      // Slack install doesn't wire an agent or send a welcome DM — the
+      // driver prints its own "finish in your Slack app" note. Falling
+      // through to null avoids a misleading "check your Slack DMs" banner.
+      return null;
     default:
       return null;
   }
@@ -807,16 +826,25 @@ async function askDisplayName(fallback: string): Promise<string> {
   return value;
 }
 
-async function askChannelChoice(): Promise<
-  'telegram' | 'discord' | 'whatsapp' | 'teams' | 'skip'
-> {
+async function askChannelChoice(): Promise<ChannelChoice> {
+  const isMac = process.platform === 'darwin';
   const choice = ensureAnswer(
-    await brightSelect({
+    await brightSelect<ChannelChoice>({
       message: 'Want to chat with your assistant from your phone?',
       options: [
         { value: 'telegram', label: 'Yes, connect Telegram', hint: 'recommended' },
         { value: 'discord', label: 'Yes, connect Discord' },
         { value: 'whatsapp', label: 'Yes, connect WhatsApp' },
+        {
+          value: 'imessage',
+          label: 'Yes, connect iMessage (experimental)',
+          hint: isMac ? 'local macOS mode' : 'remote Photon only',
+        },
+        {
+          value: 'slack',
+          label: 'Yes, connect Slack (experimental)',
+          hint: 'needs public URL',
+        },
         { value: 'teams', label: 'Yes, connect Microsoft Teams', hint: 'complex setup' },
         { value: 'skip', label: 'Skip for now', hint: "I'll just use the terminal" },
       ],
@@ -824,7 +852,7 @@ async function askChannelChoice(): Promise<
   );
   setupLog.userInput('channel_choice', String(choice));
   phEmit('channel_chosen', { channel: String(choice) });
-  return choice as 'telegram' | 'discord' | 'whatsapp' | 'teams' | 'skip';
+  return choice;
 }
 
 // ─── interactive / env helpers ─────────────────────────────────────────

setup/channels/imessage.ts

@@ -0,0 +1,314 @@
+/**
+ * iMessage channel flow for setup:auto.
+ *
+ * `runIMessageChannel(displayName)` covers both deployment modes:
+ *
+ *   Local (macOS): the bot runs on this Mac and talks via the signed-in
+ *   iMessage account. Reading chat.db needs Full Disk Access granted to
+ *   the Node binary — we open the directory for them so they can drag
+ *   the `node` file into System Settings.
+ *
+ *   Remote (Photon API): the bot talks to a separate server (Photon)
+ *   that owns an iMessage account on another Mac. Used when this host
+ *   is Linux, or when the operator wants to keep their daily-driver
+ *   Mac's chat history out of the loop.
+ *
+ * Flow:
+ *   1. Pick mode (auto-defaults to local on macOS, remote elsewhere)
+ *   2. Local: FDA walkthrough (open node bin directory, wait for ack)
+ *      Remote: prompt for Photon server URL + API key
+ *   3. Ask for the phone or email the operator messages from — this is
+ *      the platform-id for first-agent wiring
+ *   4. Install the adapter (setup/add-imessage.sh, non-interactive)
+ *   5. Wire the agent via scripts/init-first-agent.ts — the welcome
+ *      iMessage goes out through the normal delivery path
+ *
+ * All output obeys the three-level contract. See docs/setup-flow.md.
+ */
+import { execSync } from 'child_process';
+import os from 'os';
+import path from 'path';
+
+import * as p from '@clack/prompts';
+import k from 'kleur';
+
+import * as setupLog from '../logs.js';
+import { brightSelect } from '../lib/bright-select.js';
+import { askOperatorRole } from '../lib/role-prompt.js';
+import { ensureAnswer, fail, runQuietChild } from '../lib/runner.js';
+import { wrapForGutter } from '../lib/theme.js';
+
+const DEFAULT_AGENT_NAME = 'Nano';
+
+type Mode = 'local' | 'remote';
+
+interface RemoteCreds {
+  serverUrl: string;
+  apiKey: string;
+}
+
+export async function runIMessageChannel(displayName: string): Promise<void> {
+  const isMac = os.platform() === 'darwin';
+
+  const mode = await askMode(isMac);
+  let remoteCreds: RemoteCreds | null = null;
+
+  if (mode === 'local') {
+    if (!isMac) {
+      await fail(
+        'imessage',
+        "Local iMessage mode only works on macOS.",
+        'Choose remote mode (Photon API) on Linux/WSL, or run setup from your Mac.',
+      );
+    }
+    await walkThroughFullDiskAccess();
+  } else {
+    remoteCreds = await collectRemoteCreds();
+  }
+
+  const handle = await askOperatorHandle();
+
+  const install = await runQuietChild(
+    'imessage-install',
+    'bash',
+    ['setup/add-imessage.sh'],
+    {
+      running:
+        mode === 'local'
+          ? "Connecting the iMessage adapter to this Mac…"
+          : `Connecting the iMessage adapter to ${remoteCreds!.serverUrl}…`,
+      done: 'iMessage adapter installed.',
+    },
+    {
+      env:
+        mode === 'local'
+          ? { IMESSAGE_LOCAL: 'true', IMESSAGE_ENABLED: 'true' }
+          : {
+              IMESSAGE_LOCAL: 'false',
+              IMESSAGE_SERVER_URL: remoteCreds!.serverUrl,
+              IMESSAGE_API_KEY: remoteCreds!.apiKey,
+            },
+      extraFields: { MODE: mode },
+    },
+  );
+  if (!install.ok) {
+    await fail(
+      'imessage-install',
+      "Couldn't install the iMessage adapter.",
+      'See logs/setup-steps/ for details, then retry setup.',
+    );
+  }
+
+  const role = await askOperatorRole('iMessage');
+  setupLog.userInput('imessage_role', role);
+
+  const agentName = await resolveAgentName();
+
+  const init = await runQuietChild(
+    'init-first-agent',
+    'pnpm',
+    [
+      'exec', 'tsx', 'scripts/init-first-agent.ts',
+      '--channel', 'imessage',
+      '--user-id', handle,
+      '--platform-id', handle,
+      '--display-name', displayName,
+      '--agent-name', agentName,
+      '--role', role,
+    ],
+    {
+      running: `Connecting ${agentName} to iMessage…`,
+      done: `${agentName} is ready. Check iMessage for a welcome message.`,
+    },
+    {
+      extraFields: {
+        CHANNEL: 'imessage',
+        AGENT_NAME: agentName,
+        PLATFORM_ID: handle,
+        MODE: mode,
+      },
+    },
+  );
+  if (!init.ok) {
+    await fail(
+      'init-first-agent',
+      `Couldn't finish connecting ${agentName}.`,
+      'Double-check Full Disk Access (local mode) or Photon credentials (remote), then retry.',
+    );
+  }
+}
+
+async function askMode(isMac: boolean): Promise<Mode> {
+  const choice = ensureAnswer(
+    await brightSelect<Mode>({
+      message: 'How should iMessage run?',
+      initialValue: isMac ? 'local' : 'remote',
+      options: isMac
+        ? [
+            {
+              value: 'local',
+              label: 'Local (this Mac)',
+              hint: "uses this machine's iMessage account",
+            },
+            {
+              value: 'remote',
+              label: 'Remote (Photon API)',
+              hint: 'the bot lives on another server',
+            },
+          ]
+        : [
+            {
+              value: 'remote',
+              label: 'Remote (Photon API)',
+              hint: 'only option off macOS',
+            },
+          ],
+    }),
+  );
+  setupLog.userInput('imessage_mode', String(choice));
+  return choice;
+}
+
+/**
+ * Grant Full Disk Access to the Node binary the host runs under — without
+ * it, the adapter can't read chat.db and inbound messages never arrive.
+ * Opening the containing directory in Finder makes the drag-and-drop
+ * target obvious; falling back to printing the path keeps us working in
+ * SSH/headless contexts where `open` is a no-op.
+ */
+async function walkThroughFullDiskAccess(): Promise<void> {
+  let nodePath = process.execPath;
+  try {
+    // `which node` picks up the user's shell-resolved node, which may differ
+    // from process.execPath (e.g. they launched setup under a different
+    // Node via `nvm`). If it succeeds and is resolvable, prefer it.
+    const which = execSync('which node', { encoding: 'utf-8' }).trim();
+    if (which) nodePath = which;
+  } catch {
+    // fall back to process.execPath
+  }
+  const nodeDir = path.dirname(nodePath);
+
+  p.note(
+    wrapForGutter(
+      [
+        `iMessage needs Full Disk Access granted to the Node binary:`,
+        '',
+        `  ${nodePath}`,
+        '',
+        '  1. System Settings → Privacy & Security → Full Disk Access',
+        `  2. Click +, then drag the "node" file from the Finder window`,
+        '     we just opened for you',
+        '  3. Toggle it on, then come back here',
+      ].join('\n'),
+      6,
+    ),
+    'Grant Full Disk Access',
+  );
+
+  try {
+    execSync(`open "${nodeDir}"`, { stdio: 'ignore' });
+  } catch {
+    // No Finder (SSH/headless) — user sees the path in the note above.
+  }
+
+  ensureAnswer(
+    await p.confirm({
+      message: "Granted Full Disk Access?",
+      initialValue: true,
+    }),
+  );
+  setupLog.userInput('imessage_fda_confirmed', 'true');
+}
+
+async function collectRemoteCreds(): Promise<RemoteCreds> {
+  p.note(
+    [
+      "Photon is a separate service that owns an iMessage account and",
+      "exposes it over HTTP. NanoClaw will talk to it via its API.",
+      '',
+      '  1. Set up a Photon server: https://photon.im',
+      '  2. Copy the server URL and API key from your Photon dashboard',
+    ].join('\n'),
+    'Remote iMessage via Photon',
+  );
+
+  const urlAnswer = ensureAnswer(
+    await p.text({
+      message: 'Photon server URL',
+      placeholder: 'https://photon.example.com',
+      validate: (v) => {
+        const t = (v ?? '').trim();
+        if (!t) return 'URL is required';
+        if (!/^https?:\/\//i.test(t)) return 'Must start with http:// or https://';
+        return undefined;
+      },
+    }),
+  );
+  const serverUrl = (urlAnswer as string).trim();
+
+  const keyAnswer = ensureAnswer(
+    await p.password({
+      message: 'Photon API key',
+      validate: (v) => ((v ?? '').trim() ? undefined : 'API key is required'),
+    }),
+  );
+  const apiKey = (keyAnswer as string).trim();
+
+  setupLog.userInput('imessage_server_url', serverUrl);
+  setupLog.userInput(
+    'imessage_api_key',
+    `${apiKey.slice(0, 4)}…${apiKey.slice(-4)}`,
+  );
+  return { serverUrl, apiKey };
+}
+
+async function askOperatorHandle(): Promise<string> {
+  p.note(
+    [
+      "What phone number or email do you iMessage with?",
+      "That's where your assistant will send its welcome message.",
+      '',
+      k.dim('  • Phone: full E.164, e.g. +15551234567'),
+      k.dim('  • Email: whatever iMessage recognises (Apple ID, iCloud alias, …)'),
+    ].join('\n'),
+    'Your iMessage handle',
+  );
+
+  const answer = ensureAnswer(
+    await p.text({
+      message: 'Phone number or email',
+      validate: (v) => {
+        const t = (v ?? '').trim();
+        if (!t) return 'Required';
+        const isPhone = /^\+\d{8,15}$/.test(t);
+        const isEmail = /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(t);
+        if (!isPhone && !isEmail) {
+          return "Use a +E.164 phone number or an email address";
+        }
+        return undefined;
+      },
+    }),
+  );
+  const handle = (answer as string).trim();
+  setupLog.userInput('imessage_handle', handle);
+  return handle;
+}
+
+async function resolveAgentName(): Promise<string> {
+  const preset = process.env.NANOCLAW_AGENT_NAME?.trim();
+  if (preset) {
+    setupLog.userInput('agent_name', preset);
+    return preset;
+  }
+  const answer = ensureAnswer(
+    await p.text({
+      message: 'What should your assistant be called?',
+      placeholder: DEFAULT_AGENT_NAME,
+      defaultValue: DEFAULT_AGENT_NAME,
+    }),
+  );
+  const value = (answer as string).trim() || DEFAULT_AGENT_NAME;
+  setupLog.userInput('agent_name', value);
+  return value;
+}

setup/channels/slack.ts

@@ -0,0 +1,249 @@
+/**
+ * Slack channel flow for setup:auto.
+ *
+ * `runSlackChannel(displayName)` walks the operator from a bare Slack
+ * workspace through a running bot, then stops before wiring an agent:
+ *
+ *   1. Walk through creating a Slack app (api.slack.com/apps) — scopes,
+ *      event subscriptions, and signing secret
+ *   2. Paste the bot token + signing secret (clack password prompts)
+ *   3. Validate via auth.test → resolves workspace + bot identity
+ *   4. Install the adapter (setup/add-slack.sh, non-interactive)
+ *   5. Print the post-install checklist: set the public webhook URL in
+ *      Slack's Event Subscriptions, DM the bot to bootstrap the channel,
+ *      then `/manage-channels` to wire an agent.
+ *
+ * Why no welcome DM here: unlike Discord/Telegram (gateway / long-poll),
+ * Slack needs a public Event Subscriptions URL for inbound events, and
+ * opening an unsolicited DM would need `im:write` scope we don't force
+ * the SKILL.md to require. Shipping a honest "here's what's left" note
+ * is better than a welcome DM the user won't receive until they
+ * configure the webhook anyway.
+ *
+ * All output obeys the three-level contract. See docs/setup-flow.md.
+ */
+import * as p from '@clack/prompts';
+import k from 'kleur';
+
+import * as setupLog from '../logs.js';
+import { confirmThenOpen } from '../lib/browser.js';
+import { ensureAnswer, fail, runQuietChild } from '../lib/runner.js';
+import { wrapForGutter } from '../lib/theme.js';
+
+const SLACK_API = 'https://slack.com/api';
+const SLACK_APPS_URL = 'https://api.slack.com/apps';
+
+interface WorkspaceInfo {
+  teamName: string;
+  teamId: string;
+  botName: string;
+  botUserId: string;
+}
+
+// displayName is reserved for when we start wiring the first agent here.
+// Kept to match the `run<X>Channel(displayName)` signature every other
+// channel driver uses, so auto.ts can dispatch without a branch.
+export async function runSlackChannel(_displayName: string): Promise<void> {
+  await walkThroughAppCreation();
+
+  const token = await collectBotToken();
+  const signingSecret = await collectSigningSecret();
+  const info = await validateSlackToken(token);
+
+  const install = await runQuietChild(
+    'slack-install',
+    'bash',
+    ['setup/add-slack.sh'],
+    {
+      running: `Connecting Slack to @${info.botName} (${info.teamName})…`,
+      done: 'Slack adapter installed.',
+    },
+    {
+      env: {
+        SLACK_BOT_TOKEN: token,
+        SLACK_SIGNING_SECRET: signingSecret,
+      },
+      extraFields: {
+        BOT_NAME: info.botName,
+        TEAM_NAME: info.teamName,
+        TEAM_ID: info.teamId,
+      },
+    },
+  );
+  if (!install.ok) {
+    await fail(
+      'slack-install',
+      "Couldn't connect Slack.",
+      'See logs/setup-steps/ for details, then retry setup.',
+    );
+  }
+
+  showPostInstallChecklist(info);
+}
+
+async function walkThroughAppCreation(): Promise<void> {
+  p.note(
+    [
+      "You'll create a Slack app that the assistant talks through.",
+      "Free and stays inside the workspaces you pick.",
+      '',
+      '  1. Create a new app "From scratch", name it, pick a workspace',
+      '  2. OAuth & Permissions → add Bot Token Scopes:',
+      '     chat:write, channels:history, groups:history, im:history,',
+      '     channels:read, groups:read, users:read, reactions:write',
+      '  3. App Home → enable "Messages Tab" and "Allow users to send',
+      '     slash commands and messages from the messages tab"',
+      '  4. Basic Information → copy the "Signing Secret"',
+      '  5. Install to Workspace → copy the "Bot User OAuth Token" (xoxb-…)',
+      '',
+      k.dim(SLACK_APPS_URL),
+    ].join('\n'),
+    'Create a Slack app',
+  );
+  await confirmThenOpen(SLACK_APPS_URL, 'Press Enter to open Slack app settings');
+
+  ensureAnswer(
+    await p.confirm({
+      message: 'Got your bot token and signing secret?',
+      initialValue: true,
+    }),
+  );
+}
+
+async function collectBotToken(): Promise<string> {
+  const answer = ensureAnswer(
+    await p.password({
+      message: 'Paste your Slack bot token',
+      validate: (v) => {
+        const t = (v ?? '').trim();
+        if (!t) return 'Token is required';
+        if (!t.startsWith('xoxb-')) return 'Bot tokens start with xoxb-';
+        if (t.length < 24) return "That's shorter than a real Slack bot token";
+        return undefined;
+      },
+    }),
+  );
+  const token = (answer as string).trim();
+  setupLog.userInput(
+    'slack_bot_token',
+    `${token.slice(0, 10)}…${token.slice(-4)}`,
+  );
+  return token;
+}
+
+async function collectSigningSecret(): Promise<string> {
+  const answer = ensureAnswer(
+    await p.password({
+      message: 'Paste your Slack signing secret',
+      validate: (v) => {
+        const t = (v ?? '').trim();
+        if (!t) return 'Signing secret is required';
+        // Slack signing secrets are 32-char hex strings, but newer apps
+        // sometimes emit longer variants — leniently require hex only.
+        if (!/^[a-f0-9]{16,}$/i.test(t)) {
+          return 'Signing secrets are a string of hex characters';
+        }
+        return undefined;
+      },
+    }),
+  );
+  const secret = (answer as string).trim();
+  setupLog.userInput(
+    'slack_signing_secret',
+    `${secret.slice(0, 4)}…${secret.slice(-4)}`,
+  );
+  return secret;
+}
+
+async function validateSlackToken(token: string): Promise<WorkspaceInfo> {
+  const s = p.spinner();
+  const start = Date.now();
+  s.start('Checking your bot token…');
+  try {
+    const res = await fetch(`${SLACK_API}/auth.test`, {
+      method: 'POST',
+      headers: {
+        Authorization: `Bearer ${token}`,
+        'Content-Type': 'application/x-www-form-urlencoded',
+      },
+    });
+    const data = (await res.json()) as {
+      ok?: boolean;
+      team?: string;
+      team_id?: string;
+      user?: string;
+      user_id?: string;
+      error?: string;
+    };
+    const elapsedS = Math.round((Date.now() - start) / 1000);
+    if (data.ok && data.team && data.user) {
+      s.stop(
+        `Connected to ${data.team} as @${data.user}. ${k.dim(`(${elapsedS}s)`)}`,
+      );
+      const info: WorkspaceInfo = {
+        teamName: data.team,
+        teamId: data.team_id ?? '',
+        botName: data.user,
+        botUserId: data.user_id ?? '',
+      };
+      setupLog.step('slack-validate', 'success', Date.now() - start, {
+        BOT_NAME: info.botName,
+        BOT_USER_ID: info.botUserId,
+        TEAM_NAME: info.teamName,
+        TEAM_ID: info.teamId,
+      });
+      return info;
+    }
+    const reason = data.error ?? `HTTP ${res.status}`;
+    s.stop(`Slack didn't accept that token: ${reason}`, 1);
+    setupLog.step('slack-validate', 'failed', Date.now() - start, {
+      ERROR: reason,
+    });
+    await fail(
+      'slack-validate',
+      "Slack didn't accept that token.",
+      reason === 'invalid_auth' || reason === 'token_revoked'
+        ? 'Copy the token again from OAuth & Permissions and retry setup.'
+        : `Slack said "${reason}". Check the token scopes and workspace install, then retry.`,
+    );
+  } catch (err) {
+    const elapsedS = Math.round((Date.now() - start) / 1000);
+    s.stop(`Couldn't reach Slack. ${k.dim(`(${elapsedS}s)`)}`, 1);
+    const message = err instanceof Error ? err.message : String(err);
+    setupLog.step('slack-validate', 'failed', Date.now() - start, {
+      ERROR: message,
+    });
+    await fail(
+      'slack-validate',
+      "Couldn't reach Slack.",
+      'Check your internet connection and retry setup.',
+    );
+  }
+}
+
+function showPostInstallChecklist(info: WorkspaceInfo): void {
+  p.note(
+    wrapForGutter(
+      [
+        `The Slack adapter is installed and your creds are saved. ${info.teamName} still needs two things before it can talk to you:`,
+        '',
+        '  1. A public URL so Slack can deliver events.',
+        '     NanoClaw serves a webhook on port 3000 by default — expose it',
+        '     via ngrok, Cloudflare Tunnel, or a reverse proxy on a VPS.',
+        '',
+        '  2. In your Slack app → Event Subscriptions:',
+        '     • Toggle "Enable Events" on',
+        `     • Request URL: https://<your-public-host>/webhook/slack`,
+        '     • Subscribe to bot events: message.channels, message.groups,',
+        '       message.im, app_mention',
+        '     • Save, then reinstall the app when Slack prompts',
+        '',
+        `  3. DM @${info.botName} from Slack once — that bootstraps the`,
+        '     messaging group. Then run `/manage-channels` in `claude` to',
+        '     wire an agent to it.',
+      ].join('\n'),
+      6,
+    ),
+    'Finish setting up Slack',
+  );
+}

setup/lib/claude-assist.ts

@@ -64,6 +64,10 @@ const STEP_FILES: Record<string, string[]> = {
   'telegram-validate': ['setup/channels/telegram.ts'],
   'pair-telegram': ['setup/pair-telegram.ts', 'setup/channels/telegram.ts'],
   'discord-install': ['setup/add-discord.sh', 'setup/channels/discord.ts'],
+  'slack-install': ['setup/add-slack.sh', 'setup/channels/slack.ts'],
+  'slack-validate': ['setup/channels/slack.ts'],
+  'imessage-install': ['setup/add-imessage.sh', 'setup/channels/imessage.ts'],
+  'imessage': ['setup/channels/imessage.ts'],
   'teams-install': ['setup/add-teams.sh', 'setup/channels/teams.ts'],
   'teams-manifest': ['setup/lib/teams-manifest.ts', 'setup/channels/teams.ts'],
   'init-first-agent': [