duckbugio/flock

Flock – AI‑driven software‑development team you can chat with

What it is – Flock is a self‑contained service that lets you run a Claude‑Code powered development team on your own server. You interact with the team through a chat app (Telegram, VK, or a simple text‑only “LO” interface). From a single message you can ask the AI to plan, code, test, review and open a pull‑request for a new feature. Each chat gets its own isolated workspace and Git branch, so multiple users can run independent projects side‑by‑side.

Why it matters – Most AI‑code assistants are single‑prompt tools that hand you back a snippet. Flock builds a full dev‑pipeline (planner → coder → tester → reviewer → arbiter) that runs inside Docker, talks to your Git host, and can even watch CI and auto‑merge when everything passes. All of this runs on your own hardware and only needs a Claude Pro/Max subscription (or an Anthropic API key), avoiding per‑token costs.

Key features (as described in the README)

Feature	What it does
Chat‑driven specs	Write a feature description in a chat; the AI team turns it into a concrete plan and code.
Full CI pipeline	The team creates a branch, runs your repo’s test/check commands, opens a PR, and can auto‑merge green builds.
Autonomy loops	Optional loops let the bot verify its own work, re‑evaluate goals (`/goal`), run scheduled jobs (`/schedule`), and watch CI status (`ENABLE_CI_WATCH`).
Multi‑platform adapters	Ready‑to‑run Docker images for Telegram and VK; a lightweight “LO” adapter for any text‑only channel.
Per‑chat isolation	Each chat gets its own workspace directory and branch (`duck/<chatid>/<slug>`), preventing cross‑talk and allowing parallel runs.
Git host integration	Works with GitHub, GitLab or Gitea via PAT; the bot can poll for PR review comments and route them back to the originating chat.
Optional voice commands	Voice messages can be transcribed (Mistral, OpenAI or local) and treated as chat commands.
Docker‑only deployment	Pre‑built images (`ghcr.io/duckbugio/flock-telegram`, `flock-vk`) mean no compilation or Ansible required for a quick start.
Safety controls	Cost caps per chat, an “arbiter” sub‑agent that breaks endless loops, and strict allow‑list of users.

Quick start (Telegram example)

# clone repo and go to the Telegram adapter
git clone https://github.com/duckbugio/flock
cd flock/adapters/telegram

# copy the example env file and fill in the four required values
cp .env.example .env   # edit .env → set BOT_TOKEN, BOT_USERNAME, ALLOWED_USERS, CLAUDE_CODE_OAUTH_TOKEN (or ANTHROPIC_API_KEY)

# start the container (Docker Compose pulls the pre‑built image)
docker compose up -d

After the container is running, send a message to the bot on Telegram and watch it create a branch, run tests, and open a PR.

How it works internally (high‑level)

User message – you describe a feature.
Lead Claude – acts as the planner, confirms scope.
Sub‑agents – planner → coder → tester → reviewer → arbiter are Claude‑Code sub‑agents defined in core/agents/.
Branch & PR – code is committed to a branch named duck/<chatid>/<slug> and a PR is opened on the configured Git host.
Feedback loop – reviewer comments are polled back into the chat; the arbiter can approve, request changes, or abort.
Autonomy options – post‑run verification, goal evaluation, scheduled jobs, CI watch, and optional auto‑merge can be toggled via environment variables.

Typical use cases

Feature development – a product manager can describe a new endpoint in chat and receive a fully tested PR.
Bug fixing – paste a bug description; the AI team creates a fix, runs the repo’s test suite, and opens a PR.
Hands‑off CI monitoring – enable CI watch so the bot notifies the chat when a build fails or succeeds, optionally auto‑merging green PRs.
Scheduled maintenance – use /schedule to run recurring linting, dependency upgrades, or other routine tasks.

Installation & operation notes

Prerequisites – Docker Compose, a Claude Pro/Max token (or Anthropic API key), and a Git host PAT with write access.
Supported transports – Telegram (pre‑built image), VK (pre‑built image), and a generic “LO” adapter that you can build locally.
Environment configuration – most settings live in .env; required keys are listed in the README tables. Optional features are toggled with ENABLE_* flags.
Security – only users listed in ALLOWED_USERS (or the VK equivalent) can invoke the bot; the agent runs as a non‑root user inside the container and is sandboxed to its workspace directory.
Extensibility – adding a new chat platform only requires a thin adapter that re‑uses the core agents; the repo includes a design doc (docs/multi-transport-plan.md).

License & contribution

License: MIT (see LICENSE).
Contributing: Follow the standard fork‑branch‑PR workflow; the repo provides a Taskfile for linting, testing and building (task lint, task tests, task build).
Security disclosures: Private reporting via SECURITY.md.

Bottom line: Flock turns a Claude‑Code subscription into a fully automated, chat‑driven development team that can plan, code, test, review and merge features on your own server, with strong isolation and optional autonomy controls.