English · Русский · 中文 · Español · Deutsch · Français · Português (BR) · 日本語

Flock

Faites tourner une équipe de développement IA Claude Code sur votre serveur et pilotez-la depuis une conversation. Décrivez une fonctionnalité sur Telegram ou VK ; l'équipe la planifie, la développe sur une branche, la teste, la relit et ouvre une PR — chaque conversation dans son propre espace de travail isolé.

Elle fonctionne avec votre abonnement Claude Pro/Max (sans facturation au token) ou une clé API Anthropic, est livrée sous forme d'images Docker pré-construites (aucune étape de build) et conserve chaque conversation dans son propre espace de travail cloisonné.

Démarrage rapide (Docker)

git clone https://github.com/duckbugio/flock
cd flock/adapters/telegram
cp .env.example .env        # fill in the REQUIRED block (4 values)
docker compose up -d

Cela récupère l'image pré-construite ghcr.io/duckbugio/flock-telegram — aucun build, aucun Ansible — puis envoyez un message à votre bot. Le .env minimal :

Variable	Description
TELEGRAM_BOT_TOKEN	depuis @BotFather
TELEGRAM_BOT_USERNAME	le @username de votre bot (sans @)
ALLOWED_USERS	identifiants d'utilisateurs Telegram séparés par des virgules, autorisés à utiliser le bot
CLAUDE_CODE_OAUTH_TOKEN	claude setup-token (abonnement) — ou définissez ANTHROPIC_API_KEY

Tout le reste dans .env.example a des valeurs par défaut raisonnables. Mettez à jour plus tard avec docker compose pull && docker compose up -d.

Mode secrétaire Telegram

Activez ce mode pour le bot dans @BotFather et choisissez les conversations privées accessibles dans Telegram. Le propriétaire du compte doit figurer dans ALLOWED_USERS. SECRETARY_MODE=approval envoie un brouillon au propriétaire pour validation ou rejet ; SECRETARY_MODE=auto répond immédiatement. Les réponses utilisent le fournisseur et le modèle IA choisis pour le bot (AI_BACKEND) ; Telegram ne sélectionne pas de modèle distinct. Avec Claude, le secrétaire utilise l’agent Flock complet, ses outils, MCP et une session persistante par conversation Business. Fixez une limite de dépenses chez le fournisseur avant d'activer les réponses automatiques. Détails en anglais.

Pour le moment, le mode secrétaire nécessite AI_BACKEND=claude ; avec les autres fournisseurs, le bot reste actif sans traiter les messages Business.

N’accordez l’accès qu’aux conversations dont vous faites confiance aux participants pour utiliser les outils et MCP de Flock. La validation ne contrôle que la réponse envoyée : les outils peuvent agir avant votre validation et l’annulation n’efface pas ces actions.

Région : hébergez dans une région prise en charge par Anthropic (certains pays, par exemple RU/CN, sont bloqués géographiquement) — sinon les appels à Claude échouent.

VK suit le même schéma sous adapters/vk/, construit sur le même cœur et publié sous ghcr.io/duckbugio/flock-vk. Il ne fournit qu'un modèle d'environnement (pas de fichier compose) : cp .env.example .env, puis docker run --env-file .env ghcr.io/duckbugio/flock-vk. L'authentification Claude et les paramètres du cœur sont identiques à ceux de Telegram ; seules les trois variables de transport changent :

Variable	Description
VK_BOT_TOKEN	token d'accès de la communauté (communauté VK → Gérer → Utilisation de l'API → token d'accès)
VK_GROUP_ID	l'identifiant numérique de votre communauté (serveur long-poll + analyse des mentions)
VK_ALLOWED_USERS	identifiants d'utilisateurs VK séparés par des virgules, autorisés à utiliser le bot

Points forts

• La conversation est la source des tâches — décrivez ce que vous voulez dans la conversation et examinez la PR qui revient ; le shell et l'éditeur de l'agent sont cloisonnés à l'intérieur du conteneur.
• Un véritable pipeline d'équipe de développement, pas un simple prompt — critères d'acceptation définis d'abord par la spécification, contrôles de build et de régression, et un arbitre qui rompt les boucles.
• Multi-transport — Telegram et VK aujourd'hui, tous deux sur le même cœur ; une nouvelle plateforme est un adaptateur léger, pas un fork.
• Réactions aux PR sans webhooks entrants — le bot interroge votre hôte git pour détecter les nouveaux commentaires de revue et achemine chacun vers la conversation qui a ouvert la PR.
• Compatible avec les abonnements — authentifiez-vous avec un token Claude Pro/Max (sans coût au token) ou une clé API Anthropic.

Fonctionnement

You (in a chat): "implement X across the api + web services"
  → bot's Claude (Lead) → planner → confirm scope → coder ⇄ tester → PR per repo
                                                      → reviewer (inline comments) ⇄ coder → arbiter
                                                                                        ├ APPROVE → you merge
                                                                                        └ ESCALATE → asks you

