ductor

<p align="center"> <img src="https://raw.githubusercontent.com/PleasePrompto/ductor/main/ductor_bot/messenger/telegram/ductor_images/logo_text.png" alt="ductor" width="100%" /> </p> <p align="center"> <strong>Claude Code, Codex CLI, and Gemini CLI as your coding assistant — on Telegram.</strong><br> Uses only official CLIs. Nothing spoofed, nothing proxied. Matrix and more via plugin system. </p> <p align="center"> <a href="https://pypi.org/project/ductor/"><img src="https://img.shields.io/pypi/v/ductor?color=blue" alt="PyPI" /></a> <a href="https://pypi.org/project/ductor/"><img src="https://img.shields.io/pypi/pyversions/ductor?v=1" alt="Python" /></a> <a href="https://github.com/PleasePrompto/ductor/blob/main/LICENSE"><img src="https://img.shields.io/github/license/PleasePrompto/ductor" alt="License" /></a> </p> <p align="center"> <a href="#quick-start">Quick start</a> &middot; <a href="#how-chats-work">How chats work</a> &middot; <a href="#commands">Commands</a> &middot; <a href="docs/README.md">Docs</a> &middot; <a href="#contributing">Contributing</a> </p>

---

If you want to control Claude Code, Google's Gemini CLI, or OpenAI's Codex CLI via Telegram, build automations, or manage multiple agents easily — ductor is the right tool for you. Additional messengers (Matrix, and more to come) are supported via a modular plugin system.

ductor runs on your machine and sends simple console commands as if you were typing them yourself, so you can use your active subscriptions (Claude Max, etc.) directly. No API proxying, no SDK patching, no spoofed headers. Just the official CLIs, executed as subprocesses, with all state kept in plain JSON and Markdown under ~/.ductor/.

<p align="center"> <img src="https://raw.githubusercontent.com/PleasePrompto/ductor/main/docs/images/ductor-start.jpeg" alt="ductor /start screen" width="49%" /> <img src="https://raw.githubusercontent.com/PleasePrompto/ductor/main/docs/images/ductor-quick-actions.jpeg" alt="ductor quick action buttons" width="49%" /> </p>

Quick start

pipx install ductor
ductor

The onboarding wizard handles CLI checks, transport setup (Telegram or Matrix), timezone, optional Docker, and optional background service install.

Requirements: Python 3.11+, at least one CLI installed (claude, codex, or gemini), and either:

• a Telegram Bot Token from @BotFather, or
• a Matrix account on a homeserver (homeserver URL, user ID, password/access token)

For Matrix support: ductor install matrix — see Matrix setup guide.

Detailed setup: docs/installation.md

How chats work

ductor gives you multiple ways to interact with your coding agents. Each level builds on the previous one.

1. Single chat (your main agent)

This is where everyone starts. You get a private 1:1 chat with your bot (Telegram or Matrix). Every message goes to the CLI you have active (claude, `code...