flock

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.

Assistant role and knowledge answers

BOT_ROLE=assistant selects a general assistant agreement for direct chats instead of the developer-team workflow. The default is developer, preserving existing bots. BOT_OWNER_INSTRUCTIONS accepts up to 8 KiB of literal text (LF and tab are supported) for context, tone and escalation rules. It also applies to LO and Telegram secretaries, whose transport/consent rules remain in force. Do not store credentials in instructions. Changing the provider, role, instructions or DuckBug credential starts a fresh agent session; prior session records and workspaces are retained.

To use DuckBug knowledge today, configure DUCKBUG_MCP_TOKEN with knowledge:read and DUCKBUG_MCP_URL (cloud default: https://duckbug.io/api/mcp). The bot uses its own authorized MCP scope. The owner can narrow topics/projects through instructions, for example:

Answer service questions from the approved DuckBug FAQ. Search before answering, read the relevant documents, and identify the source. If the answer is missing or access fails, ask me instead of guessing. Only share information intended for the correspondent; do not reveal internal procedures or credentials.

The duckbug-knowledge skill discovers the compact tool catalog, then uses kb_search and kb_get. knowledge_context remains available for engineering work; its returned files are not installed as bot rules. Existing tokens may lack knowledge:read; use DuckBug's token/access flow to grant it. This MCP wiring is currently supported on the Claude backend.

Delegated runs use the effective catalog of the current credential, including deployment availability. If no authorized KB operations are present, ordinary replies still work, but the agent is told that the knowledge base is unavailable and must not promise a lookup or invent document sources. Product MCP documents and app-admin document pickers are not substitutes for the owner's knowledge base.

Roles and prompts are behavioral preferences, not an execution sandbox. The bot retains its configured tools. MCP capabilities enforce data access; a project credential can also expose shared organization documents. Use an appropriate corpus for external replies. Direct chats keep normal tools. Delegated Secretary runs instead enforce a read-only knowledge tool policy; changing a role or prompt cannot add tools. Approval mode reviews the outgoing reply, and the host alone sends it.

Telegram Secretary Mode

Telegram can connect your bot to your account so it receives messages from selected private chats and may reply on your behalf. Enable Secretary Mode for the bot in @BotFather, then connect it in Telegram's chat automation settings and grant only the chats and can_reply permission you want. The Telegram account owner must be listed in ALLOWED_USERS.

Set SECRETARY_MODE=approval to receive an AI draft in your private chat with the bot and choose Send or Discard. Set SECRETARY_MODE=auto to send the draft automatically. The default is off. Telegram settings control chat access; for Ansible deployments set secretary_mode in the inventory variables. SECRETARY_MODE controls reply approval, while the bot's AI_BACKEND and model remain separately configured. For now, Secretary Mode is available only when AI_BACKEND=claude; other providers leave the Telegram bot running without Business message handling. Delegated messages use the selected Claude model and rendered owner instructions with only authorized kb_search, kb_get and kb_list tools. The trusted host discovers and validates these read-only operations using this bot's existing MCP credential; the model receives only a short-lived local proxy capability. It cannot access shell, files, coding skills, subagents, arbitrary MCP dispatchers or send messages directly. Unsupported providers fail closed. Explicit CLAUDE_CODE_OAUTH_TOKEN or ANTHROPIC_API_KEY is required; implicit keychain/credential-file authentication is not inherited. The runtime pins Claude Code 2.1.294 to qualify these tool-policy flags. This is an application tool restriction, not an OS sandbox.

Each delegated chat has separate private history and a readonly_v2 session namespace; ordinary coding sessions and old unrestricted secretary sessions are never resumed. Business workspaces default to SECRETARY_WORKSPACE_DIR=/workspace-business and must be mounted persistently.

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. Flock resumes each Business chat's earlier conversation. Approval draft replies and routing metadata are stored in secretary-state.json under APPROVED_DIRECTORY; delegated runs receive no file-access tools. Edited or deleted messages cancel unsent approval drafts; the bot does not generate a replacement reply for an edit. Approval buttons expire after 24 hours; Telegram may reject a reply earlier if its business reply window has closed.

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/<chatid>/<slug> 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.