Claude Code, Codex CLI, Gemini CLI, 그리고 Antigravity CLI를 당신의 코딩 어시스턴트로 — Telegram 및 Matrix에서 사용하세요.

오직 공식 CLI만을 사용합니다. 스푸핑(spoofing)이나 프록시(proxy)를 사용하지 않습니다. 하나의 런타임(runtime) 내에서 멀티 트랜스포트(multi-transport), 자동화, 그리고 서브 에이전트(sub-agents)를 지원합니다.

빠른 시작 · 채팅 작동 방식 · 명령어 · 문서 · 기여하기

Claude Code, Google의 Gemini CLI, OpenAI의 Codex CLI, 또는 Antigravity CLI를 Telegram이나 Matrix를 통해 제어하고 싶거나, 자동화를 구축하거나, 여러 에이전트를 쉽게 관리하고 싶다면 — ductor가 당신에게 적합한 도구입니다. 메시징 레이어는 모듈식으로 설계되었습니다: 현재 Telegram과 Matrix를 지원하며, 새로운 트랜스포트(transports)가 동일한 트랜스포트 불가지론적(transport-agnostic) 코어에 플러그인 방식으로 연결될 수 있습니다.

ductor는 사용자의 머신에서 실행되며, 마치 사용자가 직접 타이핑하는 것처럼 단순한 콘솔 명령어를 전송하므로, 사용 중인 활성 구독(Claude Max, Google AI Ultra 등)을 직접 사용할 수 있습니다. API 프록시(proxying), SDK 패칭(patching), 스푸핑된 헤더(spoofed headers)가 없습니다. 오직 공식 CLI를 서브프로세스(subprocesses)로 실행하며, 모든 상태는 ~/.ductor/ 아래에 일반 JSON 및 Markdown 형식으로 유지됩니다.

pipx install ductor # 또는: uv tool install ductor
ductor

온보딩 위저드(onboarding wizard)가 CLI 체크, 트랜스포트 설정 (Telegram 또는 Matrix), 시간대, 선택 사항인 Docker, 그리고 선택 사항인 백그라운드 서비스 설치를 처리합니다.

요구 사항: Python 3.11 이상, 최소 하나 이상의 CLI 설치 (claude, codex, gemini, 또는 agy), 그리고 다음 중 하나가 필요합니다:

• @BotFather로부터 받은 Telegram Bot Token,
• 또는 홈서버(homeserver)의 Matrix 계정 (홈서버 URL, 사용자 ID, 비밀번호/액세스 토큰)

Matrix 지원을 위해: ductor install matrix — Matrix 설정 가이드를 참조하세요.

상세 설정: docs/installation.md

ductor는 코딩 에이전트와 상호작용할 수 있는 여러 가지 방법을 제공합니다. 각 단계는 이전 단계를 기반으로 구축됩니다.

이것은 모든 사람이 시작하는 단계입니다. 봇(Telegram 또는 Matrix)과 비공개 1:1 채팅을 할 수 있습니다. 모든 메시지는 활성화된 CLI (claude, codex, gemini, 또는 agy)로 전송되며, 응답은 실시간으로 스트리밍되어 돌아옵니다.

사용자: "이 코드베이스의 인증 흐름(auth flow)을 설명해줘"
봇: [Claude Code로부터 응답 스트리밍 중]
사용자: /model
...

이 단일 채팅만 있으면 충분합니다. 아래의 모든 기능은 선택 사항입니다.

Telegram: 그룹을 생성하고, 토픽(topics, 포럼 모드)을 활성화한 뒤 봇을 추가하세요.
Matrix: 봇을 여러 방(rooms)에 초대하세요 — 각 방은 고유한 컨텍스트(context)를 가집니다.

모든 토픽(Telegram) 또는 방(Matrix)은 각자의 CLI 컨텍스트를 가진 격리된 채팅이 됩니다.

그룹: "My Projects"
├── General ← 고유 컨텍스트 (단일 채팅과 격리됨)
├── Topic: Auth ← 고유 컨텍스트
...

이는 단일 그룹으로부터 5개의 독립적인 대화를 생성합니다. 사용자의 개인 단일 채팅 또한 별도로 유지되므로, 총 6개의 컨텍스트가 모두 병렬로 실행됩니다.

각 토픽은 서로 다른 모델을 사용할 수 있습니다. 특정 토픽의 제공자(provider)만 변경하려면 해당 토픽 내부에서 /model을 실행하세요.

모든 채팅은 동일한 ~/.ductor/ 워크스페이스(workspace)를 공유합니다 — 즉, 동일한 도구, 동일한 메모리, 동일한 파일을 사용합니다. 격리되는 유일한 요소는 대화 컨텍스트(conversation context)뿐입니다.

