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/agents-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/agents-md)<a href="https://agentmods.dev/instructions/pleaseprompto/ductor/agents-md"><img src="https://agentmods.dev/badge/instructions/pleaseprompto/ductor/agents-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 | $0.01656 | $0.01656 |
| Opus 5 | $0.00828 | $0.00828 |
| Sonnet 5 | $0.00331 | $0.00331 |
| Haiku 4.5 | $0.00166 | $0.00166 |
Grade A, and why
ductor AGENTS.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 5d 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.
Copies of this mod
2 near-identical copies found in the catalogue:
- ductor CLAUDE.md — 89% identical, 15 lines differ
- ductor GEMINI.md — 86% identical, 16 lines differ
How it starts
The opening of the file, as written. The whole thing — 182 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, grok).
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/, security/, text/ |
shared file/path safety, 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.
- 5d ago First seen · 182 lines · 1,656 tokens per session scan A 2398e0c0d303
ductor AGENTS.md is an instructions file published in the GitHub repository PleasePrompto/ductor (454 stars, last pushed 1mo ago), licensed MIT. It adds 1,656 tokens to every session, about $0.0083 per session on Opus 5. A static security scan graded it A with 0 findings. No closer match exists in the catalogue, so it is treated as the original; first seen 2026-08-30.
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.
claude-plugins CLAUDE.md
Claude Code instructions for aiocean/claude-plugins, covering claude.md, what this is, plugin structure, marketplace registry and plugin categories.
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.