ductor: run Claude Code, Codex CLI and Gemini CLI from Telegram, Matrix or Slack

What ductor actually solves for a solo developer

The problem is not that coding CLIs are hard to run. It is that they are bound to a terminal. You start a long refactor on your laptop, close the lid, and the session is gone from your reach. ductor takes the CLI you already have installed and executes it as a subprocess, then relays the console output to a chat app. The README puts it plainly: ductor "runs on your machine and sends simple console commands as if you were typing them yourself."

That framing matters for who this is for. It is aimed at a developer with an active subscription (the README names Claude Max and Google AI Ultra as examples) who wants to keep using that subscription rather than pay per token through an API. Because nothing is proxied and no headers are spoofed, the CLI sees exactly what it would see in a terminal. The audience is one person with several projects, not a platform team provisioning agents for fifty engineers.

How the transport-agnostic core drives five different CLIs

The architecture has three layers visible in the repository. At the bottom sit the official CLIs (claude, codex, gemini, agy, grok), spawned as subprocesses. In the middle is a transport-agnostic core. On top are the messaging transports: Telegram ships in the base install via aiogram, Matrix is an extra backed by matrix-nio, Slack is an extra backed by slack-bolt and slack-sdk.

The README describes the messaging layer as modular, with new transports plugging into the same core. That is the design bet: chat-specific concerns stay in ductor_bot/messenger/telegram/, and the agent logic does not know which messenger it is talking to. State lives in plain JSON and Markdown under ~/.ductor/, which is why a single workspace can back several isolated conversations at once.

The isolation model is worth understanding before you plan anything. A private chat, each Telegram forum topic, each Matrix room, and each named session gets its own CLI conversation context, but they all share the same ~/.ductor/ workspace, the same files, and the same memory. Only the conversation is separated. If you expected topic isolation to also mean filesystem isolation, you will be surprised.

Installing ductor and sending the first prompt

The README gives a two-line quick start. The first line installs the package with pipx or uv; the second launches the onboarding wizard, which walks through CLI detection, transport setup, timezone, optional Docker, and an optional background service.

pipx install ductor    # or: uv tool install ductor
ductor

Before that, the requirements are Python 3.11 or newer, at least one of claude, codex, gemini, agy or grok on your PATH, and a credential for one transport: a Telegram Bot Token from @BotFather, a Matrix account with homeserver URL, user ID and password or access token, or a Slack bot token plus an app token. Matrix support is added separately with `ductor install matrix`. Slack needs an extra pip install and two config keys.

ductor install matrix
pip install "ductor[slack]"

For Slack, the README points at docs/installation.md#slack-setup for the app scopes and events, and says to configure `slack.bot_token` and `slack.app_token`. Once the wizard finishes, you open the bot chat and send a plain sentence. The bot streams the CLI response back into the chat, and the next message continues the same session context. Commands are typed with a leading slash: `/model` opens an interactive provider picker, and `/session` starts a named session inside the current chat.

You:   "Explain the auth flow in this codebase"
Bot:   [streams response from Claude Code]

You:   /model
Bot:   [interactive model/provider picker]

That is the whole first run. Groups with topics, background tasks, and sub-agents are layers you add later, not prerequisites.

Limits you hit once the novelty wears off

The most concrete limitation is Telegram's, and ductor documents it rather than hiding it. The Bot API has no method to list existing forum topics, so ductor learns topic names from `forum_topic_created` and `forum_topic_edited` events. Any topic that existed before the bot joined shows as "Topic #N" until someone renames it. If you run a large forum group, expect a wall of numbered topics on first connect.

A second constraint is the shared workspace. Because every chat, topic and session reads and writes the same ~/.ductor/ tree, a background task that edits a file can collide with what you are doing in your main chat. The isolation is conversational, not filesystem-level. The README does not document rollback or conflict handling for that case, so plan around it rather than expecting it to be solved.

Third, this is a subprocess wrapper. It inherits whatever your CLI does, including its latency, its rate limits and its failure modes. If the CLI hangs, ductor is waiting on a hung process. There is no queueing layer described in the README that would let a second request proceed while the first is stuck.

Finally, ductor is the wrong tool if you need a hosted or multi-tenant service. It is designed to run on your machine against your credentials. Handing a shared bot token to a team means handing out your subscription and your filesystem.

ductor compared with building your own bot wrapper

The obvious alternative is a small script: aiogram or slack-bolt plus `subprocess.run`, roughly a hundred lines. That gets you a bot that answers prompts. The difference is everything the README lists around it. ductor already handles live streaming of partial output, persistent memory across messages, cron jobs, webhooks, Docker sandboxing via Dockerfile.sandbox, named sessions, background tasks with their own TASKMEMORY.md, and sub-agents with separate workspaces and separate CLI auth. Reproducing the session and topic isolation alone is more work than it looks, because the mapping from chat identity to CLI context has to survive restarts.

The other alternative is an agent framework that talks to model APIs directly. That approach is cleaner to deploy and easier to scale, but it bills per token and abandons the subscription you already pay for. ductor's whole premise is the opposite trade: keep the subscription, accept that the process runs on your hardware.

If you only ever want one chat and one CLI, the custom script is genuinely competitive. The gap opens when you want several isolated contexts, scheduled runs, or a second agent with its own auth.

Maintenance, releases and what the MIT licence leaves you

The repository is not archived, and the last push was on 2026-07-23. Release cadence in the visible window is fast: v0.19.0 on 2026-07-12, v0.20.0 on 2026-07-22, v0.20.1 on 2026-07-23. The version in pyproject.toml is 0.20.1, and the classifier is Development Status 4 - Beta, which is the honest label for a project moving this quickly.

Upgrade cost is low if you installed with pipx or uv: the tool lives in its own environment, so `pipx upgrade ductor` or the uv equivalent replaces it without touching your project dependencies. The moving parts are the extras. A Matrix or Slack install pulls matrix-nio or slack-bolt, and those have their own release cycles.

The MIT licence is permissive, and pyproject.toml declares it with a LICENSE file. That covers ductor's own code. It does not cover the CLIs you drive through it, which carry their own terms, and it does not cover what those CLIs do with your files. If you run ductor against a proprietary codebase, the licence question is about your CLI vendor, not about ductor.

Editorial conclusion

Adopt ductor if you already run claude, codex, gemini, agy or grok locally, pay for a subscription, and want that same session reachable from Telegram, Matrix or Slack without an API proxy in the middle. Skip it if you need a hosted service, an audited multi-tenant deployment, or a stable release line: pyproject.toml still declares Development Status 4 - Beta, and the last push was on 2026-07-23. Before committing, verify three things on your own machine: that your CLI authenticates inside the Docker sandbox, that a scheduled job fires in your timezone, and that the Slack extra installs cleanly on your Python version.

Frequently asked questions

Official sources

1. License: MIT
2. PleasePrompto/ductor on GitHub
3. Project website
4. README
5. Releases