Remote-control and monitor Claude Code from Telegram

Start a task, close the laptop, and let Claude keep coding. Agent Babysitter messages your phone when work finishes, takes your reply straight back into the same live session, and lets you send screenshots, use voice, and check your usage — all from Telegram.

Claude Code already does the work. Agent Babysitter is the piece that lets you walk away from it — a thin bash script wrapped around Anthropic's official Telegram plugin. No daemon, no webhook, no second copy of your session.

_{▶︎ 50-second demo — one-line install, pair your phone with a PIN, then close the laptop and let Claude keep working. Watch with audio →}

---

✨ Why you'll love it

• 🔔 Leave your desk — get pinged when Claude finishes or needs a decision.
• 📱 Reply from your phone — your message lands in the same live session.
• 🖼 Send screenshots — attach an image and Claude reads it directly.
• 🎤 Voice both ways — send a voice note, or ask for the answer spoken back.
• 📊 Check usage remotely — your Claude limits, one tap away, no browser.
• 🔒 Your own private bot — PIN-paired, so only you can reach it.
• 🟢 See the state at a glance — a dot in Claude's status bar shows whether reports are flowing or muted, plus your 5-hour and weekly usage.
• 🖥 Runs anywhere — laptop, SSH, tmux, a headless Linux server.
• 🗂 Multiple projects — one bot per project, babysat side by side.

🚀 Quick start

Install it, then run abs instead of claude:

curl -fsSL https://agentbabysitter.com/install.sh | bash
abs

It installs a single script to ~/.local/bin/abs and touches nothing else. Piping to bash is your call to make — read it first if you'd rather.

Prefer Python packaging?

pipx install agent-babysitter     # or: pip install agent-babysitter

From source, or to contribute:

git clone https://github.com/Pranjalab/AgentBabysitter
cd AgentBabysitter
./install.sh

About two minutes, once per bot:

1. 🤖 Create a bot — message @BotFather, send /newbot, and paste the token back (it stays hidden and never leaves your machine).
2. 📲 Pair your phone — abs prints a short PIN; send it to your bot. That proves the phone is yours, and from then on the bot answers only you.
3. ✅ Done — Claude Code starts. Walk away; you'll get a message when a task finishes.

After setup it's just abs, from whatever project you're in. Setup is once per bot, not once per project.

Prerequisites: claude, bun, jq, curl. The installer checks for them and tells you what's missing rather than installing anything behind your back.

🧩 Features

🔔 Notifications — know when Claude needs you

A task finishing sends a short summary to your phone: what happened, and anything that needs a decision. Stop babysitting the spinner; the spinner tells you when it's done.

💬 Remote control — steer the same session from your phone

Reply in plain English and it arrives in the live session as if you'd typed it at the desk. Approve a step, change direction, ask a question — the terminal and Telegram are one session, not two conversations.

🖼 Screenshots — hand Claude an image without the terminal

Pasting an image into a terminal is awkward. Attach it in Telegram instead and Claude reads it directly — a broken UI, a stack trace you photographed, a design to match.

🎤 Voice — talk to Claude, and have it talk back

Send a voice note and it's transcribed; ask for the answer spoken and it replies with a real voice message. Both run locally — no audio ever leaves your machine.

Voice is an optional add-on (it pulls in Whisper + Chatterbox, a few GB), so the installer offers it as a separate step — or turn it on any time with a single command:

abs voice setup      # builds the local speech engines; abs voice status to check

Pick the model for speed vs. expression (abs config voice standard|turbo — turbo generates ~1.8× faster), and clone a voice from any short reference clip so replies speak in the voice you choose (abs config voice-sample <clip>, or --audio-prompt per call).

📊 Usage — check your Claude limits without leaving the chat

Tap /usage and your subscription limits and reset times come to Telegram — no browser, no app, no breaking focus before a big task.

🗂 Profiles — babysit several projects at once

