flanner

Flanner

AI コーディングエージェント向けのプランファイル管理ツールです。MCP（Model Context Protocol）を介して Claude Code やその他のアシスタントと連携します。

なぜ必要なのか

AI エージェントは、設計ドキュメント、移行計画、アーキテクチャに関するメモなどの Markdown ファイルを絶えず作成します。こうしたファイルはすぐに増え、リポジトリ内のあちこちに散らばり、いつの間にか古くなり、誤ってコミットされやすくなります。Flanner はこれらのファイルを一か所にまとめ、エージェントが修正するたびに自動でバージョン管理します。また、必要と判断するまで Git の対象から外し、閲覧しやすい表示画面と監査履歴も提供します。

いや、まだ納得できません。それでも、なぜ必要なのですか？

プランファイルは、ローカルのプロジェクト内に散らばるだけでなく、プロジェクト管理ツールの未解決課題の中にも散らばっていきます。Flanner はその両方をつなぐ要として、ディスク上のファイルを整理し、それぞれのプランを関連する課題にリンクします。

Flanner はローカル優先であり、チームで使う場合もその方針は変わりません。プランは暗号化された接続を介してマシン間で直接同期されます。プランを保管するサーバーはなく、アップロードの手順もありません。ホスト側のサービス（Flanner Mesh）は ID を発行し、誰が何を読めるかを決定しますが、プランの内容を見ることはなく、見ようとしても読むことはできません。次の段階では、プロダクトトラッカーやチャットから Notion のようなセカンドブレインまで、チームがすでに使っているツールとの連携を実現します。

機能

• MCP 連携：プランファイルのツールを Claude Code と Codex に公開します。
• ヘッダーとバージョン管理の自動化：すべてのプランに YAML フロントマターが付き、改訂のたびに新しいバージョンが作成され、履歴全体が保存されます。
• Git による保護：プランは .plans/ に保存され、コミットに自動的に含まれないようにします。
• エージェント連携：flanner init により、CLAUDE.md、AGENTS.md、ガードフックを設定します。エージェントは Markdown をそのまま書き散らすのではなく、flanner を通じてプランを保存します。
• メモリー：プランを取り巻く、長期的に保持すべきコンテキストです。制約、却下したライブラリ、環境についての事実などを Markdown ファイルとして保存し、後のセッションで検索できます。デフォルトでは、エージェントが提案し、あなたが承認します。認証情報と思われるものは拒否し、誰かに求められた場合にのみチームメイトと共有します。
• スキル：エージェントが実際に読み込むものです。スキルパッケージは、プロジェクト、ホームディレクトリ、インストール済みのすべてのプラグインから一度に読み込まれます。同じ名前のパッケージが複数ある場合、1つが暗黙的に選ばれます。flanner skills scan ですべてを読み取り、flanner skills doctor でどのコピーが有効か、ほかのコピーに何が問題なのかを確認できます。読み取りのみで、パッケージ内のものは実行されません。
• Curb：各エージェントがアクセスできる範囲を確認します。flanner curb map は Claude Code と Codex の起動ごとに、読み取り可能な認証情報と、それらを外部に送信し得るチャネルを確認し、その根拠となるルールとともにリスクを High、Medium、Low で評価します。実行者が誰であっても、その出力に認証情報や場所の名前が記載されることはありません。flanner curb show では、それらを画面上のウィンドウに表示します。flanner curb sweep は、トランスクリプト、セッション、指示ファイル、スキル、MCP 設定、シェル履歴、.env ファイルにエージェントが残したシークレットを検出し、そのうちどれがモデルプロバイダーに送信されたかを示します。読み取りのみで、何も変更されません。シークレットの発行元に確認を求めない限り、マシンの外部に情報が送信されることもありません。Flanner Mesh を使うと、flanner curb policy は組織が署名したエージェントポリシーを適用し、登録後は制限を強化する変更のみを適用し、それ以外の変更はすべて承認待ちにします。flanner curb fleet では、各デバイスが署名した最小限のレポートに基づき、管理者がデバイスごとのポリシー状態と件数を確認できます。GitHub Action としても提供される actions/curb-ci の flanner curb ci は、CI ワークフロー内のエージェントのステップを同じ方法で判定し、SARIF を出力します。flanner curb app はアプリケーション独自の LLM 呼び出しを検出します。また、agent-blast-radius スキルを使うと、エージェントが自らコマンドを実行して、結果をマスキングできます。flanner curb attribution は各エージェントに専用の署名鍵を割り当て、OS の認証情報ストアに保持して、そのエージェントのコミットにラベルを付けます。flanner curb verify は、組織の署名済み鍵レジストリと照合し、各コミットに署名したエージェント鍵を示します。署名で分かるのは、どの鍵が署名したかであり、誰がコードを書いたかではありません。
• メッセージ（Team Mesh）：チームメイトは、デバイス間でエージェント内から互いにメッセージを送信できます。flanner messages send は送信前に内容をプレビューし、flanner はエージェントに、チームメイトからのメッセージを表示するだけで、それに基づいて行動しないよう指示します。
• 課題トラッカーとの連携（このビルドでは無効）：プランを Linear（または JIRA）の課題にひも付けます。LINEAR_API_KEY が設定されている場合、flanner は課題を検証し、CLI とダッシュボードに最新の状態を表示します。実装済みですが、まだサポートされていません。FLANNER_INTEGRATIONS=1 を設定すると有効になります。
• 閲覧ビュー：プランの閲覧、編集、履歴の確認ができるブラウザーダッシュボードです（ライトモードとダークモードに対応し、完全にオフラインで動作します）。
• プロジェクトごとの設定：リポジトリごとにプランのディレクトリをカスタマイズできます。

