@interactive-inc/claude-funnel weekly downloads statistics

Open Claude Funnel

Slack のメンション、GitHub の Issue、毎朝 9 時の cron。こうした外部の出来事を Claude Code エージェントに届け、エージェントの返信を同じ経路で外へ返すハブ。

コマンドは funnel（短縮形 fnl）。Claude Code を中心に作っているが、アーキテクチャはエージェント非依存。現在のバージョンは 0.53.0。

funnel がやること

• 外部の出来事（チャットのメンション、新しい Issue、cron の tick）を、起動中のエージェントセッションにそのまま届ける • エージェントの返信を受信と同じコネクタで外へ返す。bash サブシェルも CLI のコールドスタートもなく、実質同期 • 外部接続は常駐デーモンが 1 か所で持つ。エージェントを何個起こしても接続は 1 回だけ。ヘルスチェックと自動再起動で監視する • 複数のエージェントで 1 つのソースを共有（fanout）するか、ワーカーとして分担（exclusive）するかを選べる

対応コネクタは Slack（Socket Mode）、GitHub（gh 経由の poll）、Discord（Gateway）、cron スケジュールの 4 種類。

必要なもの

• Bun 1.3 以降 • Claude Code CLI • 接続する外部サービスのトークンまたは CLI（Slack アプリ、gh 認証、Discord bot など）

リポジトリで使う（推奨）

設定を funnel.json としてリポジトリに commit し、チームで共有・バージョン管理できる。グローバルに何も入れないので、リポジトリの lock ファイルでバージョンが固定される。

インストール

これで bunx funnel（または bunx fnl）が使える。

設定

リポジトリ直下に funnel.json を置く。transport（channels[]）と起動レシピ（profiles[]）を宣言する。

channels は購読箱（transport）。各チャネルは connectors を持てる。connectors 配列はそのチャネルの真実の源で、起動時に宣言にないコネクタは削除され、足りないコネクタは作られる（名前で照合）。connectors フィールド自体が無ければ既存のコネクタはそのまま残る。

profiles は起動レシピ。各プロファイルは一意な name を持ち、channel でチャネルを名前指定でバインドし、次を持つ。

• options — claude の argv 先頭に積む（ユーザーが渡す CLI 引数はその後ろ。--brief / --agent / --model などに使う） • env — 起動する claude プロセスに被せる（衝突時は起動シェルの process.env が勝つ） • resume — claude セッションの再利用可否

同じチャネルに複数のプロファイルをバインドしてよく、name で区別する。チャネル側がプロファイルを選ぶことはない（プロファイルがチャネルを bind する一方向）。

トークンは funnel.json に書かない（スキーマが弾く）。リポジトリ内で次のどちらか。

• fnl channels ops connectors set my-slack --bot-token=xoxb-... --app-token=xapp-... で設定する • 省略して fnl claude 起動時の TTY プロンプトで答える。次回以降は引き継がれ再度聞かれない

いずれもトークンは ~/.funnel/projects//settings.json（リポジトリ外）に保存され、commit されない。

funnel.json に書けないものが 2 つある。delivery モード（fanout / exclusive）は CLI で設定する（funnel.json のチャネルは fanout 固定）。schedule の cron エントリも CLI で足す（funnel.json には schedule コネクタの存在だけ宣言できる）。

セッション再開には resume の明示が要る。funnel.json の resume はデフォルト値を持たず、書かないと再開されない（未指定が false 扱いになる）。前回の claude セッションを引き継ぎたいなら必ず "resume": true を書く。再開のための session id は funnel が ~/.funnel/projects//claude/local-sessions.json に自動で保存・読み出しするので、funnel.json には書かない。

使い方

--profile なしの bunx fnl claude は、funnel.json の先頭チャネルで起動する。--channel review で名前指定すると、そのチャネルを transport だけバインドして起動する（レシピなし）。

これでコネクタが見たイベントが、起動中のエージェントセッションに届く。エージェントは my-slack という MCP ツールで返信できる。

cron 起動を足す（schedule コネクタを宣言したうえで、エントリは CLI で）。

cron は一致する tick ごと、一回実行は run-at 以降の最初の tick でプロンプトを発火する。発火済みの一回実行は state に記録されるため、設定削除の hook が失敗しても再発火しない。デーモン停止中に逃した枠は次回起動時に catch-up する（meta.catchup = "true"。cron の探索は最大 24 時間）。

cron は標準の 5 フィールド規則に従う。day-of-month と day-of-week を両方限定した場合は OR、日曜は 0 と 7 の両方を受け付ける。不正な式は登録時に拒否される。

funnel.json を持つリポジトリは自分自身にスコープされる。初回起動時に funnel は funnel.json の先頭へ不変の id(uuid) を書き戻し、以降このリポジトリの funnel state を ~/.funnel/projects// 配下に隔離する。グローバルの ~/.funnel には一切触らない（イベントログと一時ファイルだけが /tmp/funnel/ で共有）。このスコープはリポジトリ内で実行する全 CLI コマンドに効く。

トップレベルの $schema（任意）は JSON Schema を指し、エディタの検証と補完が効く。ローカルインストールでは ./node_modules/@interactive-inc/claude-funnel/funnel.schema.json を推奨する（ネットワーク往復なし）。https://interactive-inc.github.io/open-claude-funnel/funnel.schema.json でも公開しており、fnl schema > funnel.schema.json でローカルコピーを再生成できる。

