Summary

ductor integrates official Claude Code, Codex CLI, and Gemini CLI into Telegram and Matrix, enabling sophisticated automations and multi-agent workflows. It targets developers and power users seeking direct control over LLM subscriptions via chat, offering persistent memory, cron jobs, webhooks, and Docker sandboxing without unofficial APIs.

How It Works

The core architecture executes official CLIs as subprocesses, ensuring direct use of subscriptions and avoiding terms-of-service violations. State is managed via plain JSON and Markdown files under ~/.ductor/. ductor supports flexible interactions: single chats, isolated group topics, named sessions, asynchronous background tasks, and fully independent sub-agents, all sharing a common workspace but maintaining distinct conversational states.

Quick Start & Requirements

Install via pipx install ductor. Requires Python 3.11+ and at least one official CLI (claude, codex, or gemini). Messenger setup needs a Telegram Bot Token or Matrix credentials. An interactive onboarding wizard handles CLI checks, transport configuration, and optional Docker/service installation. See docs/installation.md.

Highlighted Details

• Multi-transport: Simultaneously operate Telegram and Matrix interfaces.
• Real-time Streaming: Live message edits (Telegram) and segment-based output (Matrix).
• Dynamic Provider Switching: /model command changes LLM providers/models mid-conversation without interruption.
• Persistent Memory: All agent and session memory stored in plain Markdown files.
• Automation & Isolation: Built-in cron jobs, webhooks, optional Docker sandboxing, and sub-agents with isolated workspaces.

Maintenance & Community

Hosted on GitHub (https://github.com/PleasePrompto/ductor.git). Specific details on maintainers, sponsorships, or community channels were not explicitly detailed in the provided README.

Licensing & Compatibility

Released under the MIT license, permitting broad use, modification, and distribution, including commercial purposes. Users must validate compliance with underlying LLM provider terms of service for unattended automation.

Limitations & Caveats

Telegram topic naming may initially show "Topic #N". Matrix transport requires ductor install matrix. Users must configure allowed users/groups for security. Telegram's default privacy mode needs specific setup for bots to access all group messages.