duckbugio/flock

duckbugio/flock has 495 GitHub stars and 6 forks. GitHot measured +1 stars in 24 hours. Last checked 2026-11-10 04:39 UTC. Last push 2026-10-26.

So werden diese Zahlen gemessen

Autonomous AI dev-team bot

495 Sterne 6 forks +1 in 24h

What you can do

The conversation is the task source — describe what you want in chat and review the PR that comes back; the agent's shell and editor are sandboxed inside the container.
A real dev-team pipeline, not a single prompt — spec-first acceptance criteria, build/regression gates, and an arbiter that breaks loops.
Autonomy loops — the bot verifies its own "done" by re-running the repo's check gate itself; /goal arms an independent evaluator that loops the team until your criterion actually holds; /schedule runs recurring jobs; an optional CI watch reacts to red builds (and can auto-merge green PRs) — all under a per-chat daily autonomy budget. See Autonomy loops.
Multi-transport — Telegram, VK and a text-first LO adapter on the same core; a new platform is a thin adapter, not a fork.

Gemessener Sternzuwachs

in 24h: +1
in 7 days: Aktualisierung verzögert
in 15 days: Aktualisierung verzögert
in 1 month: Aktualisierung verzögert

Nettoänderungen in überlappenden Zeiträumen, keine Tagessummen. Fehlende Messwerte bleiben leer. Sterne zeigen Interesse, nicht Qualität.

README.de.md

Original

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

Flock

Betreibe ein Claude Code KI-Entwicklungsteam auf deinem Server und steuere es per Chat. Beschreibe ein Feature in Telegram oder VK; das Team plant es, baut es auf einem Branch, testet es, prüft es und öffnet einen PR — jeder Chat in seinem eigenen isolierten Workspace.

Es läuft über dein Claude-Pro/Max-Abonnement (keine Abrechnung pro Token) oder einen Anthropic-API-Key, wird als vorgefertigte Docker-Images ausgeliefert (kein Build-Schritt) und hält jeden Chat in seinem eigenen sandboxed Workspace.

