flock: a Claude dev team in a container, where approval gates the reply and not the tools

approval mode gates the reply, not the tool actions behind it

Telegram Secretary Mode lets the bot receive messages from selected private chats and reply on your behalf. It has three settings. Off is the default. Approval sends you an AI draft in a private chat with the bot and you choose Send or Discard. Auto sends the draft automatically.

The limitation is stated in the same paragraph and deserves to be quoted rather than paraphrased: in approval mode the owner approves the outgoing Telegram reply, while agent tool actions happen during drafting and are not deferred by that approval.

Two consequences follow. A Business message can trigger tool actions before you approve its reply, so the Send button is not a gate on side effects. And cancelling a run cannot undo completed actions. The guidance that follows is therefore about access rather than about approval: grant access only to people you trust with Flock's normal tools and MCP.

That is a coherent position, since a drafting step that could not touch anything would not be a drafting step. But it inverts the intuition most people carry about an approve button, and the pairing of that mode with chat access control is where the risk concentrates.

The mitigation offered is on the cost side rather than the permission side: set a spending limit with your provider before enabling automatic replies. The bot caps requests per minute and applies its configured cost cap to Business runs.

A VK adapter ships alongside an explicit note that Russia is geo-blocked

There is a region requirement, and it is a hard one. The host has to be in an Anthropic-supported region; some countries are named as geo-blocked, and Russia and China are the two given. Where the block applies, Claude calls fail.

That sits in an awkward position on this page, because one of the three supported transports is VK, a Russian platform, and the VK section immediately follows the region note. The adapter is built on the same core as Telegram and published as its own image, so it works; what does not work is calling Claude from inside the region it is most likely to be deployed in.

The VK integration itself is minimal. Three transport variables: a community access token, the community's numeric id, and an allow-list of user IDs. The numeric id serves both the long-poll server and mention parsing, which tells you the adapter is built around long polling and reply-to-mention rather than a webhook.

Delivery differs from Telegram here in a way that costs the user a step. The Telegram adapter ships with a compose file. The VK adapter ships only an environment template, so there is no compose file to run, and the documented start is a bare `docker run` against the published image with an env file. Same core, same image pattern, less scaffolding.

One more constraint carries over: the Telegram account owner must be listed in the allow-list, and on VK the equivalent is the community allow-list.

The bot reads its own approval drafts from secretary-state.json

State has a documented home and a documented reader. Approval draft replies and routing metadata are stored in a file called `secretary-state.json`, under a directory set by an environment variable, and the documentation notes that the coding agent can read it.

That is stated as a fact rather than as a hazard, and in a system where the agent is the thing that has to resume a conversation it is close to unavoidable. Each Business chat resumes its earlier conversation, so some persistent record has to exist. The choice of a plain file under a configurable directory keeps it inspectable, and it means the state can be read from outside the running container.

The lifecycle rules around that state are more specific than the storage. Edited or deleted messages cancel unsent approval drafts, and the bot does not generate a replacement reply for an edit. Approval buttons expire after twenty-four hours, and Telegram may reject a reply earlier than that if its own business reply window has closed.

So there are three independent ways a pending approval dies: the sender edits, the sender deletes, or the window closes. Only the first two are under the user's control, and none of them produces a follow-up draft.

Business workspaces default to a separate directory and are supposed to be mounted persistently, with the documentation noting that the separate directory reduces accidental cross-chat access but is not a security boundary for an agent with shell tools. That sentence is the honest one to keep in mind before granting chat access.

Three adapters, three different ways to install them

The three transports are described as sitting on one core, with a new platform framed as a thin adapter rather than a fork. That is the right architecture claim. The installation experience is where the three diverge most.

Telegram is the reference path and the only one with a compose file:

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

That pulls a prebuilt image with no build step and no orchestration tooling involved, and updating is two commands.

VK ships an environment template only, and starts with a plain `docker run` and an env file. LO, described as a text-first adapter, has its own adapter directory with its own readme and a separate compatibility audit document listing supported commands, optional streaming and platform gaps.

What LO adds is worth noting separately. Its entry point supports interrupted-run recovery, an optional CI watch, and Gitea pull request comment polling restricted to its own checked-out branches. Voice input uses the shared transcription providers when enabled.

So the platform with the least complete installer has the most distinctive features, and the one with a compose file is the plainest. That is not a criticism so much as a reminder that the transports are genuinely thin rather than one product with three skins.

go.mod lists two direct dependencies, and neither of them is for VK

The Go module manifest is short enough to take in at a glance. The module path is the repository. The Go directive pins a full three-part version. Then two require blocks: a primary one with two modules and a secondary one with a single entry.