クイックスタート

uv tool install flanner   # or: pipx install flanner, or: pip install flanner

cd your-project      # a git repo where plans should live
flanner init         # sets up the database, MCP registration, and a project

Python をインストールしたくない場合は、Windows、macOS、Linux 向けのデスクトップアプリをご利用ください。インストール不要で、ウィンドウ内の Web UI、コマンドライン、Claude と Codex が使用する MCP サーバーがひとつになっており、バックグラウンドでの同期とアップデートにも対応しています。flanner.io/download からダウンロードできます。ビルドとリリースについては、desktop/README.md をご覧ください。

uv tool install を使うと、flanner 専用の環境が作成され、flanner と flanner-mcp の両方が PATH に追加されます。どちらも重要です。エージェントは名前で flanner-mcp を起動するため、プロジェクトの仮想環境によって、その環境の外から起動したエージェントが見つけられなくなることがあります。この点に注意すれば、pip install flanner でも動作します。

エージェントに、プランを作成・確認するよう依頼してみましょう。

「認証サービスのアーキテクチャプランを作成して」

「アーキテクチャプランの履歴を表示して」

ダッシュボードを開いて、プランを確認しましょう。

flanner web --open-browser     # http://localhost:8080

flanner init は何度実行しても安全です。git のルートを検出し、.plans/ を作成し、.gitignore を更新して、エージェントとの連携を設定します。

3 つのエージェントで設定ファイルはそれぞれ異なりますが、init がすべて処理するため、覚えておく必要のある 2 つ目のコマンドはありません。Claude Code が読み込むプロジェクト単位の .mcp.json を書き込み、ユーザースコープと Claude Desktop の設定にサーバーを登録し、CLAUDE.md と AGENTS.md に管理対象のブロックを追加します。Codex は AGENTS.md を読み込み、~/.codex/config.toml に MCP サーバーを登録します。Codex がインストールされている場合、init はそこに flanner のエントリーを追加し、ファイルを安全に編集できない場合にのみ、貼り付ける 2 行を表示します。flanner status にはエージェントごとに行が表示され、それぞれのエージェントが実際に参照する場所を確認します。後でいずれかの設定を修復する必要がある場合は、flanner setup を再実行すると、そのエージェントの登録がやり直されます。

