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

Flock

Claude Code を使った AI 開発チームをサーバー上で動かし、チャットから指示しましょう。 Telegram や VK で機能を説明するだけで、チームがそれを計画し、ブランチ上で実装し、テストし、レビューして、PR を作成します。各チャットはそれぞれ隔離された専用ワークスペースで動作します。

Claude の Pro/Max サブスクリプション（トークン課金なし）または Anthropic API キーで動作し、ビルド済み Docker イメージとして配布され（ビルド手順は不要）、各チャットをそれぞれサンドボックス化されたワークスペースに隔離します。

クイックスタート（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

これによりビルド済みイメージ ghcr.io/duckbugio/flock-telegram が取得されます。ビルドも Ansible も不要で、あとは Bot にメッセージを送るだけです。最小限の .env は次のとおりです。

変数	内容
TELEGRAM_BOT_TOKEN	@BotFather から取得
TELEGRAM_BOT_USERNAME	Bot の @ユーザー名（@ は不要）
ALLOWED_USERS	Bot の利用を許可する Telegram ユーザー ID のカンマ区切りリスト
CLAUDE_CODE_OAUTH_TOKEN	claude setup-token（サブスクリプション） — または ANTHROPIC_API_KEY を設定

.env.example のそれ以外の項目には妥当なデフォルト値が設定されています。更新は後から docker compose pull && docker compose up -d で行えます。

Telegram の秘書モード

@BotFather でボットの秘書モードを有効にし、Telegram でアクセスを許す個人チャットを選びます。アカウント所有者の ID を ALLOWED_USERS に追加してください。SECRETARY_MODE=approval は所有者へ送信・破棄ボタン付きの下書きを送り、SECRETARY_MODE=auto は直ちに返信します。返信にはボットで別途選択した AI プロバイダーとモデル（AI_BACKEND）を使用します。Telegram 側で別の AI モデルは選びません。Claude では秘書も通常の Flock エージェントとして動作し、ツール、MCP、Business チャットごとの永続的な会話履歴を利用します。自動返信前にプロバイダー側で支出上限を設定してください。英語の詳細。

現在、秘書モードは AI_BACKEND=claude のみ対応します。他のプロバイダーではボットは動作を続けますが、Business メッセージは処理しません。

Flock のツールと MCP を使わせてもよい相手のチャットだけにアクセスを許可してください。承認の対象は返信の送信だけです。ツールは承認前に動作する場合があり、実行済みの操作は取り消せません。

リージョン: Anthropic がサポートするリージョンでホストしてください（一部の国、例えば RU/CN などはジオブロックされています）。そうでない場合、Claude の呼び出しは失敗します。

VK も同じパターンで adapters/vk/ に用意されており、同じコアの上に構築され、ghcr.io/duckbugio/flock-vk として公開されています。配布されるのは env テンプレートのみ（compose ファイルはありません）。cp .env.example .env のあと、docker run --env-file .env ghcr.io/duckbugio/flock-vk を実行します。Claude の認証とコア設定は Telegram と同じで、トランスポート用の 3 つの変数のみが異なります。

変数	内容
VK_BOT_TOKEN	コミュニティアクセストークン（VK コミュニティ → 管理 → API の利用 → アクセストークン）
VK_GROUP_ID	コミュニティの数値 ID（ロングポーリングサーバー + メンション解析用）
VK_ALLOWED_USERS	Bot の利用を許可する VK ユーザー ID のカンマ区切りリスト

主な特長

• 会話そのものがタスクの起点 — チャットでやりたいことを説明し、返ってくる PR をレビューするだけ。エージェントのシェルとエディタはコンテナ内にサンドボックス化されています。
• 単発のプロンプトではなく、本物の開発チームのパイプライン — 仕様優先の受け入れ基準、ビルド/回帰テストのゲート、そしてループを断ち切る arbiter を備えています。
• マルチトランスポート — 現在は Telegram と VK に対応し、いずれも同じコアの上で動作します。新しいプラットフォームの追加はフォークではなく薄いアダプターで済みます。
• インバウンド Webhook なしで PR に反応 — Bot は新しいレビューコメントを git ホストに対してポーリングし、それぞれを PR を作成したチャットへ振り分けます。
• サブスクリプションに優しい — Claude Pro/Max トークン（トークン課金なし）または Anthropic API キーで認証できます。

仕組み

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

