add-telegram-swarm
Skill98 starsChanged 8 months agoApache-2.0View on GitHub
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 /add-telegram). Triggers on "agent swarm", "agent teams telegram", "telegram swarm", "bot pool".
- Reads credentials
6 other projects use a version of this, 6 of them edited.
Adopted by
Most recently taken up by
- juancruzmunozalbelo/swarmclawedited, first seen Oct 8, 2026
- Runchuan-BU/BioClawedited, first seen Aug 2, 2026
- b1rdmania/ghostclawedited, first seen May 3, 2026
- 0-CYBERDYNE-SYSTEMS-0/FFT_nanoedited, first seen Mar 16, 2026
- sskarz/nanoclawbsteredited, first seen Mar 11, 2026
- breakcafe/picoclawedited, first seen Mar 6, 2026
Other versions6 projects use a version of this.
Word for word · 0
None found.
Edited · 6
- Runchuan-BU/BioClaw★ 40597% same
- b1rdmania/ghostclaw★ 9197% same
- 0-CYBERDYNE-SYSTEMS-0/FFT_nano★ 493% same
- sskarz/nanoclawbster★ 298% same
- breakcafe/picoclaw★ 198% same
- juancruzmunozalbelo/swarmclaw★ 197% same
Wrote their own version · 0
None found.
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository20 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- add-dingtalkSkill
- add-discordSkill
- add-gmailSkill
- add-ollama-toolSkill
- add-parallelSkill
- add-slackSkill
- add-telegramSkill
- add-vaspSkill
- add-voice-transcriptionSkill
- add-whatsappSkill
- convert-to-apple-containerSkill
- customizeSkill
- debugSkill
- get-qodo-rulesSkill
- qodo-pr-resolverSkill
- setupSkill
- update-matclawSkill
- use-local-whisperSkill
- x-integrationSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
22 rules. 5 are common, 0 are distinctive, and 17 are very specific to this project.
5
Common
Most of the 6 edited versions we read keep these.
0
Distinctive
This author's own choices. Worth a look.
17
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 16
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
- Common: line 44
Wait for user to provide the tokens.
- Very specific: line 62
Read src/config.ts and add the bot pool config near the other Telegram exports:
- Very specific: line 73
Read src/telegram.ts and add the following:
- Very specific: line 81
Add pool state: after the existing let bot declaration:
- Very specific: line 171
Read container/agent-runner/src/ipc-mcp-stdio.ts and update the send_message tool to accept an optional sender parameter:
- Very specific: line 207
Read src/ipc.ts and make these changes:
- Very specific: line 240
Read groups/global/CLAUDE.md and add a Message Formatting section:
- Very specific: line 305
Add pool tokens to .env:
- Very specific: line 331
Must use unload/load (macOS) or restart (Linux) because the service env vars changed.
- Common: line 354
If pool runs out, bots are reused (round-robin wraps)
- Very specific: line 361
Check pool initialized: grep "Pool bot" logs/matclaw.log
- Common: line 362
Ensure all pool bots are members of the Telegram group
- Common: line 363
Check Group Privacy is disabled for each pool bot
- Very specific: line 371
Check the group's CLAUDE.md has the Agent Teams instructions.
- Very specific: line 377
Remove TELEGRAM_BOT_POOL from src/config.ts
- Very specific: line 378
Remove pool code from src/telegram.ts (poolApis, senderBotMap, initBotPool, sendPoolMessage)
- Very specific: line 379
Remove pool routing from IPC handler in src/index.ts (revert to plain sendMessage)
- Very specific: line 380
Remove initBotPool call from main()
- Very specific: line 381
Remove sender param from MCP tool in container/agent-runner/src/ipc-mcp-stdio.ts
- Common: line 382
Remove Agent Teams section from group CLAUDE.md files
- Very specific: line 383
Remove TELEGRAM_BOT_POOL from .env, data/env/env, and launchd plist/systemd unit
“Common” is measured: kept by at least 6 in 10 of the 6 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Add Agent Swarm to Telegram
This 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.
Prerequisite: Telegram must already be set up via the /add-telegram skill. If src/telegram.ts does not exist or TELEGRAM_BOT_TOKEN is not configured, tell the user to run /add-telegram first.
How It Works
- The main bot receives messages and sends lead agent responses (already set up by
/add-telegram) - Pool bots are send-only — each gets a Grammy
Apiinstance (no polling) - When a subagent calls
send_messagewith asenderparameter, the host assigns a pool bot and renames it to match the sender's role - Messages appear in Telegram from different bot identities
Subagent calls send_message(text: "Found 3 results", sender: "Researcher")
→ MCP writes IPC file with sender field
→ Host IPC watcher picks it up
→ Assigns pool bot #2 to "Researcher" (round-robin, stable per-group)
→ Renames pool bot #2 to "Researcher" via setMyName
→ Sends message via pool bot #2's Api instance
→ Appears in Telegram from "Researcher" botPrerequisites
1. Create Pool Bots
Tell the user:
I need you to create 3-5 Telegram bots to use as the agent pool. These will be renamed dynamically to match agent roles.
- Open Telegram and search for
@BotFather- Send
/newbotfor each bot:
- Give them any placeholder name (e.g., "Bot 1", "Bot 2")
- Usernames like
myproject_swarm_1_bot,myproject_swarm_2_bot, etc.- Copy all the tokens
- Add all bots to your Telegram group(s) where you want agent teams
Wait for user to provide the tokens.
2. Disable Group Privacy for Pool Bots
Tell the user:
Important: Each pool bot needs Group Privacy disabled so it can send messages in groups.
For each pool bot in
@BotFather:
- Send
/mybotsand select the bot- Go to Bot Settings > Group Privacy > Turn off
Then add all pool bots to your Telegram group(s).
Implementation
Step 1: Update Configuration
Read src/config.ts and add the bot pool config near the other Telegram exports:
export const TELEGRAM_BOT_POOL = (process.env.TELEGRAM_BOT_POOL || '')
.split(',')
.map((t) => t.trim())
.filter(Boolean);Step 2: Add Bot Pool to Telegram Module
Read src/telegram.ts and add the following:
- Update imports — add
Apito the Grammy import:
import { Api, Bot } from 'grammy';- Add pool state after the existing
let botdeclaration:
// Bot pool for agent teams: send-only Api instances (no polling)
const poolApis: Api[] = [];
// Maps "{groupFolder}:{senderName}" → pool Api index for stable assignment
const senderBotMap = new Map<string, number>();
let nextPoolIndex = 0;- Add pool functions — place these before the
isTelegramConnectedfunction:
/**
* Initialize send-only Api instances for the bot pool.
* Each pool bot can send messages but doesn't poll for updates.
*/
export async function initBotPool(tokens: string[]): Promise<void> {
for (const token of tokens) {
try {
const api = new Api(token);
const me = await api.getMe();
poolApis.push(api);
logger.info(
{ username: me.username, id: me.id, poolSize: poolApis.length },
'Pool bot initialized',
);
} catch (err) {
logger.error({ err }, 'Failed to initialize pool bot');
}
}
if (poolApis.length > 0) {
logger.info({ count: poolApis.length }, 'Telegram bot pool ready');
}
}
/**
* Send a message via a pool bot assigned to the given sender name.
* Assigns bots round-robin on first use; subsequent messages from the
* same sender in the same group always use the same bot.
* On first assignment, renames the bot to match the sender's role.
*/
export async function sendPoolMessage(
chatId: string,
text: string,
sender: string,
groupFolder: string,
): Promise<void> {
if (poolApis.length === 0) {
// No pool bots — fall back to main bot
await sendTelegramMessage(chatId, text);
return;
}
const key = `${groupFolder}:${sender}`;
let idx = senderBotMap.get(key);
if (idx === undefined) {
idx = nextPoolIndex % poolApis.length;
nextPoolIndex++;
senderBotMap.set(key, idx);
// Rename the bot to match the sender's role, then wait for Telegram to propagate
try {
await poolApis[idx].setMyName(sender);
await new Promise((r) => setTimeout(r, 2000));
logger.info({ sender, groupFolder, poolIndex: idx }, 'Assigned and renamed pool bot');
} catch (err) {
logger.warn({ sender, err }, 'Failed to rename pool bot (sending anyway)');
}
}
const api = poolApis[idx];
try {
const numericId = chatId.replace(/^tg:/, '');
const MAX_LENGTH = 4096;
if (text.length <= MAX_LENGTH) {
await api.sendMessage(numericId, text);
} else {
for (let i = 0; i < text.length; i += MAX_LENGTH) {
await api.sendMessage(numericId, text.slice(i, i + MAX_LENGTH));
}
}
logger.info({ chatId, sender, poolIndex: idx, length: text.length }, 'Pool message sent');
} catch (err) {
logger.error({ chatId, sender, err }, 'Failed to send pool message');
}
}Step 3: Add sender Parameter to MCP Tool
Read container/agent-runner/src/ipc-mcp-stdio.ts and update the send_message tool to accept an optional sender parameter:
Change the tool's schema from:
{ text: z.string().describe('The message text to send') },To:
{
text: z.string().describe('The message text to send'),
sender: z.string().optional().describe('Your role/identity name (e.g. "Researcher"). When set, messages appear from a dedicated bot in Telegram.'),
},And update the handler to include sender in the IPC data:
async (args) => {
const data: Record<string, string | undefined> = {
type: 'message',
chatJid,
text: args.text,
sender: args.sender || undefined,
groupFolder,
timestamp: new Date().toISOString(),
};
writeIpcFile(MESSAGES_DIR, data);
return { content: [{ type: 'text' as const, text: 'Message sent.' }] };
},Step 4: Update Host IPC Routing
Read src/ipc.ts and make these changes:
- Add imports — add
sendPoolMessageandinitBotPoolfrom the Telegram swarm module, andTELEGRAM_BOT_POOLfrom config. - Update IPC message routing — in
src/ipc.ts, find where thesendMessagedependency is called to deliver IPC messages (insideprocessIpcFiles). ThesendMessageis passed in via theIpcDepsparameter. Wrap it to route Telegram swarm messages through the bot pool:
if (data.sender && data.chatJid.startsWith('tg:')) {
await sendPoolMessage(
data.chatJid,
data.text,
data.sender,
sourceGroup,
);
} else {
await deps.sendMessage(data.chatJid, data.text);
}Note: The assistant name prefix is handled by formatOutbound() in the router — Telegram channels have prefixAssistantName = false so no prefix is added for tg: JIDs.
- Initialize pool in
main()insrc/index.ts— after creating the Telegram channel, add:
if (TELEGRAM_BOT_POOL.length > 0) {
await initBotPool(TELEGRAM_BOT_POOL);
}Step 5: Update CLAUDE.md Files
5a. Add global message formatting rules
Read groups/global/CLAUDE.md and add a Message Formatting section:
## Message Formatting
NEVER use markdown. Only use WhatsApp/Telegram formatting:
- *single asterisks* for bold (NEVER **double asterisks**)
- _underscores_ for italic
- • bullet points
- ```triple backticks``` for code
No ## headings. No [links](url). No **double stars**.5b. Update existing group CLAUDE.md headings
In any group CLAUDE.md that has a "WhatsApp Formatting" section (e.g. groups/main/CLAUDE.md), rename the heading to reflect multi-channel support:
## WhatsApp Formatting (and other messaging apps)5c. Add Agent Teams instructions to Telegram groups
For each Telegram group that will use agent teams, create or update its groups/{folder}/CLAUDE.md with these instructions. Read the existing CLAUDE.md first (or groups/global/CLAUDE.md as a base) and add the Agent Teams section:
## Agent Teams
When creating a team to tackle a complex task, follow these rules:
### CRITICAL: Follow the user's prompt exactly
Create *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.
### Team member instructions
Each team member MUST be instructed to:
1. *Share progress in the group* via `mcp__matclaw__send_message` with a `sender` parameter matching their exact role/character name (e.g., `sender: "Marine Biologist"` or `sender: "Alexander Hamilton"`). This makes their messages appear from a dedicated bot in the Telegram group.
2. *Also communicate with teammates* via `SendMessage` as normal for coordination.
3. Keep group messages *short* — 2-4 sentences max per message. Break longer content into multiple `send_message` calls. No walls of text.
4. Use the `sender` parameter consistently — always the same name so the bot identity stays stable.
5. NEVER use markdown formatting. Use ONLY WhatsApp/Telegram formatting: single *asterisks* for bold (NOT **double**), _underscores_ for italic, • for bullets, ```backticks``` for code. No ## headings, no [links](url), no **double asterisks**.
### Example team creation prompt
When creating a teammate, include instructions like:
\```
You are the Marine Biologist. When you have findings or updates for the user, send them to the group using mcp__matclaw__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.
\```
### Lead agent behavior
As the lead agent who created the team:
- You do NOT need to react to or relay every teammate message. The user sees those directly from the teammate bots.
- Send your own messages only to comment, share thoughts, synthesize, or direct the team.
- When processing an internal update from a teammate that doesn't need a user-facing response, wrap your *entire* output in `<internal>` tags.
- Focus on high-level coordination and the final synthesis.Step 6: Update Environment
Add pool tokens to .env:
TELEGRAM_BOT_POOL=TOKEN1,TOKEN2,TOKEN3,...Important: Sync to all required locations:
cp .env data/env/envAlso add TELEGRAM_BOT_POOL to the launchd plist (~/Library/LaunchAgents/com.matclaw.plist) in the EnvironmentVariables dict if using launchd.
Step 7: Rebuild and Restart
npm run build
./container/build.sh # Required — MCP tool changed
# macOS:
launchctl unload ~/Library/LaunchAgents/com.matclaw.plist
launchctl load ~/Library/LaunchAgents/com.matclaw.plist
# Linux:
# systemctl --user restart matclawMust use unload/load (macOS) or restart (Linux) because the service env vars changed.
Step 8: Test
Tell the user:
Send a message in your Telegram group asking for a multi-agent task, e.g.: "Assemble a team of a researcher and a coder to build me a hello world app"
You should see:
- The lead agent (main bot) acknowledging and creating the team
- Each subagent messaging from a different bot, renamed to their role
- Short, scannable messages from each agent
Check logs:
tail -f logs/matclaw.log | grep -i pool
Architecture Notes
- Pool bots use Grammy's
Apiclass — lightweight, no polling, just send - Bot names are set via
setMyName— changes are global to the bot, not per-chat - A 2-second delay after
setMyNameallows Telegram to propagate the name change before the first message - Sender→bot mapping is stable within a group (keyed as
{groupFolder}:{senderName}) - Mapping resets on service restart — pool bots get reassigned fresh
- If pool runs out, bots are reused (round-robin wraps)
Troubleshooting
Pool bots not sending messages
- Verify tokens:
curl -s "https://api.telegram.org/botTOKEN/getMe" - Check pool initialized:
grep "Pool bot" logs/matclaw.log - Ensure all pool bots are members of the Telegram group
- Check Group Privacy is disabled for each pool bot
Bot names not updating
Telegram 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.
Subagents not using send_message
Check the group's CLAUDE.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.
Removal
To remove Agent Swarm support while keeping basic Telegram:
- Remove
TELEGRAM_BOT_POOLfromsrc/config.ts - Remove pool code from
src/telegram.ts(poolApis,senderBotMap,initBotPool,sendPoolMessage) - Remove pool routing from IPC handler in
src/index.ts(revert to plainsendMessage) - Remove
initBotPoolcall frommain() - Remove
senderparam from MCP tool incontainer/agent-runner/src/ipc-mcp-stdio.ts - Remove Agent Teams section from group CLAUDE.md files
- Remove
TELEGRAM_BOT_POOLfrom.env,data/env/env, and launchd plist/systemd unit - Rebuild:
npm run build && ./container/build.sh && launchctl unload ~/Library/LaunchAgents/com.matclaw.plist && launchctl load ~/Library/LaunchAgents/com.matclaw.plist(macOS) ornpm run build && ./container/build.sh && systemctl --user restart matclaw(Linux)
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

