agents_control is a remote for iTerm2, tmux and the AI agents inside them. When Claude Code stops and waits, the question arrives in Telegram with reply buttons. You answer, the session unblocks.
Downloads from RubyGems, clones and stars from GitHub (clones include automated ones). GitHub keeps 14 days of traffic, so the history is saved daily here. Snapshot of 13 Oct 2026.
Claude Code calls agents_control through its own hooks when it stops. The question and its reply buttons arrive in Telegram, and Claude Code waits while you answer. A question can also be answered by replying to its message, even with several tabs open.
Silence counts as a refusal: if nobody answers, the action does not happen. In present mode (the default) questions are mirrored but stay in the terminal. In away mode (/away) they wait for your tap.
/tabs lists your tabs, /screen N shows one, /run N command runs a command and shows the result, /new opens a tab. Reply to a result and your text is typed into the same pane, so back-and-forth prompts like git add -p work over Telegram.
A tab stuck in less, vim or a REPL asks for confirmation first, instead of a blind send.
Photos, videos, voice notes and documents sent to the bot are saved on your machine, and the agent receives the file's local path. Name the target with a caption like /run 3 why does this render wrong? or by replying to a session's message. With nothing to go on, the file is saved and the path comes back, never guessed.
A path and never a link, on purpose: Telegram's download URL contains the bot token.
Limit reset. Notices a message like "resets 3pm" and types the continuation itself when the time comes. CLI menus. Turns Claude Code's own "1. … 2. …" choices into buttons. Rate-limit anchors. Moves the five-hour window to times that suit you, with a ping from a cheap model.
Everyone runs their own bot: there is no shared service. The daemon listens on 127.0.0.1 only and reaches Telegram with outgoing connections. Only chats on your allowed list get answers. The token lives in the Keychain or libsecret, never in a file.
Destructive commands such as rm -rf ~, mkfs or a fork bomb ask first: a button tap, or a passphrase you set.
rm -rf ~Reply to this message with the passphrase to send it to mobile-app. Anything else cancels.
Both exchanges follow the examples in the project's README.
| /agents | Sessions with a live agent. |
|---|---|
| /tabs | All terminal tabs. |
| /screen N | Show a tab's screen. |
| /focus N | Switch to a tab. |
| /run N command | Run a command in a tab and show the result. Replying to the result types into the same pane. |
| /new [directory] | Create a tab. |
| /away | Intercept agent questions before you step out. |
| /status | Current status. |
The number N comes from the last list shown.
| /sessions | Sessions with a live agent. |
|---|---|
| /tabs | All terminal tabs. |
| /away | Intercept agent questions. |
| /settings | Settings. /settings away toggles away mode. |
| /doctor | Check that everything is in place. |
| /quit | Quit. |
| agents_control | Open the console and stay in the tab. This is the normal way to run it. |
|---|---|
| agents_control setup | Set up the Telegram bot: asks for the token, waits for your /start. |
| agents_control sessions | Show agent sessions. |
| agents_control daemon | Run the daemon: agent hooks plus Telegram. |
| agents_control hooks status | Check, install or uninstall the agent hooks. |
| agents_control stop | Stop a running daemon. |
| agents_control doctor | Check that everything is in place, in the environment the daemon will actually get. |
| agents_control service install | Autostart with launchd or systemd. Also uninstall and status. |
| agents_control passphrase set | Passphrase for destructive commands. Also clear and status. |
| agents_control version | Print the version. |
You need Ruby 3.1 or newer. The only dependency is thor, pure Ruby, so nothing compiles.
gem install agents_control
Or clone the source, or add it from inside Claude Code as a plugin.
git clone https://github.com/saparjohnick/agents_control
cd agents_control
bundle install
# or, in Claude Code:
/plugin marketplace add saparjohnick/agents_control
/plugin install agents-control@agents-control
Make a bot with @BotFather in Telegram, then run the wizard. It catches your chat_id from your own message and adds it to the allowed list, so you never type a long number by hand.
agents_control setup # asks for the token, waits for your /start
The tool lives in a tab. While it is open, it listens to Telegram and receives agent events.
agents_control
Both are optional. A passphrase replaces the confirmation button for destructive commands. Then check the setup.
agents_control passphrase set # typed without echo, stored in the Keychain agents_control service install # autostart (launchd / systemd) agents_control doctor # is everything in place