Getting it into your agent
One page per mod, every tool's command on it. A separate URL per tool would split the same page into five that compete with each other.
npx agentmods add instructions/pleaseprompto/ductor/gemini-mdgit clone --depth 1 https://github.com/PleasePrompto/ductorWrote this? Show the measurements
A badge with what this costs and how it scanned, read live from this page, so it follows the numbers instead of freezing them. Markdown for a README, HTML for a documentation site or a project page.
[](https://agentmods.dev/instructions/pleaseprompto/ductor/gemini-md)<a href="https://agentmods.dev/instructions/pleaseprompto/ductor/gemini-md"><img src="https://agentmods.dev/badge/instructions/pleaseprompto/ductor/gemini-md.svg" alt="Measured on agentmods" height="20"></a>What it costs to keep this loaded
Counted locally with the o200k_base tokenizer, which is exact for GPT models; Claude uses its own tokenizer and its counts differ. Treat this as one consistent yardstick across the catalogue rather than a bill. Prices are per million input tokens.
| Model | Per session | Once invoked |
|---|---|---|
| Fable 5.1 | $0.01682 | $0.01682 |
| Opus 5 | $0.00841 | $0.00841 |
| Sonnet 5 | $0.00336 | $0.00336 |
| Haiku 4.5 | $0.00168 | $0.00168 |
Grade A, and why
ductor GEMINI.md scanned grade A with 0 findings against 26 rules in 11 categories — prompt injection, anti-refusal, data exfiltration, privilege escalation, supply chain, agent snooping, system-prompt leakage, SSRF and excessive agency — measured 6d ago.
A static scan of the body, not an audit. Every finding is printed with the line that produced it so you can judge whether it matters here. A mod is markdown that instructs an agent; that is exactly why what it instructs is worth reading.
Nothing flagged
None of the 26 patterns this scan looks for appear in this file: no shell pipes, no recursive deletes, no credential paths, no hidden text, no instruction-override or anti-refusal phrasing, no agent-config snooping. That is not a guarantee, it is the absence of the things that are checkable.
This is a copy
86% identical to ductor AGENTS.md — 16 lines differ, which has more behind it and is treated as the original. This page carries a canonical link to it rather than competing with it.
How it starts
The opening of the file, as written. The whole thing — 180 lines — stays where its author put it; the contents beside it link to each section on GitHub.
This file gives coding agents a current map of the repository.
Project Overview
ductor is a multi-transport chat orchestrator for the official provider CLIs (claude, codex, gemini, agy).
It runs Telegram and/or Matrix, can expose an optional direct WebSocket API, keeps state under ~/.ductor, and supervises the main agent plus optional sub-agents in one asyncio process.
Stack:
- Python 3.11+
- aiogram 3.x (Telegram)
- matrix-nio (Matrix, optional extra)
- aiohttp (webhook server, internal API, optional direct API)
- Pydantic 2.x
- asyncio
Development Commands
# Setup
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
# Run
ductor
ductor -v
# Tests
pytest
pytest -k "pattern"
# Quality
ruff format .
ruff check .
mypy ductor_bot
Runtime Flow
Telegram:
Update -> AuthMiddleware -> SequentialMiddleware -> TelegramBot
-> Orchestrator -> CLIService -> provider subprocess -> Telegram delivery
Matrix:
sync event -> MatrixBot auth/room checks -> Orchestrator
-> CLIService -> provider subprocess -> Matrix delivery
API (optional):
/ws auth (token + e2e_pk + optional chat_id/channel_id)
-> encrypted frames -> Orchestrator streaming -> encrypted result events
Background and async delivery:
Observer / TaskHub / InterAgentBus callback
-> bus.adapters -> Envelope -> MessageBus
-> optional shared lock + optional session injection
-> registered transport adapters (TelegramTransport / MatrixTransport)
Module Map
| Module | Purpose |
|---|---|
cli_commands/ |
CLI command implementations (service, docker, api, agents, lifecycle, install, status) |
messenger/ |
transport protocol, capabilities, notifications, registry, multi-transport adapter |
messenger/telegram/ |
Telegram transport: middleware, handlers, startup, callback routing, file/media UX |
messenger/matrix/ |
Matrix transport: sync loop, auth, segment streaming, reaction buttons, media |
orchestrator/ |
command routing, directives/hooks, flows, provider/session/task wiring, lifecycle split |
bus/ |
unified Envelope, MessageBus, shared LockPool, delivery adapters |
cli/ |
provider wrappers, stream parsing, auth detection, model caches, process registry |
session/ |
SessionKey(transport, chat_id, topic_id), provider-isolated session buckets, named sessions |
tasks/ |
delegated background task runtime (TaskHub) and persistent registry |
background/ |
named background session execution for /session |
multiagent/ |
supervisor, inter-agent bus, internal localhost API bridge, shared knowledge sync |
api/ |
optional direct WebSocket API and authenticated file endpoints |
cron/, webhook/, heartbeat/, cleanup/ |
in-process automation observers |
workspace/ |
~/.ductor path model, seeding, rule deployment/sync, skill sync |
infra/ |
PID lock, service backends, Docker manager, restart/update/recovery helpers |
files/ |
shared file/path safety, MIME detection, image processing (image_processor.py: resize/convert incoming images) |
security/, text/ |
prompt safety, formatting helpers |
What this file has done since we first saw it
Hashed on every crawl. A supply-chain change to an agent config is a question of when, not whether, so the history is kept rather than the latest state alone.
- 6d ago First seen · 180 lines · 1,682 tokens per session scan A 791e272d9f1d
ductor GEMINI.md is an instructions file published in the GitHub repository PleasePrompto/ductor (454 stars, last pushed 1mo ago), licensed MIT. It adds 1,682 tokens to every session, about $0.0084 per session on Opus 5. A static security scan graded it A with 0 findings. It is 86% identical to ductor AGENTS.md, differing in 16 lines, and is treated as a copy.
Other instructions, from other repositories
wisp-science AGENTS.md
AGENTS.md instructions for xuzhougeng/wisp-science, covering agents.md, project orientation, repository layout, engineering rules and verification commands.
ai-agents security.instructions.md
Instructions for rjmurillo/ai-agents, covering security file rules, must, should, must not and references.
Cerebro AGENTS.md
Instructions for AgenticFirst/Cerebro, covering cerebro — agent context, read before touching integrations, project layout, conventions a fresh agent would otherwise miss and running locally.
discoclaw CLAUDE.md
Instructions for DiscoClaw/discoclaw, covering discoclaw, safety, context loading (strict), identity and workspace file ownership.
nextjs-skills CLAUDE.md
Instructions for mohamed-hossam1/nextjs-skills: All contribution rules — style, naming, file layout, verification — live in AGENTS.md. Read that first.
coworker CLAUDE.md
Instructions for Array-Ventures/coworker: This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.