Flock AI Dev Team
Run a self-hosted Claude Code team that turns chat requests into tested, reviewed pull requests.
Per-dimension scores and reasoning
The material shows a non-root container, per-chat workspaces, user allow-lists, guidance to scope Git tokens, and read-only contents permission in CI. The workflow also describes scope confirmation, risk arbitration, and human PR merging. The README identifies major data flows and effects involving Git-host polling, voice transcription, external model services, branches, and PRs; SECURITY.md covers secret storage and private reporting, while CI runs govulncheck and Trivy. Deductions apply because a deployment-wide write-capable Git token is shared across chats, DinD exposes a TCP Docker service, third-party transport/model data boundaries are not exhaustively documented, and there is no granular confirmation for each consequential action. Recovery relies mainly on unmerged branches, human merging, and immutable SHA image tags, with no stated automatic restoration of changed files, branches, or opened PRs. The MIT attribution and DuckBug organization are clear, but publisher identity is not verified by the supplied evidence.
The README, SECURITY.md, go.mod, and workflows are broadly consistent about container deployment, test entry points, security scanning, and publishing. Dependencies have explicit versions, and the documentation identifies Anthropic regional availability constraints and image-update procedures. Deductions apply because no runtime error-handling implementation, retry policy, timeout behavior, or concrete user-facing diagnostic examples are supplied; failure communication is limited to a regional failure warning and a conceptual arbiter escalation. Availability still depends on external services, rolling latest images, and Claude authentication.
The material identifies operators managing microservice development through Telegram or VK, distinguishes simple questions from build requests, and describes planner, coder, tester, reviewer, and arbiter roles, bounded loops, group-mention controls, concurrency limits, voice providers, and GitHub/GitLab/Gitea environments. Deductions apply because request classification is only summarized rather than formally specified, ambiguity handling is not shown, and most capability boundaries remain documentary. The LO adapter appears in workflows but not in the README support matrix, while guidance for non-Docker deployments, unsupported regions, and additional hosting environments is limited.
The quick start, architecture diagram, repository map, configuration tables, security guidance, build commands, and multilingual navigation form a thorough information architecture. The full MIT text is present and agrees with the metadata, justifying full license credit. Deductions apply because installation depends on unshown environment templates and published images, and VK lacks a Compose file. Examples are present but there is no developed FAQ; limitations are mentioned but not consolidated comprehensively. Publishing supports latest, automatic versions, Git tags, and immutable SHA tags, but no changelog or stability policy is supplied. SECURITY.md sets response expectations, although maintenance is volunteer-driven, email availability is uncertain, and publisher identity remains unverified.
The intended deliverables are reviewable per-repository branches and linked PRs produced through planning, testing, review, and arbitration. Cross-service coordination, review-comment routing, and chat isolation provide plausible marginal value beyond a single coding prompt. Subscription-token and API-key options plus prebuilt images make the operating model reasonably understandable. Deductions apply because the supplied sources contain no output examples, quality measurements, resource-usage figures, latency data, demonstrated concurrency capacity, or total-cost evidence, so superior utility and cost-benefit cannot be established statically.
Major claims point to concrete directories, configuration names, Task commands, and workflows. Security scans, image-build checks, licensing, and release tags receive some corroboration across files, and recommendations or future plans are generally distinguishable from present-tense claims. Deductions apply because the limited source set omits the referenced core documentation, agent prompts, implementation, tests, Taskfile, Dockerfiles, and environment templates. Claims about the complete autonomous pipeline, sandbox isolation, and testing behavior are therefore only partially traceable. CI badges and workflow definitions also do not establish successful execution in this static review.
- The agent has shell and file-edit access inside its container; configure a non-empty user allow-list and restrict the write-capable Git token to the minimum repositories and permissions.
- The deployment-wide Git token is shared across chats, so per-chat workspace isolation does not provide credential or repository-permission isolation.
- Enabling DinD, voice transcription, or PR-comment polling expands interfaces and data flows; review Docker-service exposure and each third-party provider's data handling before deployment.
- Prefer immutable SHA image tags over rolling latest, and establish a manual recovery procedure for agent-created branches, PRs, and workspace changes.
- This assessment did not execute the code, tests, or images and did not inspect referenced implementation and configuration files that were not supplied.
What does this agent do, and when should you use it?
Flock is a self-hosted development bot operated through Telegram, VK, or a text-first LO adapter. Its platform-neutral core lives under core/ and coordinates five native Claude Code subagents: planner, coder, tester, reviewer, and arbiter. Each chat receives an isolated workspace, while build requests move through specification, implementation, testing, review, and pull-request creation across one or more repositories. Optional autonomy features add post-run verification, independent goal evaluation, recurring schedules, and CI monitoring, bounded by retry limits and a per-chat daily budget for autonomous tasks. Deployment uses prebuilt Docker images, and the Claude Code runtime authenticates with either a Claude Pro/Max OAuth token or an Anthropic API key.
A user submits a question or development request through Telegram, VK, or LO. Plain questions are answered directly; build requests are routed through the planner, coder, tester, reviewer, and arbiter definitions in core/agents/. The planner establishes scope and acceptance criteria, the coder edits code on duck/<chatid>/<slug> branches inside an isolated workspace, the tester runs repository checks, the reviewer provides inline feedback, and the coder iterates until the cycle-limited arbiter returns APPROVE or ESCALATE. One task can span multiple microservice repositories and produce a cross-linked PR for each repository. With ENABLE_POST_VERIFY, Flock reruns the changed repositories' task, make, npm check, test, or lint gate; /goal adds a fresh-session evaluator that inspects the workspace and repeats checks independently. /schedule creates durable recurring prompts, while ENABLE_CI_WATCH polls GitHub check-runs or Gitea commit status, triggers repair work on failures, and can merge green PRs when ENABLE_AUTO_MERGE is enabled. Its PR poller reads new review comments from the Git host and routes them back to the chat that created the branch without requiring inbound webhooks.
- A microservices team wants one chat request to coordinate implementation branches and cross-linked pull requests across several repositories.
- Developers working from Telegram, VK, or LO want to delegate coding, testing, and review to infrastructure running on their own server.
- Maintainers want autonomous changes checked against the repository's real build or test gate and independently judged against an explicit
/goalcriterion. - A self-hosted GitHub, GitLab, or Gitea operator cannot expose an inbound webhook and needs outbound polling for pull-request review comments.
- A team wants recurring maintenance runs or automatic repair attempts when CI turns red, with optional automatic merging after a green result.
- An operator serving several private or group chats needs separate workspaces, user allow-lists, and a configurable cap on concurrent chat runs.
What are this agent's strengths and limitations?
- The five-role pipeline combines acceptance criteria, implementation, regression gates, inline review, and an arbiter that terminates unproductive cycles.
- Telegram, VK, and LO share one core while retaining per-chat workspaces and configurable concurrency limits.
- Post-run verification reruns the repository's own checks, while
/goaluses an independent session with no context shared from the working session. - It coordinates branches and PRs across multiple service repositories and can consume review comments through outbound polling instead of an inbound webhook.
- Prebuilt Docker images avoid a local build step, and authentication supports either a Claude Pro/Max subscription token or an Anthropic API key.
- The core team consists of native Claude Code subagents, with no documented replacement path for another model provider.
- Operators must host Docker and grant the agent shell, editor, filesystem, and network access, creating infrastructure and security responsibilities.
- The host must be in an Anthropic-supported region; the documentation warns that geographic blocking causes Claude calls to fail in some countries.
- PR creation requires a write-scoped Git token that is shared across chats in one deployment, so excessive token scope increases exposure.
- CI monitoring, auto-merge, voice transcription, Git-host polling, and Docker-in-Docker each require additional configuration, credentials, or privileges.
How do you install or deploy this agent?
Telegram quick start:
- Run
git clone https://github.com/duckbugio/flock. - Run
cd flock/adapters/telegram. - Run
cp .env.example .env. - Set
TELEGRAM_BOT_TOKEN,TELEGRAM_BOT_USERNAMEwithout the @ sign, comma-separatedALLOWED_USERS, andCLAUDE_CODE_OAUTH_TOKENin.env;ANTHROPIC_API_KEYcan replace the OAuth token. - From an Anthropic-supported region, run
docker compose up -d. This pulls the prebuiltghcr.io/duckbugio/flock-telegramimage.
For VK, work under adapters/vk/, copy .env.example, set VK_BOT_TOKEN, VK_GROUP_ID, VK_ALLOWED_USERS, and the Claude credential, then run docker run --env-file .env ghcr.io/duckbugio/flock-vk. LO uses adapters/lo/ and ghcr.io/duckbugio/flock-lo, but the supplied material does not include its complete startup command.
How do you use this agent?
After starting an adapter, send the bot a question or describe a development task from an allow-listed account, such as a feature spanning API and web services. A question is answered directly; a build request enters the planning pipeline, may pause for scope confirmation, and then produces work on duck/<chatid>/<slug> branches followed by tests, review, and PR creation. Set an independently evaluated objective with /goal all list views paginate correctly, or disable it with /goal off; use /schedule to define recurring jobs in the chat's configured timezone. To clone repositories and open PRs, configure GIT_HOST, GIT_USER, a write-scoped GIT_TOKEN, GIT_AUTHOR_NAME, and GIT_AUTHOR_EMAIL; for github.com, also set GH_TOKEN to the same token. For Gitea review-comment polling, configure GITEA_API_URL and GITEA_POLL_INTERVAL and enable ENABLE_PR_REVIEW.
FAQ
Does Flock require usage-based Anthropic API billing?
CLAUDE_CODE_OAUTH_TOKEN from a Claude Pro/Max subscription or use ANTHROPIC_API_KEY. AUTO_TASK_MAX_COST_PER_DAY can cap autonomy-originated spending per chat per day, although direct messages are not covered by that cap.What repository permissions does it need?
GIT_TOKEN; github.com also requires GH_TOKEN. The token should be scoped conservatively because one deployment shares it across chats.What prevents endless agent repair loops?
POST_VERIFY_MAX_FIXES, and goal evaluation is bounded by GOAL_MAX_ATTEMPTS.Can it modify and merge code without a person present?
ENABLE_AUTO_MERGE=true permits green PRs to merge automatically. Auto-merge can remain disabled for human approval, and AUTO_APPROVE_SCOPE is off by default.Do multiple users share a workspace?
/workspace/chat_<id> directories. A direct chat is private to that conversation, while members of one group share the group's workspace. The deployment-wide Git token remains shared, and adapter allow-lists control who may invoke the bot.