Telegram 참고 사항: Bot API에는 기존 포럼 토픽을 나열하는 메서드가 없습니다. ductor는 forum_topic_created 및 forum_topic_edited 이벤트를 통해 토픽 이름을 학습합니다. 따라서 이름이 변경되기 전까지 기존에 존재하던 토픽은 "Topic #N"으로 표시됩니다. 이는 Telegram의 제한 사항이며, ductor의 제한 사항이 아닙니다.

현재 컨텍스트를 잃지 않고 다른 작업을 수행해야 하나요? 이름이 지정된 세션(named session)을 시작하세요. 세션은 동일한 채팅 내에서 실행되지만, 고유한 CLI 대화를 가집니다.

사용자: "인증(authentication) 작업을 시작하자" ← 메인 컨텍스트가 구축됨
봇: [인증에 대해 응답함]
/session Fix the broken CSV export ← "firmowl" 세션 시작
...

세션은 단일 채팅, 그룹 토픽, 서브 에이전트(sub-agent) 채팅 등 어디에서나 작동합니다. 현재 사용 중인 터미널 옆에 두 번째 터미널 창을 여는 것이라고 생각하면 됩니다.

어떤 채팅이든 오래 걸리는 작업을 백그라운드 태스크(background task)로 위임할 수 있습니다. 태스크가 자율적으로 실행되는 동안 사용자는 계속 채팅을 이어갈 수 있습니다. 작업이 완료되면 결과가 다시 대화로 흘러 들어옵니다.

사용자: "상위 5개 경쟁사를 조사하고 요약본을 작성해줘"
봇: → 백그라운드 태스크 (background task)로 위임, 사용자는 계속 채팅 가능
봇: → 태스크 완료, 결과가 채팅창에 나타남
...

각 태스크는 고유의 메모리 파일 (TASKMEMORY.md)을 가지며, 후속 질문을 통해 재개할 수 있습니다.

서브 에이전트 (Sub-agents)는 완전히 분리된 봇입니다. 각자 고유의 채팅, 워크스페이스 (workspace), 메모리 (memory), CLI 인증 (auth), 설정 (config) (하트비트 (heartbeat), 타임아웃 (timeouts), 모델 기본값 (model defaults) 등)을 가집니다. 각 서브 에이전트는 서로 다른 전송 프로토콜 (transport)을 사용할 수 있습니다 (예: 메인 에이전트는 Telegram, 서브 에이전트는 Matrix).

ductor agents add codex-agent # 새로운 봇 생성 (자체적인 BotFather 토큰 필요)

메인 채팅 (Claude): "인증 흐름 (auth flow)을 설명해줘"
codex-agent 채팅 (Codex): "파서 모듈 (parser module)을 리팩터링(Refactor)해줘"

서브 에이전트는 ~/.ductor/agents/<name>/ 경로에 존재하며, 메인 에이전트와 완전히 격리된 자체 워크스페이스, 도구 (tools), 메모리를 가집니다.

에이전트 간에 태스크를 위임할 수 있습니다:

메인 채팅: "codex-agent에게 API 테스트 코드를 작성하라고 시켜줘"
→ Claude가 Codex에게 태스크를 전송
→ Codex가 자체 워크스페이스에서 작업 수행
...

구분	단일 채팅 (Single chat)	그룹 토픽 (Group topics)	이름 지정 세션 (Named sessions)	백그라운드 태스크 (Background tasks)	서브 에이전트 (Sub-agents)
정의	메인 1:1 채팅	하나의 토픽 = 하나의 채팅	모든 채팅에서 추가 컨텍스트 제공	"내가 계속 작업하는 동안 이것을 수행해줘"	별도의 봇, 모든 요소가 독립적
컨텍스트 (Context)	제공자(provider)당 하나	제공자당 토픽당 하나	세션당 고유 컨텍스트	고유 컨텍스트, 결과가 다시 돌아옴	완전히 격리됨
워크스페이스 (Workspace)	~/.ductor/	메인과 공유	부모 채팅과 공유	부모 에이전트와 공유	~/.ductor/agents/ 하위에 고유 워크스페이스
설정 (Config)	메인 설정	메인과 공유	부모 채팅과 공유	부모 에이전트와 공유	고유 설정 (하트비트, 타임아웃, 모델 등)
설정 방법 (Setup)	자동	그룹 생성 + 토픽 활성화	/session <prompt>	자동 또는 "이것을 위임해(delegate this)"	Telegram: ductor agents add ; Matrix: agents.json / 도구 스크립트

~/.ductor/ ← 공유 워크스페이스 (도구, 메모리, 파일)
│
├── 단일 채팅 (Single chat) ← 메인 에이전트, 프라이빗 1:1
...