Schnellstart (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

Das zieht das vorgefertigte Image ghcr.io/duckbugio/flock-telegram — kein Build, kein Ansible — schreibe anschließend deinem Bot. Die minimale .env:

Variable	Beschreibung
`TELEGRAM_BOT_TOKEN`	von @BotFather
`TELEGRAM_BOT_USERNAME`	der @username deines Bots (ohne `@`)
`ALLOWED_USERS`	kommagetrennte Telegram-Benutzer-IDs, die den Bot verwenden dürfen
`CLAUDE_CODE_OAUTH_TOKEN`	`claude setup-token` (Abonnement) — oder setze `ANTHROPIC_API_KEY`

Alles Übrige in .env.example hat sinnvolle Standardwerte. Aktualisiere es später mit docker compose pull && docker compose up -d.

Telegram-Sekretärmodus

Aktiviere den Modus für den Bot in @BotFather und wähle die zugänglichen privaten Chats in Telegram. Der Kontoinhaber muss in ALLOWED_USERS eingetragen sein. SECRETARY_MODE=approval sendet dem Kontoinhaber einen Entwurf mit Senden/Verwerfen; SECRETARY_MODE=auto antwortet sofort. Für Antworten nutzt der Bot den separat gewählten KI-Anbieter und dessen Modell (AI_BACKEND); Telegram wählt kein eigenes KI-Modell. Mit Claude nutzt der Sekretär den vollständigen Flock-Agenten mit Werkzeugen, MCP und einem dauerhaften Verlauf pro Business-Chat. Setze vor automatischen Antworten ein Ausgabenlimit beim Anbieter. Weitere Einzelheiten auf Englisch.

Der Sekretärmodus unterstützt derzeit nur AI_BACKEND=claude; mit anderen Anbietern bleibt der Bot online, verarbeitet aber keine Business-Nachrichten.

Gewähre nur vertrauenswürdigen Chats Zugriff auf Flocks Werkzeuge und MCP. Die Freigabe betrifft nur die gesendete Antwort: Werkzeugaktionen können schon vor deiner Freigabe stattfinden und lassen sich durch Abbruch nicht rückgängig machen.

Region: Hoste in einer von Anthropic unterstützten Region (einige Länder, z. B. RU/CN, sind geoblockt) — andernfalls schlagen Claude-Aufrufe fehl.

VK folgt demselben Muster unter adapters/vk/, auf demselben Core aufgebaut und veröffentlicht als ghcr.io/duckbugio/flock-vk. Es liefert nur ein Env-Template (keine Compose-Datei): cp .env.example .env, dann docker run --env-file .env ghcr.io/duckbugio/flock-vk. Die Claude-Authentifizierung und die Core-Einstellungen sind identisch mit Telegram; nur die drei Transport-Variablen ändern sich:

Variable	Beschreibung
`VK_BOT_TOKEN`	Community-Access-Token (VK-Community → Verwalten → API-Nutzung → Access-Token)
`VK_GROUP_ID`	die numerische ID deiner Community (Long-Poll-Server + Mention-Parsing)
`VK_ALLOWED_USERS`	kommagetrennte VK-Benutzer-IDs, die den Bot verwenden dürfen

Höhepunkte

Die Konversation ist die Aufgabenquelle — beschreibe im Chat, was du willst, und prüfe den PR, der zurückkommt; Shell und Editor des Agenten sind innerhalb des Containers sandboxed.
Eine echte Entwicklungsteam-Pipeline, kein einzelner Prompt — Spec-First-Akzeptanzkriterien, Build- und Regressions-Gates und ein Arbiter, der Schleifen durchbricht.
Multi-Transport — heute Telegram und VK, beide auf demselben Core; eine neue Plattform ist ein schlanker Adapter, kein Fork.
PR-Reaktionen ohne eingehende Webhooks — der Bot pollt deinen Git-Host nach neuen Review-Kommentaren und leitet jeden zurück an den Chat, der den PR geöffnet hat.
Abo-freundlich — authentifiziere dich mit einem Claude-Pro/Max-Token (keine Kosten pro Token) oder einem Anthropic-API-Key.

Wie es funktioniert

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

Die fünf Subagenten — planner → coder → tester → reviewer → arbiter — laufen als native Claude Code-Subagenten in core/agents/. Eine einfache Frage wird schlicht beantwortet; eine Build-Anfrage löst das Team aus. Der Arbiter ist der risikobewusste, mit Zyklusgrenze versehene Schleifenbrecher, damit Agenten sich niemals endlos drehen. Branches werden duck/<chatid>/<slug> benannt, sodass PR-Webhook-/Poll-Ereignisse zurück an den richtigen Chat geleitet werden.

Das Team ist für einen Microservices-Workspace ausgelegt: Ein Feature kann sich über mehrere Services erstrecken, und es koordiniert Branches sowie einen quervernetzten PR pro Repo. Die vollständige Pipeline, die Leitplanken und die Rollentabelle findest du in core/README.md.

Repo-Aufbau (Monorepo)

Das plattformunabhängige Gehirn des Entwicklungsteams liegt in core/; jede Plattform ist ein schlanker Adapter unter adapters/<name>/, der es sich teilt.

Adapter	Pfad	Vorgefertigtes Image
Telegram	`adapters/telegram/`	`ghcr.io/duckbugio/flock-telegram`
VK	`adapters/vk/`	`ghcr.io/duckbugio/flock-vk`

Künftige Plattformen nutzen denselben Core wieder — siehe docs/multi-transport-plan.md.

Einen Git-Host anbinden (optional, aber zentral)

Setze diese Werte in .env, damit das Team Repos klonen und PRs öffnen kann (funktioniert mit 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

Für github.com setze zusätzlich GH_TOKEN (= dein GIT_TOKEN), damit die gh-CLI PRs öffnen kann.

Der Poller ist die empfohlene Methode, um auf Review-Kommentare zu reagieren — er greift nach außen, sodass er sogar funktioniert, wenn dein Host den Bot nicht erreichen kann. Er ist aktiv, wenn ENABLE_PR_REVIEW=true gesetzt und GITEA_API_URL konfiguriert ist. Eine Alternative mit eingehendem Webhook plus Caddy-TLS-Proxy ist nur über das Ansible-Deployment verfügbar (setze webhook_domain).

Weitere Optionen

Sprachnachrichten: ENABLE_VOICE_MESSAGES=true, VOICE_PROVIDER=mistral|openai|local, plus MISTRAL_API_KEY (oder OPENAI_API_KEY). Werden transkribiert und als Befehle ausgeführt.
dind-Sidecar: docker compose --profile dind up -d stellt dem Team dockerisierte Linter/Tests bereit (setze DOCKER_HOST=tcp://dind:2375).
Isolation pro Chat: Jeder Chat erhält /workspace/chat_<id> (1:1 → privat; Gruppe → ein gemeinsamer Workspace); Chats sind vollständig isoliert und laufen parallel, begrenzt durch MAX_CONCURRENT_CHAT_RUNS. Setze in Gruppen REQUIRE_GROUP_MENTION=true, damit der Bot nur antwortet, wenn er per @mention erwähnt wird oder auf ihn geantwortet wird.
Ansible-Deployment (Telegram): Ein-Befehl-VPS-Provisionierung aus adapters/telegram/deploy — kopiere inventories/example in dein eigenes inventories/<name>/ (gitignored), fülle Inventory/Vars/Vault aus, dann ansible-playbook -i inventories/<name>/inventory.ini playbook.yml. Die Rolle zieht das vorgefertigte Image; setze bot_image, um einen Tag festzuhalten.

Sicherheit

Whitelist: Nur ALLOWED_USERS (Telegram) / VK_ALLOWED_USERS (VK) dürfen den Bot verwenden — lass sie niemals leer; sie gewährt Shell-/Edit-Zugriff auf deinen Server.
Isolation pro Chat: Verschiedene Chats erhalten separate Workspaces. Das Git-Token wird über ein Deployment hinweg geteilt — scope es entsprechend.
Secrets: Bewahre sie in .env (gitignored) auf oder, bei Ansible, in der vault.yml einer echten Instanz (gitignored, mit ansible-vault verschlüsselbar). Nur inventories/example/ wird versioniert.
Sandbox: Der Agent läuft als Non-Root-Benutzer; sein Bash/Edit ist auf den Container beschränkt, nicht auf deinen Host.

Build, Lint, Test

Das Repo verwendet Task als CI-Runner — denselben Einstiegspunkt, den die CI nutzt:

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

Lizenz

MIT © DuckBug.

Mitwirken & Sicherheit

Leitfäden zum Mitwirken und zur Meldung von Sicherheitslücken: CONTRIBUTING.md, CODE_OF_CONDUCT.md, SECURITY.md.