Manager Bot vs Worker Bot: A Complete Guide to Clautel's Architecture
Clautel uses two types of bots to connect your phone to Claude Code. Understanding the difference between them — and how they work together — makes everything click.
This guide covers both from scratch: what each bot does, how to create them, and every command you'll use day to day.
How it works
The Two-Bot Architecture
Clautel uses two distinct bot types for a reason: separation of concerns.
-
The Manager Bot is your command center. There's only one. It handles project registration, subscription management, and routing. Think of it as the admin panel.
-
Worker Bots are project-specific. Each codebase gets its own dedicated bot. When you message a worker bot, you're talking directly to Claude Code running in that project's directory. You can have multiple sessions per bot — start fresh, resume old ones, or hand off to your terminal and come back.
This design means your conversations stay clean. Your frontend project's context never bleeds into your backend project. Switching projects is just switching Telegram chats.
Part 1: Setting Up the Manager Bot
The manager bot is created once during clautel setup. Here's exactly what happens.
Install Clautel
npm install -g clautel
Requires Node.js 18+. Takes about 10 seconds.
Run the setup wizard
clautel setup
The wizard walks you through three things interactively. You don't need to edit any config files.
Create your Manager Bot via @BotFather
Open Telegram and search for @BotFather — Telegram's official bot creator. The setup wizard will prompt you to do this.
BotFather
bot
Alright, a new bot. How are we going to call it? Please choose a name for your bot.
Good. Now let's choose a username for your bot. It must end in bot.
Done! Congratulations on your new bot. You will find it at t.me/my_clautel_manager_bot. Use this token to access the HTTP API: 7123456789:AAF... Keep your token secure and store it safely.
Copy the token BotFather gives you — the setup wizard will ask for it next.
Set your Telegram User ID
The wizard will also ask for your Telegram user ID. This is how Clautel ensures only you can control your bots — nobody else's messages get a response.
To find your user ID, message @userinfobot on Telegram. It replies instantly with your numeric ID.
Never share your bot token. Anyone who has it can send commands to your machine. If it leaks, revoke it immediately via @BotFather using /revoke.
Activate your license
The wizard will prompt you to enter your Clautel license key. Get one at clautel.com/#pricing — there's a 7-day free trial.
If you want to activate it manually later:
clautel activate YOUR_LICENSE_KEY
Start the daemon
clautel start
This starts the background process that listens for your Telegram messages. Your manager bot is now live.
On macOS, install it as a launchd service so it starts automatically on boot:
clautel install-service
Part 2: Manager Bot Commands
Once the daemon is running, open Telegram and message your manager bot. Here's everything it can do.
/add — Register a project
This is the most important manager bot command. It kicks off an interactive flow to create a worker bot for a specific directory on your machine.
Before running /add, go to @BotFather on Telegram and create a new bot (/newbot). You'll get a token — have it ready.
Then send /add to your manager bot and it will guide you through the rest:
Manager Bot
bot
Please send me the bot token for the worker bot. Create one via @BotFather if you haven't already.
Got it. Now send me the full path to the project directory on your machine.
Worker bot registered for /Users/you/projects/my-app. Open t.me/my_app_worker_bot to start coding.
After that, Clautel starts the worker bot automatically. You don't need to do anything else.
/bots — List your active bots
/bots
Manager Bot
bot
Active worker bots:\n\n• @frontend_bot → /Users/you/projects/frontend\n• @backend_bot → /Users/you/projects/backend\n• @infra_bot → /Users/you/projects/infrastructure
/remove — Remove a project bot
/remove @bot_username
This stops the worker bot and removes it from Clautel's registry. The Telegram bot itself still exists on Telegram — you'd delete that separately via @BotFather if you want.
/subscribe — Get or upgrade your plan
Opens the subscription flow directly in chat. Upgrades you from Pro (5 bots) to Max (unlimited bots).
/subscription — View billing & cancel
Shows your current plan, renewal date, and a link to manage or cancel.
/feedback — Send feedback to the team
We read everything. Use this if something's broken or you want a feature.
Part 3: Setting Up Worker Bots
Each worker bot is tied to one project directory. Within it, you can run multiple Claude Code sessions — start a new one with /new, pick up a previous one with /resume, or hand off to your terminal and come back. You create a Telegram bot for it via @BotFather (just like the manager bot), then register it with /add.
How many can you have?
- Pro plan ($4/mo): up to 5 worker bots
- Max plan ($9/mo): unlimited
Here's how adding three projects looks. Each /add is its own conversational flow — token first, then path:
Manager Bot
bot
Active worker bots: @frontend_bot → /projects/frontend | @backend_bot → /projects/backend
Part 4: Worker Bot Commands
Worker bots are where you actually talk to Claude Code. Every message you send is forwarded to Claude Code running in that project's directory.
Talking to Claude Code
Just type naturally — the same way you'd use Claude Code in your terminal:
frontend-bot
bot
Reading src/pages/dashboard.tsx... I can see the issue. The flex container is missing items-start which is causing the cards to stretch. Let me fix that.
Done. Updated line 34 in dashboard.tsx. The layout should be correct now.
/model — Switch Claude model
/model
Shows a menu to switch between available Claude models mid-session. Useful if you want to use a faster/cheaper model for simple tasks and switch back for complex ones.
/cost — Check token usage
/cost
backend-bot
bot
Session cost: ~$0.12\nInput tokens: 4,230\nOutput tokens: 1,105\nModel: claude-opus-4-6
/session — Get session ID to continue in CLI
/session
Returns the current session ID so you can continue the same conversation in your terminal using claude --resume SESSION_ID. Great for when you want to switch from phone to desktop mid-task.
backend-bot
bot
Current session ID: sess_01XabCdEfG\n\nTo continue in your terminal:\nclaude --resume sess_01XabCdEfG
/resume — Pick up a CLI session in Telegram
/resume
Shows your recent CLI sessions with timestamps. Tap one to continue it here in Telegram — full context intact, no loss of history.
backend-bot
bot
Recent sessions:\n\n1. sess_01Xa... — 2h ago — "Refactor user service to use repository pattern"\n2. sess_02Yb... — Yesterday — "Add rate limiting to auth endpoints"\n3. sess_03Zc... — 2 days ago — "Fix N+1 query in dashboard"
Resuming session from 2h ago. Context: you were refactoring the user service. The repository interface was created, migration is 60% complete. What would you like to do next?
/preview — Live browser screenshot
/preview https://localhost:3000
Takes a screenshot of any URL — including your local dev server — and sends it to Telegram. Includes interactive controls so you can click, scroll, and navigate.
frontend-bot
bot
[Screenshot of your dashboard]\n\n• Click: tap coordinates\n• /navigate — go to another URL\n• /browser — refresh screenshot
Use /preview right after Claude makes a UI change to visually confirm the result — without going to your laptop.
/new — Start a fresh session
/new
Clears the current conversation context and starts a new Claude Code session. Use this when switching between unrelated tasks.
/cancel — Abort a running operation
/cancel
Stops whatever Claude Code is currently doing. Useful if you realize mid-task that the prompt was wrong, or if something is taking too long.
Quick Reference
Manager Bot
| Command | What it does |
|---|---|
/add TOKEN /path | Register a new project worker bot |
/bots | List all active worker bots |
/remove @bot | Stop and remove a worker bot |
/subscribe | Get a license or upgrade your plan |
/subscription | View billing details and cancel |
/feedback | Send feedback to the Clautel team |
Worker Bot
| Command | What it does |
|---|---|
| Any message | Talk to Claude Code in that project |
| Photo / file | Attach as context for Claude |
/model | Switch Claude model |
/cost | Show token usage and cost |
/session | Get session ID to continue in CLI |
/resume | Pick up a recent CLI session here |
/preview <url> | Take a live browser screenshot |
/navigate <url> | Go to a different URL in browser |
/browser | Refresh current browser screenshot |
/new | Start a fresh session |
/cancel | Abort the current operation |
Common Setup Patterns
Solo developer, one project: One manager bot + one worker bot. Simple.
Solo developer, multiple projects: One manager bot + one worker bot per project. Switch between them by switching Telegram chats.
Small team: Each developer runs their own Clautel instance on their machine with their own manager + worker bots. No shared infrastructure needed.
Name your worker bots clearly — something like projectname_claude_bot — so you can tell them apart in Telegram's chat list.
Clautel starts at $4/mo. Get started at clautel.com — 7-day free trial, no card required upfront.