Les cinq sous-agents — planner → coder → tester → reviewer → arbiter — s'exécutent comme des sous-agents Claude Code natifs dans core/agents/. Une simple question reçoit simplement une réponse ; une demande de build déclenche l'équipe. L'arbiter est le briseur de boucles conscient du risque et limité en cycles, afin que les agents ne tournent jamais indéfiniment. Les branches sont nommées duck/<chatid>/<slug> de sorte que les événements de webhook/sondage de PR soient routés vers la bonne conversation.

L'équipe est conçue pour un espace de travail en microservices : une fonctionnalité peut s'étendre sur plusieurs services, et elle coordonne les branches ainsi qu'une PR avec liens croisés par dépôt. Le pipeline complet, les garde-fous et le tableau des rôles se trouvent dans core/README.md.

Organisation du dépôt (monorepo)

Le cerveau de l'équipe de développement, agnostique de plateforme, se trouve dans core/ ; chaque plateforme est un adaptateur léger sous adapters/<name>/ qui le partage.

Adaptateur	Chemin	Image pré-construite
Telegram	adapters/telegram/	ghcr.io/duckbugio/flock-telegram
VK	adapters/vk/	ghcr.io/duckbugio/flock-vk

Les futures plateformes réutilisent le même cœur — voir docs/multi-transport-plan.md.

Connecter un hôte git (optionnel mais central)

Définissez ces variables dans .env pour permettre à l'équipe de cloner des dépôts et d'ouvrir des PR (fonctionne avec Gitea/GitHub/GitLab) :

GIT_HOST=git.example.com
GIT_USER=...
GIT_TOKEN=...                 # write-scoped PAT
GIT_AUTHOR_NAME=AI Team
[email protected]
# Poll the host for new PR comments (reliable; no inbound webhook needed):
GITEA_API_URL=https://git.example.com/api/v1
GITEA_POLL_INTERVAL=90

Pour github.com, définissez également GH_TOKEN (= votre GIT_TOKEN) afin que la CLI gh puisse ouvrir des PR.

Le poller est le moyen recommandé pour réagir aux commentaires de revue — il tend la main vers l'extérieur, il fonctionne donc même lorsque votre hôte ne peut pas joindre le bot. Il est actif lorsque ENABLE_PR_REVIEW=true et que GITEA_API_URL est défini. Une alternative par webhook entrant associé à un proxy TLS Caddy n'est disponible qu'au travers du déploiement Ansible (définissez webhook_domain).

Autres options

• Messages vocaux : ENABLE_VOICE_MESSAGES=true, VOICE_PROVIDER=mistral|openai|local, plus MISTRAL_API_KEY (ou OPENAI_API_KEY). Transcrits et exécutés comme des commandes.
• Sidecar dind : docker compose --profile dind up -d fournit à l'équipe des linters/tests dockerisés (définissez DOCKER_HOST=tcp://dind:2375).
• Isolation par conversation : chaque conversation reçoit /workspace/chat_<id> (1:1 → privé ; groupe → un espace de travail partagé) ; les conversations sont totalement isolées et s'exécutent en parallèle, plafonnées par MAX_CONCURRENT_CHAT_RUNS. Dans les groupes, définissez REQUIRE_GROUP_MENTION=true pour ne répondre que lorsque le bot est @mentionné ou cité en réponse.
• Déploiement Ansible (Telegram) : provisionnement d'un VPS en une commande depuis adapters/telegram/deploy — copiez inventories/example vers votre propre inventories/<name>/ (ignoré par git), remplissez inventory/vars/vault, puis ansible-playbook -i inventories/<name>/inventory.ini playbook.yml. Le rôle récupère l'image pré-construite ; définissez bot_image pour épingler un tag.

Sécurité

• Liste blanche : seuls ALLOWED_USERS (Telegram) / VK_ALLOWED_USERS (VK) peuvent utiliser le bot — ne la laissez jamais vide ; elle accorde un accès shell/édition à votre serveur.
• Isolation par conversation : différentes conversations obtiennent des espaces de travail séparés. Le token git est partagé au sein d'un déploiement — limitez sa portée en conséquence.
• Secrets : conservez-les dans .env (ignoré par git) ou, pour Ansible, dans le vault.yml d'une instance réelle (ignoré par git, chiffrable avec ansible-vault). Seul inventories/example/ est suivi.
• Sandbox : l'agent s'exécute en tant qu'utilisateur non-root ; ses commandes Bash/Edit sont confinées au conteneur, pas à votre hôte.

Build, lint, test

Le dépôt utilise Task comme exécuteur de CI — le même point d'entrée que CI :

task lint      # format + vet + linters (in the dev-tools image)
task tests     # Go test suite
task build     # compile the binaries

Licence

MIT © DuckBug.

Contribuer et sécurité

Guides pour contribuer et pour signaler une vulnérabilité : CONTRIBUTING.md, CODE_OF_CONDUCT.md, SECURITY.md.