멀티 트랜스포트 (Multi-transport)— Telegram과 Matrix를 동시에 실행하거나 하나를 선택하여 사용 가능
멀티 언어 (Multi-language)— 영어, 독일어, 네덜란드어, 프랑스어, 러시아어, 스페인어, 포르투갈어로 제공되는 UI
실시간 스트리밍 (Real-time streaming)— 실시간 메시지 수정 (Telegram) 또는 세그먼트 기반 출력 (Matrix)
Telegram 추론 + 도구 UX 제어 (Telegram reasoning + tool UX controls)— 선택 가능한 추론 스트림 (reasoning stream), 실시간 도구 진행 상황, 그리고 별도의 사고 표시기 (thinking indicator) 제어
인용 답장 컨텍스트 (Quoted-reply context)— 메시지에 답장 (Telegram)할 때 인용된 텍스트가 에이전트 프롬프트로 전달되므로, "이 내용을 확장해줘"와 같은 후속 질문이 참조를 유지함
4가지 코딩 에이전트 (Four coding agents)— Claude Code, Codex CLI, Gemini CLI, Antigravity (agy)
/model 명령어를 통해 채팅/토픽별로 전환 가능 (활성 프로세스 중에도 절대 차단되지 않음)
지속성 메모리 (Persistent memory)— 세션 간에도 유지되는 일반 Markdown 파일
메모리 유지 관리 (Memory maintenance)— 사전 압축 플러시 (pre-compaction flush), 선택 가능한 성찰 주기 (reflection cadence), 그리고 LLM 기반 압축 (compaction)
크론 잡 (Cron jobs)— 타임존 지원, 작업별 오버라이드, 선택 가능한 성공 시 무음 모드, 원래 채팅으로의 결과 라우팅 기능을 갖춘 프로세스 내 스케줄러
웹훅 (Webhooks)— wake (활성 채팅에 주입) 및 cron_task (격리된 작업 실행) 모드
하트비트 (Heartbeat)— 타겟별 설정을 지원하는 선제적 체크, 그룹/토픽 지원, 채팅 유효성 검사
이미지 처리 (Image processing)— 수신된 이미지에 대한 자동 크기 조정 및 WebP 변환 (설정 가능)
미디어 전사 훅 (Media transcription hooks)— 번들된 미디어 도구를 위한 설정 가능한 외부 오디오/비디오 전사 (transcription) 명령어
알림 라우팅 (Notification routing)— 시작/업그레이드 라이프사이클 메시지를 특정 채팅/토픽으로 대상 지정 가능
작업 우선순위 (Task priorities)— interactive (대화형), background (백그라운드), batch (배치)

백그라운드 작업을 위한 스케줄링 모드 (scheduling modes)
Telegram 상태 반응 (Telegram status reactions)— 에이전트가 작업하는 동안 사용자 메시지에 단계별 상태를 나타내는 이모지 추적기 (stage-aware emoji tracker)
설정 핫 리로드 (Config hot-reload)— 대부분의 설정(언어, 장면, 이미지 포함)은 재시작 없이 업데이트됨
Docker 샌드박스 (Docker sandbox)— 구성 가능한 호스트 마운트(host mounts)를 지원하는 선택적 사이드카 컨테이너 (sidecar container)
서비스 매니저 (Service manager)— Linux (systemd), macOS (launchd), Windows (Task Scheduler)
도구 간 기술 동기화 (Cross-tool skill sync)— ~/.claude/, ~/.codex/, ~/.gemini/ 간의 기술 공유 (전역적으로 또는 제공자별로 토글 가능)

Telegram은 주요 전송 수단(primary transport)입니다 — 전체 기능 세트를 갖추고 있으며, 충분히 검증되었고, 추가 의존성이 없습니다.

메신저 (Messenger)	상태 (Status)	스트리밍 (Streaming)	버튼 (Buttons)	설치 (Install)
Telegram	주요 (primary)	실시간 메시지 편집 (Live message edits)	인라인 키보드 (Inline keyboards)	pip install ductor
Matrix	지원됨 (supported)	세그먼트 기반 (새 메시지) (Segment-based)	이모지 반응 (Emoji reactions)	ductor install matrix

두 전송 수단 모두 동일한 에이전트에서 병렬로 (in parallel) 실행될 수 있습니다:

{"transport": "telegram"}
{"transport": "matrix"}
{"transports": ["telegram", "matrix"]}

각 메신저는 messenger/<name>/ 아래의 독립된 모듈이며, 공유된 BotProtocol을 구현합니다.

코어(오케스트레이터, 세션, CLI, cron 등)는 완전히 전송 수단에 무관(transport-agnostic)합니다 — 어떤 메신저가 메시지를 전달했는지 알지 못합니다.

