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

Flock

Run a Claude Code AI dev team on your server and drive it from chat. Describe a feature in Telegram, VK or LO; the team plans it, builds it on a branch, tests it, reviews it, and opens a PR — each chat in its own isolated workspace.

It runs on your Claude Pro/Max subscription (no per-token billing) or an Anthropic API key, ships as prebuilt Docker images (no build step), and keeps every chat in its own sandboxed workspace.

Quick start (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

That pulls the prebuilt image ghcr.io/duckbugio/flock-telegram — no build, no Ansible — then message your bot. The minimum .env:

Everything else in .env.example has sensible defaults. Update later with docker compose pull && docker compose up -d.

Region: host in an Anthropic-supported region (some countries, e.g. RU/CN, are geo-blocked) — otherwise Claude calls fail.

VK is the same pattern under adapters/vk/, built on the same core and published as ghcr.io/duckbugio/flock-vk. It ships only an env template (no compose file): cp .env.example .env, then docker run --env-file .env ghcr.io/duckbugio/flock-vk. Claude auth and core settings match Telegram; only the three transport vars change:

LO has a text-first adapter with its own allow-list and workspace namespace. Its image is published as ghcr.io/duckbugio/flock-lo; start it using adapters/lo/. The LO entry point supports interrupted-run recovery, optional CI watch and Gitea PR-comment polling restricted to its own checked-out branches. Voice input uses the shared transcription providers when enabled. See the LO / Telegram compatibility audit for supported commands, optional streaming, and platform gaps.

Highlights

• 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.
• PR reactions without inbound webhooks — the bot polls your git host for new review comments and routes each back to the chat that opened the PR.
• Subscription-friendly — authenticate with a Claude Pro/Max token (no per-token cost) or an Anthropic API key.

How it works

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

The five subagents — planner → coder → tester → reviewer → arbiter — run as native Claude Code subagents in core/agents/. A plain question is just answered; a build request triggers the team. The arbiter is the risk-aware, cycle-limited loop-breaker so agents never spin forever. Branches are named duck// so PR-webhook/poll events route back to the right chat.

The team is built for a microservices workspace: a feature can span several services, and it coordinates branches and one cross-linked PR per repo. The full pipeline, guardrails, and role table live in core/README.md.

Autonomy loops

Four opt-in loops move you up the delegation ladder — from "the agent checks its own work" to "the agent runs without you" — each with a hard stop condition (env keys in .env.example):

• Post-run verification (ENABLE_POST_VERIFY, default on) — after a run reports done, the bot itself re-runs the changed repos' own check gate (task/make/npm check/test/lint) and, on red, sends the team back with the real failure output — up to POST_VERIFY_MAX_FIXES consecutive rounds. The agent's "tests pass" is verified, not trusted.
• /goal evaluator — /goal all list views paginate correctly arms a goal; after every completed run an independent, fresh-session judge (no shared context with the working session) inspects the workspace, re-runs checks, and returns a strict verdict. Not met → the unmet points are injected back as a fix-up; met → 🎯 and the goal disarms. Bounded by GOAL_MAX_ATTEMPTS; EVALUATOR_MODEL can pick a cheaper judge; /goal off disarms.
• /schedule cron jobs — durable per-chat recurring prompts with per-chat timezones (see the SCHEDULER block in .env.example); fired as normal team runs, gated by the creator's allow-list status and cost cap at fire time.
• CI watch (ENABLE_CI_WATCH) — polls CI state on the duck/* branches (GitHub check-runs or Gitea commit status). A red build injects "CI is red — fix and push" into the owning chat; a green build wakes the chat too, so "I'll report when CI finishes" actually happens — each once per commit. With ENABLE_AUTO_MERGE=true a green PR is merged automatically — the full hands-off mode; leave it false to keep the human merge.

Runs can also legally come back later: writing followup/.md (content = the prompt) schedules a durable one-shot return — and a promise nudge fires one corrective run whenever a final answer says "I'll report back" without scheduling anything that actually would, so the bot stops going silent on its own promises.

Two safety rails apply across all of it: AUTO_TASK_MAX_COST_PER_DAY caps what autonomy-originated runs may spend per chat per day (direct messages are unaffected), and AUTO_APPROVE_SCOPE controls which planner complexities may skip the "confirm scope & wait" step (off by default).

Repo layout (monorepo)

The platform-agnostic dev-team brain lives in core/; each platform is a thin adapter under adapters// that shares it.

Future platforms reuse the same core — see docs/multi-transport-plan.md.

Connect a git host (optional but core)

Set these in .env to let the team clone repos and open PRs (works with 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

For github.com, also set GH_TOKEN (= your GIT_TOKEN) so