duckbugio/flock: a self-hosted Claude Code dev team you drive from Telegram or VK

What flock solves, and who it is actually for

The project's own framing is that the conversation is the task source. You describe a feature in a chat, and the bot returns a pull request. That is a narrower promise than a general coding assistant, and it is the reason the design looks the way it does.

The intended user is a small team running several services that need to change together. The README states the team is built for a microservices workspace, where a feature can span several services and the bot coordinates branches and one cross-linked PR per repo. A single-repo, single-service project gets much less out of it, because the cross-linking is where the coordination cost lives.

The second half of the audience is operational. Flock is self-hosted, ships as prebuilt Docker images, and can authenticate with a Claude Pro/Max subscription token instead of per-token API billing. For a team that already pays for Claude and does not want a second metered bill, that is the deciding constraint.

What it is not: a chat wrapper around a single prompt. The README is explicit that a plain question is just answered, while a build request triggers the team. That distinction matters, because it means the bot is doing routing before it does work.

The planner, coder, tester, reviewer and arbiter pipeline

Flock runs five subagents: planner, coder, tester, reviewer and arbiter. The README describes them as native Claude Code subagents living in core/agents/, and gives the flow as planner, then scope confirmation, then coder and tester in a loop, then a reviewer leaving inline comments back to the coder, then the arbiter.

The arbiter is the interesting part. It is described as a risk-aware, cycle-limited loop-breaker so agents never spin forever, and it has two exits: APPROVE, after which you merge, or ESCALATE, which asks you. Any multi-agent pipeline needs a terminator, and making the terminator a separate role rather than a turn counter is a design choice worth noting. It also means the failure mode is a question to a human rather than a silent stop.

Routing is handled by branch naming. Branches are named duck/<chatid>/<slug>, and the README states this is how PR-webhook or poll events find their way back to the right chat. That is a simple mechanism with a real consequence: the chat id is embedded in the branch name, so anything that rewrites branch names breaks the return path.

Each chat also gets its own isolated workspace, and the README says the agent's shell and editor are sandboxed inside the container. Isolation is per chat, not per user, which is the right unit here since the chat is the task source.

Installing flock with Docker and sending a first request

The README's quick start is four commands. It clones the repository, moves into the Telegram adapter directory, copies the environment template, and starts the compose stack. The compose file pulls the prebuilt image ghcr.io/duckbugio/flock-telegram, so there is no build step and no Ansible.

git clone https://github.com/duckbugio/flock
cd flock/adapters/telegram
cp .env.example .env
docker compose up -d

Before starting it, the .env file needs four values. The README calls this the REQUIRED block and lists TELEGRAM_BOT_TOKEN from @BotFather, TELEGRAM_BOT_USERNAME without the @, ALLOWED_USERS as comma-separated Telegram user IDs, and CLAUDE_CODE_OAUTH_TOKEN from claude setup-token. The alternative to the token is setting ANTHROPIC_API_KEY instead. Everything else in .env.example has defaults.

claude setup-token

Once the container is up, you message the bot. A plain question gets an answer; a build request starts the team. The README's own example request is to implement a feature across the api and web services, which is the shape the pipeline expects.

Upgrades are a pull and a restart, and the README gives the exact pair.

docker compose pull && docker compose up -d

The VK adapter follows the same pattern under adapters/vk/ but ships only an environment template, no compose file, so the documented start is a docker run with an env file.

docker run --env-file .env ghcr.io/duckbugio/flock-vk

Its transport variables are VK_BOT_TOKEN, VK_GROUP_ID and VK_ALLOWED_USERS. The LO adapter is text-first, published as ghcr.io/duckbugio/flock-lo, and started using adapters/lo/; the README points to docs/lo-telegram-compatibility.md for supported commands and platform gaps rather than listing them inline.

The four autonomy loops and their hard stops

Flock's most distinctive feature is that it does not trust its own completion message. Post-run verification is on by default via ENABLE_POST_VERIFY. After a run reports done, the bot re-runs the changed repos' own check gate (the README names task, make, npm check, test and lint as the kinds of gates it looks for) and, on a red result, sends the team back with the real failure output, up to POST_VERIFY_MAX_FIXES consecutive rounds. The README's phrasing is that the agent's "tests pass" is verified, not trusted.

That is a strong claim and it carries a strong dependency: your repos must expose a check gate the bot can discover and run. If a service has no task, make or npm check target, post-run verification has nothing to call, and the safety net is effectively absent for that repo.

/goal is the second loop. You arm a criterion such as /goal all list views paginate correctly, and after every completed run an independent, fresh-session judge with no shared context inspects the workspace, re-runs checks and returns a strict verdict. Unmet points are injected back as a fix-up; a met goal is marked and disarmed. GOAL_MAX_ATTEMPTS bounds the loop and EVALUATOR_MODEL can point the judge at a cheaper model, which is a sensible cost lever since the judge runs repeatedly.

