[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M6DFZ3KX0410N4RQJ7REH7SC":3,"skill-same:01M6DFZ3KX0410N4RQJ7REH7SC":65},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":15,"categories":16,"keywords":22,"publishedAt":40,"linkOnly":41,"markdownContent":42,"markdownBody":43,"frontMatter":44,"refName":45,"commitSha":46,"skillDirectory":47,"forksCount":13,"repositoryHtmlUrl":48,"repositoryHomepageUrl":6,"ownerHtmlUrl":49,"ownerBlogUrl":6,"ownerDescription":6,"updatedAt":50,"install":51,"resources":64},"01M6DFZ3KX0410N4RQJ7REH7SC","add-telegram-swarm",null,"Add Agent Swarm (Teams) support to Telegram. Each subagent gets its own bot identity in the group. Requires Telegram channel to be set up first (use \u002Fadd-telegram). Triggers on \"agent swarm\", \"agent teams telegram\", \"telegram swarm\", \"bot pool\".","mbaker95\u002Fnanodex","mbaker95","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F11398294?v=4","01M6DFXVNAJHZG78Y2D700Y6V3","01M6DFXVTTW83QGKTJ9FJ5YCH5",0,"MIT","https:\u002F\u002Fgithub.com\u002Fmbaker95\u002Fnanodex\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fadd-telegram-swarm\u002FSKILL.md",[17],{"categoryNo":18,"categoryName":19,"taxonomyType":20,"taxonomyTypeDesc":21},"01JBSEEDCAT000000000000023","Skill与智能体开发","SCENARIO","使用场景",[23,24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39],"add telegram swarm","add telegram","telegram","swarm","subagent","triggers","agent teams","up","use","channel","add agent","bot","first","SET","teams","identity","support","2026-11-10 10:12:30",false,"---\nname: add-telegram-swarm\ndescription: Add Agent Swarm (Teams) support to Telegram. Each subagent gets its own bot identity in the group. Requires Telegram channel to be set up first (use \u002Fadd-telegram). Triggers on \"agent swarm\", \"agent teams telegram\", \"telegram swarm\", \"bot pool\".\n---\n\n# Add Agent Swarm to Telegram\n\nThis skill adds Agent Teams (Swarm) support to an existing Telegram channel. Each subagent in a team gets its own bot identity in the Telegram group, so users can visually distinguish which agent is speaking.\n\n**Prerequisite**: Telegram must already be set up via the `\u002Fadd-telegram` skill. If `src\u002Ftelegram.ts` does not exist or `TELEGRAM_BOT_TOKEN` is not configured, tell the user to run `\u002Fadd-telegram` first.\n\n## How It Works\n\n- The **main bot** receives messages and sends lead agent responses (already set up by `\u002Fadd-telegram`)\n- **Pool bots** are send-only — each gets a Grammy `Api` instance (no polling)\n- When a subagent calls `send_message` with a `sender` parameter, the host assigns a pool bot and renames it to match the sender's role\n- Messages appear in Telegram from different bot identities\n\n```\nSubagent calls send_message(text: \"Found 3 results\", sender: \"Researcher\")\n  → MCP writes IPC file with sender field\n  → Host IPC watcher picks it up\n  → Assigns pool bot #2 to \"Researcher\" (round-robin, stable per-group)\n  → Renames pool bot #2 to \"Researcher\" via setMyName\n  → Sends message via pool bot #2's Api instance\n  → Appears in Telegram from \"Researcher\" bot\n```\n\n## Prerequisites\n\n### 1. Create Pool Bots\n\nTell the user:\n\n> I need you to create 3-5 Telegram bots to use as the agent pool. These will be renamed dynamically to match agent roles.\n>\n> 1. Open Telegram and search for `@BotFather`\n> 2. Send `\u002Fnewbot` for each bot:\n>    - Give them any placeholder name (e.g., \"Bot 1\", \"Bot 2\")\n>    - Usernames like `myproject_swarm_1_bot`, `myproject_swarm_2_bot`, etc.\n> 3. Copy all the tokens\n> 4. Add all bots to your Telegram group(s) where you want agent teams\n\nWait for user to provide the tokens.\n\n### 2. Disable Group Privacy for Pool Bots\n\nTell the user:\n\n> **Important**: Each pool bot needs Group Privacy disabled so it can send messages in groups.\n>\n> For each pool bot in `@BotFather`:\n> 1. Send `\u002Fmybots` and select the bot\n> 2. Go to **Bot Settings** > **Group Privacy** > **Turn off**\n>\n> Then add all pool bots to your Telegram group(s).\n\n## Implementation\n\n### Step 1: Update Configuration\n\nRead `src\u002Fconfig.ts` and add the bot pool config near the other Telegram exports:\n\n```typescript\nexport const TELEGRAM_BOT_POOL = (process.env.TELEGRAM_BOT_POOL || '')\n  .split(',')\n  .map((t) => t.trim())\n  .filter(Boolean);\n```\n\n### Step 2: Add Bot Pool to Telegram Module\n\nRead `src\u002Ftelegram.ts` and add the following:\n\n1. **Update imports** — add `Api` to the Grammy import:\n\n```typescript\nimport { Api, Bot } from 'grammy';\n```\n\n2. **Add pool state** after the existing `let bot` declaration:\n\n```typescript\n\u002F\u002F Bot pool for agent teams: send-only Api instances (no polling)\nconst poolApis: Api[] = [];\n\u002F\u002F Maps \"{groupFolder}:{senderName}\" → pool Api index for stable assignment\nconst senderBotMap = new Map\u003Cstring, number>();\nlet nextPoolIndex = 0;\n```\n\n3. **Add pool functions** — place these before the `isTelegramConnected` function:\n\n```typescript\n\u002F**\n * Initialize send-only Api instances for the bot pool.\n * Each pool bot can send messages but doesn't poll for updates.\n *\u002F\nexport async function initBotPool(tokens: string[]): Promise\u003Cvoid> {\n  for (const token of tokens) {\n    try {\n      const api = new Api(token);\n      const me = await api.getMe();\n      poolApis.push(api);\n      logger.info(\n        { username: me.username, id: me.id, poolSize: poolApis.length },\n        'Pool bot initialized',\n      );\n    } catch (err) {\n      logger.error({ err }, 'Failed to initialize pool bot');\n    }\n  }\n  if (poolApis.length > 0) {\n    logger.info({ count: poolApis.length }, 'Telegram bot pool ready');\n  }\n}\n\n\u002F**\n * Send a message via a pool bot assigned to the given sender name.\n * Assigns bots round-robin on first use; subsequent messages from the\n * same sender in the same group always use the same bot.\n * On first assignment, renames the bot to match the sender's role.\n *\u002F\nexport async function sendPoolMessage(\n  chatId: string,\n  text: string,\n  sender: string,\n  groupFolder: string,\n): Promise\u003Cvoid> {\n  if (poolApis.length === 0) {\n    \u002F\u002F No pool bots — fall back to main bot\n    await sendTelegramMessage(chatId, text);\n    return;\n  }\n\n  const key = `${groupFolder}:${sender}`;\n  let idx = senderBotMap.get(key);\n  if (idx === undefined) {\n    idx = nextPoolIndex % poolApis.length;\n    nextPoolIndex++;\n    senderBotMap.set(key, idx);\n    \u002F\u002F Rename the bot to match the sender's role, then wait for Telegram to propagate\n    try {\n      await poolApis[idx].setMyName(sender);\n      await new Promise((r) => setTimeout(r, 2000));\n      logger.info({ sender, groupFolder, poolIndex: idx }, 'Assigned and renamed pool bot');\n    } catch (err) {\n      logger.warn({ sender, err }, 'Failed to rename pool bot (sending anyway)');\n    }\n  }\n\n  const api = poolApis[idx];\n  try {\n    const numericId = chatId.replace(\u002F^tg:\u002F, '');\n    const MAX_LENGTH = 4096;\n    if (text.length \u003C= MAX_LENGTH) {\n      await api.sendMessage(numericId, text);\n    } else {\n      for (let i = 0; i \u003C text.length; i += MAX_LENGTH) {\n        await api.sendMessage(numericId, text.slice(i, i + MAX_LENGTH));\n      }\n    }\n    logger.info({ chatId, sender, poolIndex: idx, length: text.length }, 'Pool message sent');\n  } catch (err) {\n    logger.error({ chatId, sender, err }, 'Failed to send pool message');\n  }\n}\n```\n\n### Step 3: Add sender Parameter to MCP Tool\n\nRead `container\u002Fagent-runner\u002Fsrc\u002Fipc-mcp-stdio.ts` and update the `send_message` tool to accept an optional `sender` parameter:\n\nChange the tool's schema from:\n```typescript\n{ text: z.string().describe('The message text to send') },\n```\n\nTo:\n```typescript\n{\n  text: z.string().describe('The message text to send'),\n  sender: z.string().optional().describe('Your role\u002Fidentity name (e.g. \"Researcher\"). When set, messages appear from a dedicated bot in Telegram.'),\n},\n```\n\nAnd update the handler to include `sender` in the IPC data:\n\n```typescript\nasync (args) => {\n    const data: Record\u003Cstring, string | undefined> = {\n      type: 'message',\n      chatJid,\n      text: args.text,\n      sender: args.sender || undefined,\n      groupFolder,\n      timestamp: new Date().toISOString(),\n    };\n\n    writeIpcFile(MESSAGES_DIR, data);\n\n    return { content: [{ type: 'text' as const, text: 'Message sent.' }] };\n  },\n```\n\n### Step 4: Update Host IPC Routing\n\nRead `src\u002Fipc.ts` and make these changes:\n\n1. **Add imports** — add `sendPoolMessage` and `initBotPool` from the Telegram swarm module, and `TELEGRAM_BOT_POOL` from config.\n\n2. **Update IPC message routing** — in `src\u002Fipc.ts`, find where the `sendMessage` dependency is called to deliver IPC messages (inside `processIpcFiles`). The `sendMessage` is passed in via the `IpcDeps` parameter. Wrap it to route Telegram swarm messages through the bot pool:\n\n```typescript\nif (data.sender && data.chatJid.startsWith('tg:')) {\n  await sendPoolMessage(\n    data.chatJid,\n    data.text,\n    data.sender,\n    sourceGroup,\n  );\n} else {\n  await deps.sendMessage(data.chatJid, data.text);\n}\n```\n\nNote: The assistant name prefix is handled by `formatOutbound()` in the router — Telegram channels have `prefixAssistantName = false` so no prefix is added for `tg:` JIDs.\n\n3. **Initialize pool in `main()` in `src\u002Findex.ts`** — after creating the Telegram channel, add:\n\n```typescript\nif (TELEGRAM_BOT_POOL.length > 0) {\n  await initBotPool(TELEGRAM_BOT_POOL);\n}\n```\n\n### Step 5: Update AGENTS.md Files\n\n#### 5a. Add global message formatting rules\n\nRead `groups\u002Fglobal\u002FAGENTS.md` and add a Message Formatting section:\n\n```markdown\n## Message Formatting\n\nNEVER use markdown. Only use WhatsApp\u002FTelegram formatting:\n- *single asterisks* for bold (NEVER **double asterisks**)\n- _underscores_ for italic\n- • bullet points\n- ```triple backticks``` for code\n\nNo ## headings. No [links](url). No **double stars**.\n```\n\n#### 5b. Update existing group AGENTS.md headings\n\nIn any group AGENTS.md that has a \"WhatsApp Formatting\" section (e.g. `groups\u002Fmain\u002FAGENTS.md`), rename the heading to reflect multi-channel support:\n\n```\n## WhatsApp Formatting (and other messaging apps)\n```\n\n#### 5c. Add Agent Teams instructions to Telegram groups\n\nFor each Telegram group that will use agent teams, create or update its `groups\u002F{folder}\u002FAGENTS.md` with these instructions. Read the existing AGENTS.md first (or `groups\u002Fglobal\u002FAGENTS.md` as a base) and add the Agent Teams section:\n\n```markdown\n## Agent Teams\n\nWhen creating a team to tackle a complex task, follow these rules:\n\n### CRITICAL: Follow the user's prompt exactly\n\nCreate *exactly* the team the user asked for — same number of agents, same roles, same names. Do NOT add extra agents, rename roles, or use generic names like \"Researcher 1\". If the user says \"a marine biologist, a physicist, and Alexander Hamilton\", create exactly those three agents with those exact names.\n\n### Team member instructions\n\nEach team member MUST be instructed to:\n\n1. *Share progress in the group* via `mcp__nanoclaw__send_message` with a `sender` parameter matching their exact role\u002Fcharacter name (e.g., `sender: \"Marine Biologist\"` or `sender: \"Alexander Hamilton\"`). This makes their messages appear from a dedicated bot in the Telegram group.\n2. *Also communicate with teammates* via `SendMessage` as normal for coordination.\n3. Keep group messages *short* — 2-4 sentences max per message. Break longer content into multiple `send_message` calls. No walls of text.\n4. Use the `sender` parameter consistently — always the same name so the bot identity stays stable.\n5. NEVER use markdown formatting. Use ONLY WhatsApp\u002FTelegram formatting: single *asterisks* for bold (NOT **double**), _underscores_ for italic, • for bullets, ```backticks``` for code. No ## headings, no [links](url), no **double asterisks**.\n\n### Example team creation prompt\n\nWhen creating a teammate, include instructions like:\n\n\\```\nYou are the Marine Biologist. When you have findings or updates for the user, send them to the group using mcp__nanoclaw__send_message with sender set to \"Marine Biologist\". Keep each message short (2-4 sentences max). Use emojis for strong reactions. ONLY use single *asterisks* for bold (never **double**), _underscores_ for italic, • for bullets. No markdown. Also communicate with teammates via SendMessage.\n\\```\n\n### Lead agent behavior\n\nAs the lead agent who created the team:\n\n- You do NOT need to react to or relay every teammate message. The user sees those directly from the teammate bots.\n- Send your own messages only to comment, share thoughts, synthesize, or direct the team.\n- When processing an internal update from a teammate that doesn't need a user-facing response, wrap your *entire* output in `\u003Cinternal>` tags.\n- Focus on high-level coordination and the final synthesis.\n```\n\n### Step 6: Update Environment\n\nAdd pool tokens to `.env`:\n\n```bash\nTELEGRAM_BOT_POOL=TOKEN1,TOKEN2,TOKEN3,...\n```\n\n**Important**: Sync to all required locations:\n\n```bash\ncp .env data\u002Fenv\u002Fenv\n```\n\nAlso add `TELEGRAM_BOT_POOL` to the launchd plist (`~\u002FLibrary\u002FLaunchAgents\u002Fcom.nanodex.plist`) in the `EnvironmentVariables` dict if using launchd.\n\n### Step 7: Rebuild and Restart\n\n```bash\nnpm run build\n.\u002Fcontainer\u002Fbuild.sh  # Required — MCP tool changed\n# macOS:\nlaunchctl unload ~\u002FLibrary\u002FLaunchAgents\u002Fcom.nanodex.plist\nlaunchctl load ~\u002FLibrary\u002FLaunchAgents\u002Fcom.nanodex.plist\n# Linux:\n# systemctl --user restart nanodex\n```\n\nMust use `unload\u002Fload` (macOS) or `restart` (Linux) because the service env vars changed.\n\n### Step 8: Test\n\nTell the user:\n\n> Send a message in your Telegram group asking for a multi-agent task, e.g.:\n> \"Assemble a team of a researcher and a coder to build me a hello world app\"\n>\n> You should see:\n> - The lead agent (main bot) acknowledging and creating the team\n> - Each subagent messaging from a different bot, renamed to their role\n> - Short, scannable messages from each agent\n>\n> Check logs: `tail -f logs\u002Fnanodex.log | grep -i pool`\n\n## Architecture Notes\n\n- Pool bots use Grammy's `Api` class — lightweight, no polling, just send\n- Bot names are set via `setMyName` — changes are global to the bot, not per-chat\n- A 2-second delay after `setMyName` allows Telegram to propagate the name change before the first message\n- Sender→bot mapping is stable within a group (keyed as `{groupFolder}:{senderName}`)\n- Mapping resets on service restart — pool bots get reassigned fresh\n- If pool runs out, bots are reused (round-robin wraps)\n\n## Troubleshooting\n\n### Pool bots not sending messages\n\n1. Verify tokens: `curl -s \"https:\u002F\u002Fapi.telegram.org\u002FbotTOKEN\u002FgetMe\"`\n2. Check pool initialized: `grep \"Pool bot\" logs\u002Fnanodex.log`\n3. Ensure all pool bots are members of the Telegram group\n4. Check Group Privacy is disabled for each pool bot\n\n### Bot names not updating\n\nTelegram caches bot names client-side. The 2-second delay after `setMyName` helps, but users may need to restart their Telegram client to see updated names immediately.\n\n### Subagents not using send_message\n\nCheck the group's `AGENTS.md` has the Agent Teams instructions. The lead agent reads this when creating teammates and must include the `send_message` + `sender` instructions in each teammate's prompt.\n\n## Removal\n\nTo remove Agent Swarm support while keeping basic Telegram:\n\n1. Remove `TELEGRAM_BOT_POOL` from `src\u002Fconfig.ts`\n2. Remove pool code from `src\u002Ftelegram.ts` (`poolApis`, `senderBotMap`, `initBotPool`, `sendPoolMessage`)\n3. Remove pool routing from IPC handler in `src\u002Findex.ts` (revert to plain `sendMessage`)\n4. Remove `initBotPool` call from `main()`\n5. Remove `sender` param from MCP tool in `container\u002Fagent-runner\u002Fsrc\u002Fipc-mcp-stdio.ts`\n6. Remove Agent Teams section from group AGENTS.md files\n7. Remove `TELEGRAM_BOT_POOL` from `.env`, `data\u002Fenv\u002Fenv`, and launchd plist\u002Fsystemd unit\n8. Rebuild: `npm run build && .\u002Fcontainer\u002Fbuild.sh && launchctl unload ~\u002FLibrary\u002FLaunchAgents\u002Fcom.nanodex.plist && launchctl load ~\u002FLibrary\u002FLaunchAgents\u002Fcom.nanodex.plist` (macOS) or `npm run build && .\u002Fcontainer\u002Fbuild.sh && systemctl --user restart nanodex` (Linux)\n","# Add Agent Swarm to Telegram\n\nThis skill adds Agent Teams (Swarm) support to an existing Telegram channel. Each subagent in a team gets its own bot identity in the Telegram group, so users can visually distinguish which agent is speaking.\n\n**Prerequisite**: Telegram must already be set up via the `\u002Fadd-telegram` skill. If `src\u002Ftelegram.ts` does not exist or `TELEGRAM_BOT_TOKEN` is not configured, tell the user to run `\u002Fadd-telegram` first.\n\n## How It Works\n\n- The **main bot** receives messages and sends lead agent responses (already set up by `\u002Fadd-telegram`)\n- **Pool bots** are send-only — each gets a Grammy `Api` instance (no polling)\n- When a subagent calls `send_message` with a `sender` parameter, the host assigns a pool bot and renames it to match the sender's role\n- Messages appear in Telegram from different bot identities\n\n```\nSubagent calls send_message(text: \"Found 3 results\", sender: \"Researcher\")\n  → MCP writes IPC file with sender field\n  → Host IPC watcher picks it up\n  → Assigns pool bot #2 to \"Researcher\" (round-robin, stable per-group)\n  → Renames pool bot #2 to \"Researcher\" via setMyName\n  → Sends message via pool bot #2's Api instance\n  → Appears in Telegram from \"Researcher\" bot\n```\n\n## Prerequisites\n\n### 1. Create Pool Bots\n\nTell the user:\n\n> I need you to create 3-5 Telegram bots to use as the agent pool. These will be renamed dynamically to match agent roles.\n>\n> 1. Open Telegram and search for `@BotFather`\n> 2. Send `\u002Fnewbot` for each bot:\n>    - Give them any placeholder name (e.g., \"Bot 1\", \"Bot 2\")\n>    - Usernames like `myproject_swarm_1_bot`, `myproject_swarm_2_bot`, etc.\n> 3. Copy all the tokens\n> 4. Add all bots to your Telegram group(s) where you want agent teams\n\nWait for user to provide the tokens.\n\n### 2. Disable Group Privacy for Pool Bots\n\nTell the user:\n\n> **Important**: Each pool bot needs Group Privacy disabled so it can send messages in groups.\n>\n> For each pool bot in `@BotFather`:\n> 1. Send `\u002Fmybots` and select the bot\n> 2. Go to **Bot Settings** > **Group Privacy** > **Turn off**\n>\n> Then add all pool bots to your Telegram group(s).\n\n## Implementation\n\n### Step 1: Update Configuration\n\nRead `src\u002Fconfig.ts` and add the bot pool config near the other Telegram exports:\n\n```typescript\nexport const TELEGRAM_BOT_POOL = (process.env.TELEGRAM_BOT_POOL || '')\n  .split(',')\n  .map((t) => t.trim())\n  .filter(Boolean);\n```\n\n### Step 2: Add Bot Pool to Telegram Module\n\nRead `src\u002Ftelegram.ts` and add the following:\n\n1. **Update imports** — add `Api` to the Grammy import:\n\n```typescript\nimport { Api, Bot } from 'grammy';\n```\n\n2. **Add pool state** after the existing `let bot` declaration:\n\n```typescript\n\u002F\u002F Bot pool for agent teams: send-only Api instances (no polling)\nconst poolApis: Api[] = [];\n\u002F\u002F Maps \"{groupFolder}:{senderName}\" → pool Api index for stable assignment\nconst senderBotMap = new Map\u003Cstring, number>();\nlet nextPoolIndex = 0;\n```\n\n3. **Add pool functions** — place these before the `isTelegramConnected` function:\n\n```typescript\n\u002F**\n * Initialize send-only Api instances for the bot pool.\n * Each pool bot can send messages but doesn't poll for updates.\n *\u002F\nexport async function initBotPool(tokens: string[]): Promise\u003Cvoid> {\n  for (const token of tokens) {\n    try {\n      const api = new Api(token);\n      const me = await api.getMe();\n      poolApis.push(api);\n      logger.info(\n        { username: me.username, id: me.id, poolSize: poolApis.length },\n        'Pool bot initialized',\n      );\n    } catch (err) {\n      logger.error({ err }, 'Failed to initialize pool bot');\n    }\n  }\n  if (poolApis.length > 0) {\n    logger.info({ count: poolApis.length }, 'Telegram bot pool ready');\n  }\n}\n\n\u002F**\n * Send a message via a pool bot assigned to the given sender name.\n * Assigns bots round-robin on first use; subsequent messages from the\n * same sender in the same group always use the same bot.\n * On first assignment, renames the bot to match the sender's role.\n *\u002F\nexport async function sendPoolMessage(\n  chatId: string,\n  text: string,\n  sender: string,\n  groupFolder: string,\n): Promise\u003Cvoid> {\n  if (poolApis.length === 0) {\n    \u002F\u002F No pool bots — fall back to main bot\n    await sendTelegramMessage(chatId, text);\n    return;\n  }\n\n  const key = `${groupFolder}:${sender}`;\n  let idx = senderBotMap.get(key);\n  if (idx === undefined) {\n    idx = nextPoolIndex % poolApis.length;\n    nextPoolIndex++;\n    senderBotMap.set(key, idx);\n    \u002F\u002F Rename the bot to match the sender's role, then wait for Telegram to propagate\n    try {\n      await poolApis[idx].setMyName(sender);\n      await new Promise((r) => setTimeout(r, 2000));\n      logger.info({ sender, groupFolder, poolIndex: idx }, 'Assigned and renamed pool bot');\n    } catch (err) {\n      logger.warn({ sender, err }, 'Failed to rename pool bot (sending anyway)');\n    }\n  }\n\n  const api = poolApis[idx];\n  try {\n    const numericId = chatId.replace(\u002F^tg:\u002F, '');\n    const MAX_LENGTH = 4096;\n    if (text.length \u003C= MAX_LENGTH) {\n      await api.sendMessage(numericId, text);\n    } else {\n      for (let i = 0; i \u003C text.length; i += MAX_LENGTH) {\n        await api.sendMessage(numericId, text.slice(i, i + MAX_LENGTH));\n      }\n    }\n    logger.info({ chatId, sender, poolIndex: idx, length: text.length }, 'Pool message sent');\n  } catch (err) {\n    logger.error({ chatId, sender, err }, 'Failed to send pool message');\n  }\n}\n```\n\n### Step 3: Add sender Parameter to MCP Tool\n\nRead `container\u002Fagent-runner\u002Fsrc\u002Fipc-mcp-stdio.ts` and update the `send_message` tool to accept an optional `sender` parameter:\n\nChange the tool's schema from:\n```typescript\n{ text: z.string().describe('The message text to send') },\n```\n\nTo:\n```typescript\n{\n  text: z.string().describe('The message text to send'),\n  sender: z.string().optional().describe('Your role\u002Fidentity name (e.g. \"Researcher\"). When set, messages appear from a dedicated bot in Telegram.'),\n},\n```\n\nAnd update the handler to include `sender` in the IPC data:\n\n```typescript\nasync (args) => {\n    const data: Record\u003Cstring, string | undefined> = {\n      type: 'message',\n      chatJid,\n      text: args.text,\n      sender: args.sender || undefined,\n      groupFolder,\n      timestamp: new Date().toISOString(),\n    };\n\n    writeIpcFile(MESSAGES_DIR, data);\n\n    return { content: [{ type: 'text' as const, text: 'Message sent.' }] };\n  },\n```\n\n### Step 4: Update Host IPC Routing\n\nRead `src\u002Fipc.ts` and make these changes:\n\n1. **Add imports** — add `sendPoolMessage` and `initBotPool` from the Telegram swarm module, and `TELEGRAM_BOT_POOL` from config.\n\n2. **Update IPC message routing** — in `src\u002Fipc.ts`, find where the `sendMessage` dependency is called to deliver IPC messages (inside `processIpcFiles`). The `sendMessage` is passed in via the `IpcDeps` parameter. Wrap it to route Telegram swarm messages through the bot pool:\n\n```typescript\nif (data.sender && data.chatJid.startsWith('tg:')) {\n  await sendPoolMessage(\n    data.chatJid,\n    data.text,\n    data.sender,\n    sourceGroup,\n  );\n} else {\n  await deps.sendMessage(data.chatJid, data.text);\n}\n```\n\nNote: The assistant name prefix is handled by `formatOutbound()` in the router — Telegram channels have `prefixAssistantName = false` so no prefix is added for `tg:` JIDs.\n\n3. **Initialize pool in `main()` in `src\u002Findex.ts`** — after creating the Telegram channel, add:\n\n```typescript\nif (TELEGRAM_BOT_POOL.length > 0) {\n  await initBotPool(TELEGRAM_BOT_POOL);\n}\n```\n\n### Step 5: Update AGENTS.md Files\n\n#### 5a. Add global message formatting rules\n\nRead `groups\u002Fglobal\u002FAGENTS.md` and add a Message Formatting section:\n\n```markdown\n## Message Formatting\n\nNEVER use markdown. Only use WhatsApp\u002FTelegram formatting:\n- *single asterisks* for bold (NEVER **double asterisks**)\n- _underscores_ for italic\n- • bullet points\n- ```triple backticks``` for code\n\nNo ## headings. No [links](url). No **double stars**.\n```\n\n#### 5b. Update existing group AGENTS.md headings\n\nIn any group AGENTS.md that has a \"WhatsApp Formatting\" section (e.g. `groups\u002Fmain\u002FAGENTS.md`), rename the heading to reflect multi-channel support:\n\n```\n## WhatsApp Formatting (and other messaging apps)\n```\n\n#### 5c. Add Agent Teams instructions to Telegram groups\n\nFor each Telegram group that will use agent teams, create or update its `groups\u002F{folder}\u002FAGENTS.md` with these instructions. Read the existing AGENTS.md first (or `groups\u002Fglobal\u002FAGENTS.md` as a base) and add the Agent Teams section:\n\n```markdown\n## Agent Teams\n\nWhen creating a team to tackle a complex task, follow these rules:\n\n### CRITICAL: Follow the user's prompt exactly\n\nCreate *exactly* the team the user asked for — same number of agents, same roles, same names. Do NOT add extra agents, rename roles, or use generic names like \"Researcher 1\". If the user says \"a marine biologist, a physicist, and Alexander Hamilton\", create exactly those three agents with those exact names.\n\n### Team member instructions\n\nEach team member MUST be instructed to:\n\n1. *Share progress in the group* via `mcp__nanoclaw__send_message` with a `sender` parameter matching their exact role\u002Fcharacter name (e.g., `sender: \"Marine Biologist\"` or `sender: \"Alexander Hamilton\"`). This makes their messages appear from a dedicated bot in the Telegram group.\n2. *Also communicate with teammates* via `SendMessage` as normal for coordination.\n3. Keep group messages *short* — 2-4 sentences max per message. Break longer content into multiple `send_message` calls. No walls of text.\n4. Use the `sender` parameter consistently — always the same name so the bot identity stays stable.\n5. NEVER use markdown formatting. Use ONLY WhatsApp\u002FTelegram formatting: single *asterisks* for bold (NOT **double**), _underscores_ for italic, • for bullets, ```backticks``` for code. No ## headings, no [links](url), no **double asterisks**.\n\n### Example team creation prompt\n\nWhen creating a teammate, include instructions like:\n\n\\```\nYou are the Marine Biologist. When you have findings or updates for the user, send them to the group using mcp__nanoclaw__send_message with sender set to \"Marine Biologist\". Keep each message short (2-4 sentences max). Use emojis for strong reactions. ONLY use single *asterisks* for bold (never **double**), _underscores_ for italic, • for bullets. No markdown. Also communicate with teammates via SendMessage.\n\\```\n\n### Lead agent behavior\n\nAs the lead agent who created the team:\n\n- You do NOT need to react to or relay every teammate message. The user sees those directly from the teammate bots.\n- Send your own messages only to comment, share thoughts, synthesize, or direct the team.\n- When processing an internal update from a teammate that doesn't need a user-facing response, wrap your *entire* output in `\u003Cinternal>` tags.\n- Focus on high-level coordination and the final synthesis.\n```\n\n### Step 6: Update Environment\n\nAdd pool tokens to `.env`:\n\n```bash\nTELEGRAM_BOT_POOL=TOKEN1,TOKEN2,TOKEN3,...\n```\n\n**Important**: Sync to all required locations:\n\n```bash\ncp .env data\u002Fenv\u002Fenv\n```\n\nAlso add `TELEGRAM_BOT_POOL` to the launchd plist (`~\u002FLibrary\u002FLaunchAgents\u002Fcom.nanodex.plist`) in the `EnvironmentVariables` dict if using launchd.\n\n### Step 7: Rebuild and Restart\n\n```bash\nnpm run build\n.\u002Fcontainer\u002Fbuild.sh  # Required — MCP tool changed\n# macOS:\nlaunchctl unload ~\u002FLibrary\u002FLaunchAgents\u002Fcom.nanodex.plist\nlaunchctl load ~\u002FLibrary\u002FLaunchAgents\u002Fcom.nanodex.plist\n# Linux:\n# systemctl --user restart nanodex\n```\n\nMust use `unload\u002Fload` (macOS) or `restart` (Linux) because the service env vars changed.\n\n### Step 8: Test\n\nTell the user:\n\n> Send a message in your Telegram group asking for a multi-agent task, e.g.:\n> \"Assemble a team of a researcher and a coder to build me a hello world app\"\n>\n> You should see:\n> - The lead agent (main bot) acknowledging and creating the team\n> - Each subagent messaging from a different bot, renamed to their role\n> - Short, scannable messages from each agent\n>\n> Check logs: `tail -f logs\u002Fnanodex.log | grep -i pool`\n\n## Architecture Notes\n\n- Pool bots use Grammy's `Api` class — lightweight, no polling, just send\n- Bot names are set via `setMyName` — changes are global to the bot, not per-chat\n- A 2-second delay after `setMyName` allows Telegram to propagate the name change before the first message\n- Sender→bot mapping is stable within a group (keyed as `{groupFolder}:{senderName}`)\n- Mapping resets on service restart — pool bots get reassigned fresh\n- If pool runs out, bots are reused (round-robin wraps)\n\n## Troubleshooting\n\n### Pool bots not sending messages\n\n1. Verify tokens: `curl -s \"https:\u002F\u002Fapi.telegram.org\u002FbotTOKEN\u002FgetMe\"`\n2. Check pool initialized: `grep \"Pool bot\" logs\u002Fnanodex.log`\n3. Ensure all pool bots are members of the Telegram group\n4. Check Group Privacy is disabled for each pool bot\n\n### Bot names not updating\n\nTelegram caches bot names client-side. The 2-second delay after `setMyName` helps, but users may need to restart their Telegram client to see updated names immediately.\n\n### Subagents not using send_message\n\nCheck the group's `AGENTS.md` has the Agent Teams instructions. The lead agent reads this when creating teammates and must include the `send_message` + `sender` instructions in each teammate's prompt.\n\n## Removal\n\nTo remove Agent Swarm support while keeping basic Telegram:\n\n1. Remove `TELEGRAM_BOT_POOL` from `src\u002Fconfig.ts`\n2. Remove pool code from `src\u002Ftelegram.ts` (`poolApis`, `senderBotMap`, `initBotPool`, `sendPoolMessage`)\n3. Remove pool routing from IPC handler in `src\u002Findex.ts` (revert to plain `sendMessage`)\n4. Remove `initBotPool` call from `main()`\n5. Remove `sender` param from MCP tool in `container\u002Fagent-runner\u002Fsrc\u002Fipc-mcp-stdio.ts`\n6. Remove Agent Teams section from group AGENTS.md files\n7. Remove `TELEGRAM_BOT_POOL` from `.env`, `data\u002Fenv\u002Fenv`, and launchd plist\u002Fsystemd unit\n8. Rebuild: `npm run build && .\u002Fcontainer\u002Fbuild.sh && launchctl unload ~\u002FLibrary\u002FLaunchAgents\u002Fcom.nanodex.plist && launchctl load ~\u002FLibrary\u002FLaunchAgents\u002Fcom.nanodex.plist` (macOS) or `npm run build && .\u002Fcontainer\u002Fbuild.sh && systemctl --user restart nanodex` (Linux)\n",{"name":5,"description":7},"main","b6b2f4d4a0c7243409d1684119a6772629bfeba6",".agents\u002Fskills\u002Fadd-telegram-swarm","https:\u002F\u002Fgithub.com\u002Fmbaker95\u002Fnanodex","https:\u002F\u002Fgithub.com\u002Fmbaker95","2026-03-12 23:02:12",{"source":8,"skillName":5,"commands":52,"prompt":62,"zipAvailable":63},[53,56,59],{"tool":54,"command":55},"npx","npx skills add mbaker95\u002Fnanodex --skill add-telegram-swarm",{"tool":57,"command":58},"bunx","bunx skills add mbaker95\u002Fnanodex --skill add-telegram-swarm",{"tool":60,"command":61},"pnpm","pnpm dlx skills add mbaker95\u002Fnanodex --skill add-telegram-swarm","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fmbaker95\u002Fnanodex\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fadd-telegram-swarm\u002FSKILL.md",true,[],[66,92,110,132,144,156],{"skillNo":67,"name":68,"nameZh":6,"description":69,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":70,"categories":71,"keywords":73,"publishedAt":40},"01M6DG2XYNH5XV7XGTJJ1SF0TG","agent-browser","Browse the web for any task — research topics, read articles, interact with web apps, fill forms, take screenshots, extract data, and test web pages. Use whenever a browser would be useful, not just when the user explicitly asks.","https:\u002F\u002Fgithub.com\u002Fmbaker95\u002Fnanodex\u002Fblob\u002Fmain\u002Fcontainer\u002Fskills\u002Fagent-browser\u002FSKILL.md",[72],{"categoryNo":18,"categoryName":19,"taxonomyType":20,"taxonomyTypeDesc":21},[74,75,76,77,78,79,80,31,81,82,83,84,85,86,87,88,89,90,91],"agent browser","browser","pages","forms","task","test web","take","extract","data","user","read","screenshots","research","test","web","just","Bash","browse",{"skillNo":93,"name":94,"nameZh":6,"description":95,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":96,"categories":97,"keywords":101,"publishedAt":40},"01M6DG2TPZAT3SMWSYFJ3K82TE","x-integration","X (Twitter) integration for NanoClaw. Post tweets, like, reply, retweet, and quote. Use for setup, testing, or troubleshooting X functionality. Triggers on \"setup x\", \"x integration\", \"twitter\", \"post tweet\", \"tweet\".","https:\u002F\u002Fgithub.com\u002Fmbaker95\u002Fnanodex\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fx-integration\u002FSKILL.md",[98],{"categoryNo":99,"categoryName":100,"taxonomyType":20,"taxonomyTypeDesc":21},"01JBSEEDCAT000000000000008","测试与质量",[102,103,31,104,105,106,107,108,109,28],"x integration","integration","testing","setup","troubleshooting","twitter","reply","quote",{"skillNo":111,"name":112,"nameZh":6,"description":113,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":114,"categories":115,"keywords":116,"publishedAt":40},"01M6DG2Q4BJQ046BZSR9N7GZ72","use-local-whisper","Use when the user wants local voice transcription instead of OpenAI Whisper API. Switches to whisper.cpp running on Apple Silicon. WhatsApp only for now. Requires voice-transcription skill to be applied first.","https:\u002F\u002Fgithub.com\u002Fmbaker95\u002Fnanodex\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fuse-local-whisper\u002FSKILL.md",[],[117,118,31,119,120,121,122,123,83,124,125,126,35,127,128,129,130,131],"whisper","local whisper","local","use local whisper","apple","openai whisper","only","voice","apple silicon","api","openai","cpp","transcription","openai whisper api","whatsapp",{"skillNo":133,"name":134,"nameZh":6,"description":135,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":136,"categories":137,"keywords":138,"publishedAt":40},"01M6DG2N2Z1V8VV4MQFRKFAQV0","update-skills","Check for and apply updates to installed skill branches from upstream.","https:\u002F\u002Fgithub.com\u002Fmbaker95\u002Fnanodex\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fupdate-skills\u002FSKILL.md",[],[139,140,141,142,143],"update","update skills","upstream","branches","check",{"skillNo":145,"name":146,"nameZh":6,"description":147,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":148,"categories":149,"keywords":150,"publishedAt":40},"01M6DG2J5D7Y3R2BF8V87XZAXF","update-nanoclaw","Efficiently bring upstream NanoClaw updates into a customized install, with preview, selective cherry-pick, and low token usage.","https:\u002F\u002Fgithub.com\u002Fmbaker95\u002Fnanodex\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fupdate-nanoclaw\u002FSKILL.md",[],[139,151,152,153,141,154,155],"update nanoclaw","install","pick","token","preview",{"skillNo":157,"name":105,"nameZh":6,"description":158,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":159,"categories":160,"keywords":161,"publishedAt":40},"01M6DG2FN7S7DVD337CNT5Y67D","Run initial NanoClaw setup. Use when user wants to install dependencies, authenticate messaging channels, register their main channel, or start the background services. Triggers on \"setup\", \"install\", \"configure nanoclaw\", or first-time setup requests.","https:\u002F\u002Fgithub.com\u002Fmbaker95\u002Fnanodex\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fsetup\u002FSKILL.md",[],[105,152,28,162,163,45,31,32,83,164,35,165,166,167,168],"time","dependencies","configure","services","start","messaging","run"]