새로운 메신저(Discord, Slack, Signal 등)를 추가하려면 새로운 서브 패키지에 BotProtocol을 구현하고 등록하기만 하면 됩니다. ductor의 나머지 부분은 변경 없이 작동합니다.
가이드: docs/modules/messenger.md

ductor는 이중 화이트리스트(dual-allowlist) 모델을 사용합니다. 모든 메시지는 두 가지 검사를 모두 통과해야 합니다.

채팅 유형 (Chat type)	검사 (Check)
개인 (Private)	user_id ∈ allowed_user_ids
그룹 (Group)	group_id ∈ allowed_group_ids AND user_id ∈ allowed_user_ids

allowed_user_ids — 봇과 대화할 수 있는 Telegram 사용자 ID 목록. 최소 하나 이상 필요합니다.
allowed_group_ids — 봇이 작동할 수 있는 Telegram 그룹 ID 목록. 기본값은 []이며, 이는 그룹이 없음을 의미합니다.
group_mention_only가 true인 경우, 봇은 그룹 내에서 멘션(@)되거나 답장(reply)을 받았을 때만 응답합니다.

세 가지 모두 핫 리로드 (hot-reloadable) 가 가능합니다. 즉, config.json을 수정하면 몇 초 이내에 변경 사항이 적용됩니다.

개인정보 보호 모드 (Privacy Mode): Telegram 봇은 기본적으로 개인정보 보호 모드가 활성화되어 있어, 그룹 내에서는 /commands만 볼 수 있습니다. 봇이 모든 메시지를 볼 수 있게 하려면, 봇을 그룹 관리자(group admin)로 지정하거나 BotFather를 통해 개인정보 보호 모드를 비활성화( /setprivacy → Disable)하십시오. 그룹에 참여한 후에 설정을 변경했다면, 봇을 제거했다가 다시 추가해야 합니다.

그룹 관리 (Group management): 봇이 allowed_group_ids에 포함되지 않은 그룹에 추가되면, 경고를 보낸 후 자동으로 그룹을 나갑니다. /where를 사용하여 추적 중인 그룹과 해당 ID를 확인할 수 있습니다.

채널 허용 목록 (Channel allowlist): Telegram 채널은 allowed_channel_ids를 통해 별도로 추적됩니다. 승인되지 않은 채널은 승인되지 않은 그룹과 마찬가지로, 참여 또는 감사(audit) 시 공지 후 자동으로 나갑니다.

팁 — 그룹을 처음 추가할 때:

• Telegram 그룹을 생성합니다. 개별 채팅 공간을 원한다면 토픽(topics)을 활성화하세요.
• 봇을 추가하고 관리자(admin)로 지정합니다 (모든 메시지에 접근하려면 필수).
• @your_bot을 언급하며 메시지를 보냅니다. (아직 봇이 응답하지는 않을 것입니다.)
• 봇과의 개인 채팅에서 /where를 실행합니다. 그러면 해당 그룹이 ID와 함께 "Rejected" 목록에 표시됩니다.
• 봇에게 다음과 같이 말합니다: "Add this as an allowed group in the config"
• 봇이 사용자를 대신해 config.json을 업데이트합니다.
• /restart를 실행합니다. 이제 봇이 그룹에서 응답합니다.

Matrix 인증은 matrix 설정 블록 내의 룸 및 사용자 허용 목록을 사용합니다:

• 봇이 작동할 수 있는 룸 ID 또는 별칭(aliases): allowed_rooms
• 봇과 상호작용할 수 있는 Matrix 사용자 ID: allowed_users

Matrix에서의 group_mention_only 세부 사항:

• DM(Direct Message)이 아닌 룸에서 group_mention_only=true인 경우, 봇은 @멘션 또는 답장(reply)을 요구하며, 해당 그룹 메시지에 대해서는 allowed_users 체크를 건너뜁니다. 단, 룸 수준의 필터링(allowed_rooms)은 여전히 적용됩니다.

봇은 첫 실행 시 비밀번호로 로그인하며, 이후 실행을 위해 access_token과 device_id를 유지합니다. E2EE(종단간 암호화)는 matrix-nio[e2e]를 통해 지원됩니다.

ductor의 UI(명령어, 상태 메시지, 온보딩)는 여러 언어로 제공됩니다:

코드	언어
en
영어 (기본값)
de
독일어
nl
네덜란드어
fr
프랑스어
ru
러시아어
es
스페인어
pt
포르투갈어

config.json에서 언어를 설정하세요:

{"language": "de"}

이 설정은 핫 리로드 (hot-reloadable) 가능합니다 — 봇을 재시작하지 않고도 언어를 변경할 수 있습니다.