--setup で設定するエージェントを選択でき、何度でも指定できます。たとえば、flanner init --setup codex は Codex のみを登録します。--skip-claude を指定すると、エージェントを登録しませんが、リポジトリ内のファイルは引き続き書き込まれます。

ほかの人がセットアップしたリポジトリを使い始める場合は、flanner init --sync で、すでにコミットされているプランファイルもインポートできます。これにより、すぐに flanner list で表示できます。

CLI コマンド

flanner init [--project-root PATH] [--plan-dir DIR]     # set up a project
flanner status                                          # projects, plan files, db path
flanner list [--project NAME] [--output json]           # list projects or a project's plans
flanner sync [--project NAME] [--dry-run]               # import existing .plans/ files
flanner config NAME [--plan-dir DIR] [...]              # change project settings
flanner web [--port 8080] [--host 127.0.0.1] [--open-browser]
flanner start [--port 8765] / flanner stop              # MCP server in the background, over http
flanner peer start / flanner peer stop                  # serve plans to teammates in the background
flanner mem remember "..." --category fact              # durable context for later sessions
flanner mem recall "..."                                # search what earlier sessions knew
flanner mem list / show ID / supersede ID --with "..."  # browse, read, and correct
flanner mem mode [off|explicit|suggest|auto_safe]       # how much this project captures
flanner mem share ID / flanner mem withdraw ID          # give one to the team, or ask them to stop
flanner skills scan / flanner skills doctor             # what your agents load, and what is wrong
flanner skills list [--all] / inspect NAME              # browse them, or read every copy of one
flanner skills observe enable / flanner skills report   # record which get used; init asks
flanner skills adopt NAME / install HASH / rollback ID  # keep a copy, install it, put it back
flanner skills share HASH / transfers / import ID       # send one to the team; receiving is not installing
flanner curb map [--agent A] [-- LAUNCH ...]            # what each agent launch can reach
flanner curb show                                       # names and locations, in a window
flanner curb inventory                                  # agents, MCP servers, hooks, jobs
flanner curb sweep [--validate]                         # secrets agents left behind (needs flanner[sweep])
flanner curb forget                                     # delete Curb's reports and digest key
flanner curb fix [--dry-run|--undo]                     # close what agents reach, after your OS says yes
flanner curb test                                       # prove each block with decoys (costs tokens)
flanner curb decoys [--renew|--remove]                  # the decoys the tester planted
flanner curb scrub FILE [--dry-run]                     # replace rotated secrets in a file (no undo)
flanner curb log [--enable|--disable|--verify]          # each tool call's metadata, hash-chained and signed
flanner curb observed                                   # what each agent has been seen using
flanner curb policy [--check-in|--enrol|--approve]      # your organization's signed agent policy
flanner curb fleet                                      # every device, checked by its own signature (admins)
flanner curb ci [PATH] [--sarif F] [--fail-on L]        # agent steps in CI workflows, as SARIF
flanner curb app [PATH] [--sarif F]                     # LLM calls in an app's Python code
flanner curb attribution [--setup|--rotate]             # sign each agent's commits with its own key
flanner curb verify [REV|RANGE]                         # which agent key signed each commit
flanner register [--force] / flanner unregister         # MCP registration with Claude Desktop
flanner claude-info                                     # integration status

ほとんどの MCP クライアントは stdio 経由でサーバーの独自コピーを起動するため、start も stop も必要ありません。これらのコマンドは、http のみを使用するクライアント、1 つのサーバーを共有する 2 つのエディター、または flanner 単独での使用を想定しています。サーバーは 127.0.0.1 にバインドされ、これを広げるオプションはありません。各ツールは起動したユーザーと同じ完全な権限で動作し、呼び出し元の認証も行いません。

---
mcp_plan_file: true
project_id: 3d816ecd-489a-4fa0-abe2-15ec93f60d5a
plan_file_id: 59c34f9c-8471-47fc-97f2-8dcfefa15434
plan_name: architecture
version: 2
created_by: claude
---

# Architecture Plan

Your plan content here...