/schedule adds durable per-chat recurring prompts with per-chat timezones, fired as normal team runs and gated at fire time by the creator's allow-list status and cost cap. CI watch, enabled by ENABLE_CI_WATCH, polls CI state on the duck/* branches using GitHub check-runs or Gitea commit status and can react to red builds. The README also notes it can auto-merge green PRs, which is the one loop I would treat with real caution: a green build is not the same as a correct change, and the README does not describe a separate review gate on the auto-merge path. All of this sits under a per-chat daily autonomy budget.

Region blocking, missing gates and other cases where flock is the wrong tool

The README carries a region warning in its own quick start: host in an Anthropic-supported region, because some countries, including RU and CN, are geo-blocked, and otherwise Claude calls fail. This is not a configuration nuance. If you are in a blocked region, the project does not work at all, and no amount of local setup fixes it. Self-hosting does not buy you independence from the model provider here.

The second limitation is the check gate dependency described above. Post-run verification and the /goal evaluator both lean on re-running checks. In a repo with no meaningful test or lint target, both loops degrade into re-reading the diff, and the value proposition weakens considerably.

The third is the polling model. The README advertises PR reactions without inbound webhooks by polling your git host for new review comments. Polling means latency between a review comment and the bot's response, and it means the git host must be one the bot knows how to poll. The README names GitHub check-runs and Gitea commit status in the CI watch context, so those are the hosts the documentation supports; anything else is unconfirmed.

Finally, per-chat isolation is not per-user isolation. Anyone on the allow-list in a given chat shares that chat's workspace and its autonomy budget. For a team chat that is the intended behaviour, but it means the allow-list is the real security boundary, and ALLOWED_USERS deserves more thought than a comma-separated list usually gets.

How flock differs from running Claude Code by hand

The obvious alternative is Claude Code itself, used directly in a terminal. The difference is not capability, since Flock runs Claude Code subagents underneath. The difference is where state and coordination live.

Running Claude Code by hand, you are the router. You decide which repo to open, you hold the cross-service context in your head, and you notice when a change in one service breaks another. Flock moves that into the pipeline: the planner confirms scope, the branches are named and cross-linked per repo, and the arbiter decides when to stop. In exchange you give up the immediacy of a terminal session and accept a chat interface as the control surface.

The second difference is verification. A hand-run Claude Code session reports that tests pass and you either believe it or check. Flock's default post-run verification re-runs the gate and feeds failures back. That is a genuine structural difference, not a prompt difference, and it is the strongest argument for the project.

The third is cost model. Flock is built to run on a Claude Pro/Max subscription via CLAUDE_CODE_OAUTH_TOKEN, with an Anthropic API key as the alternative. A hosted agent product bills you per token or per seat by design. If you already hold the subscription, the self-hosted route changes what a long autonomous run costs you.

Licence, maintenance and what an upgrade actually costs

Flock is MIT licensed, which is permissive: you can use, modify and redistribute it, including in commercial settings, provided the copyright notice and permission notice are preserved. That is the standard MIT obligation and it is worth reading in the LICENSE file rather than taking my summary as complete. Nothing in the README suggests any additional restriction, and there is no separate enterprise tier mentioned.

On maintenance, the repository is not archived and the last push was on 2026-09-15, so the codebase is being touched. No releases were retrieved, so there is no published version history to reason about, and the README's upgrade instruction is a container pull rather than a versioned migration.

The practical upgrade cost follows from the Docker-first design. Because you run ghcr.io/duckbugio/flock-telegram, flock-vk or flock-lo and update with docker compose pull && docker compose up -d, you inherit whatever the image tag resolves to. The README does not document rollback, and it does not describe pinned version tags. If you need reproducible deployments, that is a gap to resolve yourself, either by pinning image digests or by tracking the repository directly.

Configuration drift is the other cost. The Telegram adapter's .env.example is the documented reference for environment keys, and the README notes that everything outside the required block has sensible defaults. Upgrades that add or rename keys will show up there first.

Editorial conclusion

Flock fits teams that already run a microservices repo, hold a Claude Pro/Max subscription or API key, and can host in an Anthropic-supported region, because the Docker path needs only four environment values and no build step. It does not fit anyone geo-blocked from Anthropic, anyone without a git host the bot can poll for review comments, or anyone who wants a hosted service with an SLA. Before adopting it, check that your repos expose a check gate the post-run verifier can call (task, make, npm check, test or lint), confirm the git host you poll is one the bot supports, and decide whether the per-chat daily autonomy budget defaults match your tolerance for unattended runs.

Frequently asked questions

Official sources

1. duckbugio/flock on GitHub
2. Issues
3. License: MIT
4. Project website
5. README