グローバルで使う

触るすべてのリポジトリで 1 つの CLI を共有したいときはグローバルに入れる。設定は funnel.json ではなく CLI で組み、~/.funnel/settings.json（グローバル）に保存される。

これで funnel / fnl がどこでも使える。ソース 1 つをエージェント 1 つにつなぐ最短手順。

delivery モードはチャネル作成時に選ぶ。tap=all は廃止されており、WS 購読は ?id= の targeted delivery のみ。

ワンコマンド起動のためにプロファイルとして保存する。プロファイルは起動レシピを持つ。

公開パッケージはビルド済みの dist/ を同梱しているので、どちらのインストールでも funnel / fnl がすぐ使える（post-install ステップなし）。リポジトリ単位で入れたなら、以降の fnl は bunx funnel に読み替える。

コマンドの一覧やフラグはここに並べない。fnl --help で全体、fnl --help（例 fnl channels --help）で個別の使い方が出る。動詞だけを引数なしで打ってもヘルプが返る。

なぜ funnel なのか

1 つのエージェントセッションは、1 つのリポジトリ・1 つの瞬間を扱うのは得意だ。だがそれに「何かに反応させたい」と思った瞬間 — チャットのメンション、新しい Issue、朝 9 時のスタンドアップ — シェルスクリプトと cron と bash -c "agent ..." をつなぎ合わせる羽目になる。「誰が何を聞いていて、誰がどこに返信していいのか」を一望できる場所がどこにもない。

funnel はその場所になる。名前付きの購読箱（チャネル）を宣言し、コネクタを取り付け、チャネルをバインドしてエージェントを起動すれば、あとはデーモンが面倒を見る。使うモチベーションは次の点にある。

外部接続をデーモンが 1 か所で持つ。各接続は、エージェントセッションを何個起こしても 1 回だけつながる。2 つ目のエージェントが 2 つ目のソケットを開くことはなく、両方が同じチャネルを購読し、デーモンがイベントを fanout する。

受信イベントは MCP 通知として届くので、エージェントは今いるセッションのまま反応する。新しいプロセスを起こさない。

送信（返信）はコネクタごとの MCP ツールを使う。bash も CLI のコールドスタートもなく、実質同期で返る。

リスナーはヘルスチェックと自動再起動で監視される。接続が不安定でも poller がクラッシュしても、自分で復旧する。

複数のエージェントが 1 つのチャネルを共有する（fanout）か、ワーカーとしてイベントを取り合う（exclusive）かを選べる。どのイベントを誰が受けるかはデーモンが決める。

つまり、外部とのつなぎ込みという「配管」を 1 つのデーモンに集約し、エージェント側は購読と返信という単純な世界だけを見ればよくなる。これが funnel を使う理由になる。

仕組み

全体像

Channel と Connector と Profile

transport モデルは 2 つの概念でできている。

Channel は名前付きの購読箱（transport のみ）。1 つ以上のコネクタと delivery モードを持ち、起動フラグは持たない。エージェントセッションはちょうど 1 つのチャネルを購読する。WS 接続は ?id= の targeted delivery のみで、tap=all は廃止されている。delivery は fanout（全 subscriber が全イベントを見る、デフォルト）か exclusive（1 イベントを 1 subscriber が round-robin で消費、ワーカープール向け）。

exclusive の再接続では同じ id と最後に配送を完了した since を渡す。配送先を永続化するため、別ワーカーへ配送済みのイベントは再送されない。接続者がいない間のイベントは、最初に再送を要求したワーカーへ割り当てる。MCP クライアントはプロセス内で同じ id を維持する。自作クライアントで id を省略した場合は接続中の配送のみを利用でき、exclusive の since 指定には id が必須。

再送用の本文は全文保存する。旧バージョンで既に切り詰められた本文は復元されず、配送先の記録がない旧イベントは exclusive では再送しない。同じワーカーへの再送はあり得るため、外部への副作用の完了を一度だけにする保証とは別である。コネクタの改名・追加や配送モードの変更は、次の送信時に接続済みクライアントにも反映する。存在しないチャネルへの publish は HTTP 404（SDK は FunnelChannelNotFoundError）になる。

Connector はチャネルから外部ソースへの 1 つの接続。slack / gh / discord / schedule の 4 型。前者 3 つは双方向（イベント入力・返信出力）、schedule は一方向（cron tick の入力のみ）。

Profile はその transport モデルの外側にある起動の便宜レイヤで、モデルの一部ではない。エージェントを動かすのに必須ではない（fnl claude --channel で足りる）。{ path, channelId, options, env, resume } を束ねた保存済みの起動 preset で、fnl claude --profile cto が既知のセットアップを再現する。どのディレクトリから起動するか、どのチャネルをバインドするか、起動レシピ（claude argv の先頭に積む引数、プロセスに被せる env、セッション再利用）をまとめて持つ。プロファイルは不変の uuid id を持ち（PID ファイルと再開可能なセッションがこれをキーにするので、rename してもどちらも迷子にならない）、name は人が打つハンドル。プロファイルは既にチャネルをバインドしているので、--profile と --channel は併用できない。

daemon…

Description from the npm listing.