# agents_control

> agents_control is an open source remote for iTerm2, tmux and the AI agents inside them (Claude Code, Codex), controlled from Telegram. For Claude Code it relays the agent's questions and permission requests as reply buttons: the agent stops, buttons appear in Telegram, you answer, the session unblocks. It also lists tabs, shows a tab's screen, runs commands and starts new sessions. Everyone runs their own Telegram bot; there is no shared service. Made by 278labs.

Site: https://agentscontrol.278labs.co.uk/
Studio: https://278labs.co.uk/
Source: https://github.com/saparjohnick/agents_control
RubyGems: https://rubygems.org/gems/agents_control
Licence: Apache 2.0. Language: Ruby 3.1+. Platforms: macOS (iTerm2 or tmux), Linux (tmux). Windows is not supported.

## Install

- `gem install agents_control`
- or `git clone https://github.com/saparjohnick/agents_control && cd agents_control && bundle install`
- or in Claude Code: `/plugin marketplace add saparjohnick/agents_control` then `/plugin install agents-control@agents-control`
- Create a bot with @BotFather, then run `agents_control setup`, then `agents_control` to open the console.

## Telegram bot commands

- `/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; `/status` current status

## Command line

`agents_control` (console), `setup`, `sessions`, `daemon`, `hooks install|uninstall|status`, `stop`, `doctor`, `service install|uninstall|status`, `passphrase set|clear|status`, `version`.

## Key facts

- Present mode (default) mirrors Claude Code questions to Telegram but keeps them in the terminal; away mode (`/away`) waits for an answer. Silence is treated as a refusal.
- Files sent to the bot (photos, videos, voice notes, documents) are saved locally and the agent receives the local path, never a download link, because Telegram's file URL contains the bot token. Telegram caps bot downloads at 20MB.
- Destructive commands (recursive force delete of / or $HOME, fork bomb, mkfs, dd to a raw device) ask for a button tap or a passphrase first.
- The daemon's port binds to 127.0.0.1 only and it reaches Telegram by long polling (outgoing only). Access is limited to an allowed chat_id list. The bot token is stored in the Keychain (macOS) or libsecret (Linux).
- Other features: rate-limit anchors, automatic resume after a usage-limit reset, CLI menu buttons, autostart with launchd or systemd, `doctor` to check the environment.
- Codex sessions are visible and controllable like any tab, but without the question relay.

Contact: sapar@278labs.co.uk

## Optional

- [Full documentation as plain text](https://agentscontrol.278labs.co.uk/llms-full.txt): everything on this site in one file, for agents that prefer a single document.