/init-first-agent

name: init-first-agent
description: Walk the operator through wiring the first NanoClaw agent to a DM channel — resolve the operator's channel identity, select or create the agent, and trigger a welcome DM via the normal delivery path. Use after channel credentials are configured and the service is running.

Init First Agent

Wire the first NanoClaw agent to a channel and verify end-to-end delivery by having the agent DM the operator. Everything the skill does is idempotent — rerunning is safe.

Prerequisites

• **Service running.** Check: `launchctl list | grep "$(. setup/lib/install-slug.sh && launchd_label)"` (macOS) or `systemctl --user status "$(. setup/lib/install-slug.sh && systemd_unit)"` (Linux). If stopped, tell the user to run `/setup` first.
• **Target channel installed.** At least one `/add-<channel>` skill has run, credentials are in `.env`, and the adapter is uncommented in `src/channels/index.ts`.
• **Adapter connected.** Tail `logs/nanoclaw.log` — look for a recent `channel setup` / `adapter connected` line for the target channel.

1. Pick the channel

Read `src/channels/index.ts` to find enabled channels (uncommented imports). Cross-check `.env` for the relevant credentials.

AskUserQuestion: "Which channel should host the welcome DM?" with one option per enabled channel (Discord, Slack, Telegram, WhatsApp, Webex, Teams, Google Chat, Matrix, iMessage, Resend, …).

Record the choice as `CHANNEL` (lowercase, e.g. `discord`).

2. Ask for the operator's identity

Read the channel's own skill for its `## Channel Info > how-to-find-id` section (e.g. `.claude/skills/add-discord/SKILL.md`, `.claude/skills/add-telegram/SKILL.md`). Show those instructions to the user in plain text.

Then ask in plain text (NOT `AskUserQuestion` — these are free-form):

1. **Your user id on this channel** — e.g. a Discord user ID, Telegram user ID, Slack user ID. Record as `USER_HANDLE`. 2. **Your display name** — human name, used to name the agent group (`dm-with-<normalized>`) and as the welcome-message addressee. Record as `DISPLAY_NAME`. 3. **Agent persona name** — the assistant's display name. Default: `DISPLAY_NAME`. Record as `AGENT_NAME`.

3. Resolve the DM platform id

This depends on whether the channel supports cold DM via `adapter.openDM`.

**Channels without cold DM (direct-addressable): telegram, whatsapp, imessage, matrix, resend.** The user handle doubles as the DM chat id. Set:

PLATFORM_ID=${CHANNEL}:${USER_HANDLE}

Skip to step 4.

**Channels with cold DM (resolution-required): discord, slack, teams, webex, gchat.** The bot can DM cold at runtime via Chat SDK, but this skill runs standalone — it can't call the adapter. Two resolutions:

3a. User DMs the bot once (Discord / Slack / Teams / Webex / gChat)

Tell the user:

> Send any single message to the bot as a DM from your account on `${CHANNEL}`. The router will record the DM as a messaging group. Reply `done` here when you've sent the message.

Wait for the user's confirmation. Then look up the most recent DM messaging groups:

pnpm exec tsx scripts/q.ts data/v2.db "SELECT id, platform_id, name, created_at FROM messaging_groups WHERE channel_type='${CHANNEL}' AND is_group=0 ORDER BY created_at DESC LIMIT 5"

Show the top rows to the user and confirm which `platform_id` is theirs (usually the most recent). Record as `PLATFORM_ID`. If none appeared, check `logs/nanoclaw.log` for `unknown_sender` drops — the adapter might be rejecting inbound due to connection or permission issues.

3b. Telegram pair-code path (if the user prefers not to DM first)

For Telegram only, there's an existing pair-code primitive. When you run this tool, take the output and extract the pairing code. Then show it to the user in plain text and ask the user to send the code in the Telegram chat to complete the pairing.

npx tsx setup/index.ts --step pair-telegram -- --intent new-agent:dm-with-<folder>

Parse the `PAIR_TELEGRAM_ISSUED` status block for `CODE` and follow the `REMINDER_TO_ASSISTANT` line in that block. Then wait for the `PAIR_TELEGRAM` block — read `PLATFORM_ID` and `PAIRED_USER_ID` from it. telegram.ts's interceptor has already upserted the user and granted owner if none existed yet. Use `PLATFORM_ID` and `PAIRED_USER_ID` directly in step 5.

4. Pick the agent group

List the existing agent groups and their wirings through the admin CLI:

ncl groups list --json
ncl wirings list --json

If setup already installed a template, it appears in the groups result even when it has no wiring. Show the user each group's name, folder, and id, and note which groups already appear as `agent_group_id` values in the wirings result.

• If no group exists, continue without `AGENT_GROUP_ID`; the init script will create one.
• If groups exist, ask whether to wire one of them or create a new agent. Recommend the sole unwired group when there is exactly one.
• When the user picks an existing group, record its exact `id` as `AGENT_GROUP_ID`. Do not infer it from the display name or folder.

5. Run the init script

When creating a new agent, first pick the provider. Read `src/providers/index.ts` and collect the installed providers from its `import './<name>.js';` lines — `claude` is always available as the built-in default. If a non-default provider is installed (e.g. codex), ask the user which one this agent should run on; if only claude is available, skip the question. An existing group keeps the provider and template configuration it already has.

npx tsx scripts/init-first-agent.ts \
  --channel "${CHANNEL}" \
  --user-id "${CHANNEL}:${USER_HANDLE}" \
  --platform-id "${PLATFORM_ID}" \
  --display-name "${DISPLAY_NAME}" \
  --agent-name "${AGENT_NAME}"

When an existing group was selected, append its exact id:

  --agent-group-id "${AGENT_GROUP_ID}"

When the channel runs a named adapter instance (e.g. a second Telegram bot registered as `telegram-mega`), ap