flanner linear auth                                     # verify LINEAR_API_KEY, print MCP snippet
flanner linear config PROJECT --workspace acme          # linear.app/acme
flanner linear link PLAN --issue ENG-123 [--notes ...]  # link a plan to an issue
flanner linear links [--project PROJECT]                # list all links
flanner linear show PLAN [--project PROJECT]            # links for one plan
flanner linear unlink PLAN [--issue ENG-123 | --all]
flanner linear refresh PLAN                             # re-pull title/state (needs API key)

flanner peer serve                                      # answer authorised peers
flanner peer pull <device-id> [--project NAME]          # pull what a peer holds
flanner peer status [<device-id>]                       # how this device is reached

Windows AMD64、Python 3.13.1、ローカル SSD 上の SQLite で測定しています。python benchmarks/bench.py で再現できます。

コールドスタートも同じ方法で測定しています。

データストアを開かないコマンドも含め、すべてのコマンドで SQLAlchemy がインポートされており、インポート時間 1.1 秒のうち 630 ms を占めていました。現在は薄いラッパーを通じて初回使用時にインポートするため、データベースに触れないコマンドではその分の時間がかかりません。flanner list はデータストアを開くため、その時間はオーバーヘッドではなく実際の処理に費やされています。

どちらも 500 ms の基準を下回りました。これらは編集可能インストールでの測定値です。通常の pip install にはない、インポートファインダーのオーバーヘッドが約 80 ms 加わります。

flanner list はこの表から外しました。データストアを開くため、その時間はスタートアップではなく実際の処理に費やされています。何も開かない 2 つのコマンドの横に載せると、不適切な比較を招くためです。

数値は python benchmarks/bench.py で取得しています。このスクリプトは python -m flanner.cli ではなく、インストール済みのコンソールスクリプトを測定します。両者は同じではなく、報告する価値があるのは実際に人が入力するほうです。CI では各実行を benchmarks/baseline.json と比較し、3 倍を超えると失敗します。これにより桁違いの性能劣化は検出できますが、それより小さな変化は検出できません。同一のコードでも、共有ランナーでは測定時間が 2 倍変動することがあるためです。

問題が発生したとき

flanner --verbose doctor        # where the time went, per step
flanner doctor --report         # a scrubbed summary to paste into an issue

--verbose を指定すると、コマンド実行後に処理時間の内訳が表示されるため、プロファイラーがなくても「なぜ遅かったのか」がわかります。

doctor --report は、バージョン、プラットフォーム、データストアのサイズ、カタログ件数、メッシュトランスポートがインストールされているかどうかを表示します。パス、プラン名、プランの内容は表示されません。プロジェクト名を含むローカルログを保持するのは問題ありませんが、その内容を公開イシューに貼り付けるのは問題です。データストアを開けないときにも動作するため、まさに必要なときに使えます。

MCP サーバーは ~/.flanner/mcp.log を保持します。各ツール呼び出しについて、結果とエラーを 1 行ずつ記録します。この機能には人間の監視者がいないため、エラーに遭遇したエージェントが何事もなかったかのように回避策を講じると、記録がまったく残らないおそれがあります。プラン本文はここに書き込まれません。flanner peer serve も、応答したリクエストを同じファイルに記録します。

プラン、メモリー、スキルがマシンの外に出ることはありません。 有効にしない限り、flanner がほかの情報を送信することもありません。flanner が送信する情報をご覧ください。

flanner が送信するもの

デフォルトでは何も送信しません。2 つの機能を、それぞれ専用のコマンドで有効にできます。 バージョンチェックについては、flanner init で個別に確認します。クラッシュレポートも、送信先が用意されれば同様になります。このビルドにはレポートの送信先がないため、init ではクラッシュレポートについて確認せず、何も送信されません。

クラッシュレポートに、エラーメッセージ、ローカル変数、ソースコードの行、コマンド引数、完全なファイルパス、ユーザー名やマシン名、個人を特定したり人数を数えたりする情報が含まれることはありません。flanner crash-reports show を実行すると、送信待ちの内容、または最後に送信された内容がそのまま表示されます。レポートは、クラッシュしたコマンドではなく、独立したバックグラウンドプロセスによって送信されます。DO_NOT_TRACK=1 または FLANNER_CRASH_REPORTS=0 を設定すると、回答内容にかかわらずクラッシュレポートが無効になります。