5 つのサブエージェント — planner → coder → tester → reviewer → arbiter — は、core/agents/ にネイティブな Claude Code サブエージェントとして配置されています。単なる質問にはそのまま回答し、ビルドの依頼があるとチームが起動します。arbiter はリスクを認識しサイクルを制限するループブレーカーで、エージェントが永遠に空回りしないようにします。ブランチは duck/<chatid>/<slug> という名前が付けられ、PR の webhook/ポーリングイベントが適切なチャットへ振り分けられます。

このチームはマイクロサービスワークスペース向けに作られています。機能は複数のサービスにまたがることがあり、チームはブランチを調整し、リポジトリごとに相互リンクされた PR を 1 つ作成します。パイプライン全体、ガードレール、役割の一覧は core/README.md にあります。

リポジトリ構成（モノレポ）

プラットフォーム非依存の開発チームの頭脳は core/ にあります。各プラットフォームはそれを共有する adapters/<name>/ 配下の薄いアダプターです。

アダプター	パス	ビルド済みイメージ
Telegram	adapters/telegram/	ghcr.io/duckbugio/flock-telegram
VK	adapters/vk/	ghcr.io/duckbugio/flock-vk

今後のプラットフォームも同じコアを再利用します — docs/multi-transport-plan.md を参照してください。

git ホストを接続する（オプションですが中核機能）

チームがリポジトリをクローンして PR を作成できるよう、.env に以下を設定します（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

github.com の場合は、gh CLI が PR を作成できるよう GH_TOKEN（= あなたの GIT_TOKEN）も設定してください。

ポーラーはレビューコメントに反応するための推奨手段です。こちらから外向きに接続するため、ホストから Bot に到達できない環境でも動作します。ENABLE_PR_REVIEW=true かつ GITEA_API_URL が設定されているときに有効になります。インバウンド Webhook + Caddy TLS プロキシという代替手段は、Ansible デプロイ経由でのみ利用できます（webhook_domain を設定）。

その他のオプション

• 音声メッセージ: ENABLE_VOICE_MESSAGES=true、VOICE_PROVIDER=mistral|openai|local、加えて MISTRAL_API_KEY（または OPENAI_API_KEY）。文字起こしされてコマンドとして実行されます。
• dind サイドカー: docker compose --profile dind up -d で、Docker 化されたリンター/テストをチームに提供します（DOCKER_HOST=tcp://dind:2375 を設定）。
• チャットごとの隔離: 各チャットには /workspace/chat_<id> が割り当てられます（1:1 → プライベート、グループ → 1 つの共有ワークスペース）。チャットは完全に隔離され、MAX_CONCURRENT_CHAT_RUNS を上限として並列実行されます。グループでは REQUIRE_GROUP_MENTION=true を設定すると、@メンションまたは返信されたときのみ応答します。
• Ansible デプロイ（Telegram）: adapters/telegram/deploy からワンコマンドで VPS をプロビジョニングします。inventories/example を自分用の inventories/<name>/（gitignore 対象）にコピーし、inventory/vars/vault を埋めてから ansible-playbook -i inventories/<name>/inventory.ini playbook.yml を実行します。ロールはビルド済みイメージを取得します。タグを固定するには bot_image を設定してください。

セキュリティ

• ホワイトリスト: ALLOWED_USERS（Telegram）/ VK_ALLOWED_USERS（VK）のみが Bot を利用できます。決して空のままにしないでください。これはサーバーへのシェル/編集アクセスを付与するものです。
• チャットごとの隔離: 異なるチャットには別々のワークスペースが割り当てられます。git トークンはデプロイ全体で共有されるため、それに応じてスコープを設定してください。
• シークレット: シークレットは .env（gitignore 対象）に、Ansible の場合は実際のインスタンスの vault.yml（gitignore 対象、ansible-vault で暗号化可能）に保管してください。追跡対象は inventories/example/ のみです。
• サンドボックス: エージェントは非 root ユーザーとして動作します。その Bash/Edit はコンテナ内に限定され、ホストには及びません。

ビルド・リント・テスト

このリポジトリは CI ランナーとして Task を使用しており、CI が使うのと同じエントリポイントです。

task lint      # format + vet + linters (in the dev-tools image)
task tests     # Go test suite
task build     # compile the binaries

ライセンス

MIT © DuckBug.

コントリビューションとセキュリティ

貢献方法と脆弱性の報告については以下を参照してください: CONTRIBUTING.md、CODE_OF_CONDUCT.md、SECURITY.md。