Each project gets its own bot, so you can run more than one session in parallel without them fighting over messages — abs --profile work.

🛑 Remote controls — a kill ladder that doesn't trust the model

Send any of these from Telegram as a whole message and the session hook acts on it itself — so they work even if the model has been prompt-injected or turned against you (it never runs them):

Phrase	Does
ABS MUTE / ABS UNMUTE	Mute / resume proactive reports (catch-up on resume)
ABS OFF	Cut inbound and outbound Telegram; the session keeps working
ABS STOP	Halt the current plan at the next step and wait for a new instruction
ABS EXIT	Close the session (asks to confirm if mid-task); restart with abs
ABS BLOCK	Lock the bot out entirely until a deliberate abs setup

And a destructive-command guard: when a turn is driven from Telegram, a PreToolUse hook blocks a small, high-confidence set of dangerous commands (rm -rf, git push --force, DROP/TRUNCATE, reading .env/keys, …) and tells you to run them at the terminal — where you're proven to be at the desk. From the terminal, nothing is blocked. Opt out with abs config guard off. Full model and the honest limits in SECURITY.md.

🔒 Security — a private bot only you can reach

Pairing writes your Telegram ID to an allowlist; anyone else who finds the bot is ignored before Claude ever sees the message. Full model in SECURITY.md.

🤔 Why Agent Babysitter?

Claude Code can already talk to Telegram — Anthropic ships an official plugin for it. But the bare plugin is just a pipe: it forwards messages and nothing more. Agent Babysitter is the workflow around that pipe.

	Official Telegram plugin, alone	With Agent Babysitter
Chat with the session from Telegram	✅	✅
Guided bot setup & token validation	Manual	✅ One command
Only you can reach the bot	Basic	✅ PIN pairing + allowlist
"Task finished" reports to your phone	❌	✅
Check Claude usage from Telegram	❌	✅
Voice notes in and out, processed locally	❌	✅
Send screenshots Claude reads	Raw	✅ Built in
Run multiple projects at once	❌ Single bot	✅ Profiles
Mute / hard-off controls	❌	✅

It complements Claude Code — it doesn't replace or fork it. Your session, your CLAUDE.md, and your permissions are all untouched.

🎯 Perfect for

• 🌙 Overnight jobs and long refactors you don't want to watch.
• 🛠 Bug-fixing sessions where you step away between turns.
• 🖥 Remote servers — run it over SSH on a VPS or home box and close the laptop.
• ☕ Coffee breaks and working from another room.
• 🗂 Multi-project days — a bot per project, all reporting to one phone.

💡 Why I built it

Three ordinary frustrations, all from using Claude Code every day:

1. I was chained to my desk. The moment I walked away I'd start worrying — is it waiting on me to approve something? Has it finished? Did it go the wrong way ten minutes ago while I was making coffee? So I just… sat there.
2. I kept checking my usage. Before a big task I'd open the browser again to see how much of my limit was left. Ten seconds, every time, breaking my focus.
3. Handing Claude a screenshot was a pain. Pasting into the terminal is awkward, and the image was usually on my phone anyway.

Agent Babysitter fixes all three — and it's stayed a single bash script the whole way, because the point was to remove friction, not add a platform.

⌨️ Commands

abs                     # start a session (first run does setup)
abs --model opus        # any claude flag is passed straight through

Command	What it does
📋 abs status	What's paired, inbound state, whether it's live
📊 abs usage	Your Claude limits — in the terminal and on Telegram
🗂 abs profiles	List your bots and which are in use
⚙️ abs config model <name>	Default model for new sessions (--clear to unset)
⚙️ abs config silent on / off	Whether new sessions start muted
⚙️ abs config statusline on / off	Bottom-bar mute/active dot + usage (default on)
⚙️ abs config usage-refresh <min>	How often the usage glance refreshes (default 5)
⚙️ abs config guard on / off	Block destructive commands on Telegram turns (default on)
⚙️ abs config voice standard / turbo	Default TTS model — expressive vs. ~1.8× faster
⚙️ abs config voice-sample <file>	Clone a voice for spoken replies (both models)
🔕 abs quiet on / off	Mute / unmute reports (inbound still works)
🛑 abs off / on	Drop / re-enable all inbound + outbound Telegram
🚪 abs exit	End the running session (restart with abs)
🎤 abs say [--turbo] "text"	Speak it and send as a voice note (--audio-prompt to clone)
♻️ abs reset	Remove this profile's token, allowlist, and state
❓ abs help	The full list