The two direct dependencies are an environment variable parser and a Telegram bot library. The secondary entry is a synchronisation package from the standard extended library.

What is notable is what is absent. There is no VK library, no HTTP client dependency, no database driver, no web framework, no queue broker and no orchestration client, in a project that stores state in files, exposes per-chat workspaces, runs scheduled jobs and polls a git host. For a service of this description, two direct dependencies means most of that is built on the standard library, which is a defensible choice and a real constraint on how much of it could be replaced.

The Telegram library's presence does confirm that the reference adapter uses a maintained client rather than hand-rolled long polling, which means the VK adapter is doing its transport work without an equivalent library, or reusing something the Telegram one already provides.

The version directive is also written as a full patch release rather than a language version, which pins toolchain selection more tightly than the usual form.

The bot verifies its own done, and a second evaluator loops the team

The autonomy features are the most interesting part of the design, and there are four distinct mechanisms rather than one.

Self-verification comes first: the bot checks its own claim of completion by re-running the repository's check gate itself. It does not take an agent's word for done.

Then there is a goal command that arms an independent evaluator, which loops the team until the stated criterion actually holds. That is a second opinion inside the run rather than the same agent grading itself, and it is the mechanism that makes a criterion like a passing gate enforceable.

A schedule command runs recurring jobs, and an optional CI watch reacts to red builds and can auto-merge green pull requests. All of it runs under a per-chat daily autonomy budget.

The pipeline itself is drawn out as a sequence rather than described: a lead bot hands to a planner, the planner confirms scope, a coder and a tester work back and forth, a pull request goes out per repository, a reviewer attaches inline comments, the coder responds, and an arbiter settles it and can approve.

An arbiter that breaks loops is the piece that makes the rest safe to leave running unattended. A coder and tester that disagree indefinitely is the failure mode a multi-agent pipeline actually hits, and naming the component that resolves it is more informative than any claim about autonomy.

Pull request reactions work by polling the git host

Review comments are handled without inbound webhooks. The bot polls the git host for new review comments and routes each one back to the chat that opened the pull request.

Polling instead of webhooks is a deliberate trade, and it is the kind of decision that only makes sense for a self-hosted deployment. Inbound webhooks need a public address, a certificate and an endpoint someone is willing to expose. Polling needs an outbound connection the container already has, which is also the connection it needs for Claude itself. A tool that runs on a laptop or a home server cannot usually take a webhook, so polling is what makes the feature available at all in that setting.

The cost is latency and request volume. Every comment arrives on a poll interval rather than immediately, and the cost falls on the host's rate limits rather than on an inbound allowance, since the traffic is outbound. The LO adapter adds a related capability with its own restriction, polling Gitea pull request comment threads limited to branches it has itself checked out.

The routing is the part worth noticing. Comments are not delivered to a general channel; each one goes back to the chat that opened the pull request. Combined with one workspace per chat, that means the conversation that asked for the work is the conversation that sees the review outcome, with no routing table to configure.

Three agent instruction files and a Taskfile in a Go repository

The root of the repository carries three agent instruction files rather than one: a general agents file, a Claude file and a Gemini file. That is a deliberate accommodation, since the project is built on Claude Code but is distributed as a generic autonomous dev team, and each of those agents looks for instructions under its own convention.

Task orchestration goes through a Taskfile rather than a Makefile, which is the Go community's usual choice and avoids a second build tool in a project that already ships one. Linting is configured for the Go ecosystem through a golangci configuration file.

The directory layout follows the standard Go split, with a command directory, an internal package directory, a core package and an adapters directory holding one subdirectory per transport, plus separate tools and documentation directories.

The readme itself is translated into seven other languages alongside English, covering Russian, Chinese, Spanish, German, French, Brazilian Portuguese and Japanese. The Russian and Chinese translations are consistent with the audience the VK adapter and the region note point at, even though that region note also describes both as geo-blocked.

There are no tagged releases at all. The last push to the default branch is dated 2026-09-30, so the project is being worked on, and the delivery model is a container image rather than a versioned binary.

Editorial conclusion

flock is for someone who wants a development team running on their own hardware and reaches it from a chat app rather than an editor, and the pipeline it describes, lead, planner, coder, tester, reviewer and an arbiter that breaks loops, is more than a single prompt in a wrapper. Two things to read closely before enabling it. Approval mode gates the outgoing message and not the tool actions behind it, so a Business chat can change files before anyone approves the reply, and the separate workspace directory is stated not to be a security boundary for an agent with shell tools. And check your region first, because the same page that ships a VK adapter names Russia and China as geo-blocked.

Frequently asked questions

Official sources

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