プラン、メモリ、スキルの内容が送信されるのは、Flanner Mesh 経由で、ご自身のチームのデバイスに直接送る場合に限られます。

終了コード

スクリプトで「コマンドを修正してください」と「このマシンに問題があります」を区別できるよう、終了コードを分けています。

仕組み

エージェントは get_plan_config を呼び出してプランの保存先を確認し、次に create_plan_file_tool または update_plan_file_tool を使ってプランを書き込みます。Flanner はプロジェクトのプランディレクトリにファイルを配置し、ヘッダーを追加して、バージョンを更新します。ファイルは .plans/（Git の追跡対象外）に保存されるため、誤ってコミットされることはありません。

削除や整理は一切行われません。 すべてのバージョン、コメント、レビューの判断が保持されます。ストアは追記専用で、クリーンアップコマンドはありません。また、設定ページにはバイト単位の使用量が表示されるため、コストを推測ではなく明確に把握できます。削除の扱いも同じ設計に基づいています。flanner retire <plan> を実行すると、すべてのピアにプランの表示と提供を停止するよう要求し、--restore で元に戻せます。ただし、これは他のデバイスが尊重する取り下げの要求であり、データの消去ではありません。実行時にオフラインだったチームメイトのデバイスには、次回同期するまで内容が残ります。また、すでにデータを保持している人からデータが消えることもありません。自分が管理していない複数のマシンに広がる追記専用ストアが誠実に約束できるのは、これが限界です。そのため、ここではこの約束をしています。

エージェントが手順から逸れないようにする仕組み。 MCP ツールは「方法」です。さらに flanner init は、エージェントが実際にツールを使うようにする 2 層の仕組みもインストールします。CLAUDE.md と AGENTS.md（Claude Code と Codex が各セッションで読み込むガイダンス）に管理対象のブロックを書き込み、flanner-plan スキルも追加することで、プランのドキュメントを flanner 経由で扱うようエージェントに指示します。それに加えて、guard-write PreToolUse フックがプランディレクトリへの直接書き込みを拒否し、エージェントに create_plan_file_tool を使うよう促します。そのため、ガイダンスを無視した場合でも、プランが管理されていない Markdown として保存されることはありません。このフックはフェイルオープンで動作し、ほかの場所への書き込みを妨げることはありません。

ロードマップ

0.9.0 でリリース：ピアツーピア同期、共有ワークスペース、チームメイト間のレビューに対応しました。プランはマシン間で直接移動し、アップロードされることはありません。仕組みと費用については、Flanner Mesh をご覧ください。

その後のリリース：ウェブ UI のサーバー送信イベントによるライブ更新、互いに直接接続できないピア向けのリレーフォールバック、そして 0.12.0 で Flanner Memory と Flanner Skills に対応しました。

今後の予定：

• プラン本文を対象にした全文検索。コマンドパレットでは現在、名前がインデックス化されていますが、プラン内のテキストはまだ検索できません。
• Notion のような製品トラッカー、チャット、セカンドブレインへのリンク
• スキルの比較実行。保存だけにとどまりません。flanner skills eval はハーネスまたは人が生成した結果を記録しますが、モデルとハーネスに対してテストスイート自体をまだ実行しません。
• 信頼できるインターフェースが整い次第、Claude Code 以外のエージェントの利用状況を観測します。それまでは、Skills の利用状況はゼロではなく不明として報告されます。

プランの内容をホストする予定はありません。カタログはお使いのマシン上に保持されます。これは設計上の判断であり、資金調達待ちのマイルストーンではありません。

コントリビューション

セットアップ、CI のチェック項目、ユニットテストとブラウザーテストの実行方法、ベンチマーク、リリースプロセスについては、CONTRIBUTING.md をご覧ください。

ライセンス

MIT