From Telegram, the hook-enforced kill ladder — sent as a whole message — ABS MUTE / ABS UNMUTE · ABS OFF · ABS STOP · ABS EXIT · ABS BLOCK (see Remote controls).

You can also just say it in chat — "mute the reports", "what's my usage" — and it runs the same commands. For voice setup, profiles, servers, and troubleshooting, see the full guide.

🏗 Architecture

Telegram polls outbound, so nothing listens on a port and no webhook is needed — which is why it works the same on a laptop, over SSH, or on a headless server.

flowchart LR
    You["📱 You (Telegram)"] <--> Bot["Your private bot"]
    Bot <--> Plugin["Official Telegram plugin"]
    Plugin <--> ABS["Agent Babysitter (abs.sh)"]
    ABS <--> Claude["Claude Code session"]
    Claude --> Project[("Your project")]

Loading

Agent Babysitter validates your token, pairs your phone, injects the "report when done" behavior per session, manages profiles, and reports usage. The plugin owns the inbound polling; Claude Code does the work.

🔒 Security

Only you can message your bot. Pairing records your Telegram user ID in an allowlist, and anyone else who finds the bot is ignored before Claude sees the message. The PIN pairing proves the phone is yours; the bot token is kept out of ps and stored owner-only.

It is not a sandbox, though — within your paired account, Claude has whatever power Claude Code gives it on your machine. Read SECURITY.md for the full model, including what it deliberately does not protect against.

❓ FAQ

Does it expose my code? No. It's your own private bot, and only your paired account can reach it. One honest caveat: Telegram itself sees the messages (they're not end-to-end encrypted), so don't use it for work where that matters.

Can anyone else message my bot? No. Unpaired accounts are dropped before Claude ever sees them.

Does voice processing stay local? Yes. Transcription and speech both run on your machine — no cloud speech vendor is involved. (The audio still travels over Telegram, like any message.)

Can I run multiple projects? Yes — one bot per project, via profiles.

Does it work over SSH / on a server? Yes. Telegram polls outbound, so no public IP, open port, or webhook is needed. Run it in tmux and close the laptop.

Does it require a server? No. It runs anywhere Claude Code runs — a server is just one option.

Can I stop Claude remotely? Not yet. Messages are read between turns, so you can steer the next step but not interrupt the current one.

Which platforms are supported? Linux and macOS, both tested — including macOS's ancient bash 3.2, with no Homebrew or GNU coreutils needed. On macOS, reset times show as clock times (resets Jul 17 at 2:40am) rather than countdowns, since that needs GNU date. Windows via WSL should work but is untested; reports welcome.

🙏 Acknowledgements

Agent Babysitter stands on two things it doesn't reinvent:

• Claude Code — the AI coding agent doing the actual work.
• Anthropic's official Telegram plugin (telegram@claude-plugins-official) — it owns the inbound polling and the download_attachment / reply tools this builds on.

🤝 Contributing

Issues, ideas, and pull requests are all welcome — bug reports and "it broke on my setup" notes especially. See CONTRIBUTING.md for how to test a change, and our Code of Conduct for the ground rules. Version history lives in CHANGELOG.md.

If Agent Babysitter saves you from waiting around for Claude Code, a ⭐ genuinely helps other developers find it.

📄 License

MIT — see LICENSE. Do what you like with it.