Flameox

flameox

コーディングエージェント向けの、範囲を限定したローカル実行時エビデンス。

Flameox は、プロファイラー、ベンチマークツール、トレースプロセッサー、ローカルの直接ターゲットを連携させます。明示的に指定されたアーティファクトまたはコマンドを、永続的な保存を任意としながら、範囲を限定したエビデンスに変換します。エージェントが仮説と実験を選び、Flameox は観測された入力、実行の来歴、型付きエビデンス、カバレッジ、制約を記録します。

初期化するワークスペースも、維持するプロジェクト設定もありません。分析には正確なアーティファクトパスを、キャプチャには明示的な argv と絶対パスの作業ディレクトリを渡します。Flameox は親ディレクトリを検索せず、プロジェクトファイルを編集せず、ホスト型サービスも提供しません。

クイックスタート

グローバルセットアップコマンドを使って、MCP クライアントを設定します。

npx flameox@latest setup

セットアップでは、サポート対象のクライアントを検出し、更新する設定を尋ねます。自動化する場合は、たとえば --client codex --yes または --all --yes のように、クライアントを明示的に選択します。--dry-run は、書き込みを行わずにパスとアクションを報告します。セットアップは無関係なクライアント設定を保持し、プロジェクトファイルは変更しません。詳しくは npm パッケージガイドを参照してください。

既存の MCP 登録を更新するには、次を実行します。

npx flameox@latest update

update --check は、設定を変更せずに利用可能な更新を報告します。更新時には各クライアントのプロバイダー固有の追加設定と設定値が保持され、リリースの固定バージョンを変更する前に新しい環境が検証されます。また、再起動または再接続が必要なクライアントが報告されます。クライアントを 1 つ選択するには --client codex を、ロールバックを含めて特定のリリースを選択するには --version 0.2.8 を使用します。Python CLI でも同じ flameox update コマンドを利用できます。

CLI を直接使用するには、正確なアーティファクトパスまたは明示的なコマンドを渡します。

uvx flameox analyze preview_artifact /absolute/path/to/artifact.json
uvx flameox capture --provider direct --cwd "$PWD" -- python benchmark.py

stdio MCP サーバーを手動で起動するには、次を実行します。

uvx flameox mcp serve

ローカルで開発するには、リポジトリをクローンし、開発用依存関係をインストールして、利用可能なツールを確認します。

git clone https://github.com/morluto/flameox.git
cd flameox
uv sync --extra dev --extra memory --extra trace --extra cpu
uv run flameox mcp inspect

エビデンスとストレージ

分析と、保存しないキャプチャでは、範囲が限定されたセッション用スクラッチ領域を使用します。セッションの analysis_id 値は、追い出されたとき、またはサーバーが停止したときに有効期限が切れます。明示的に保存すると、ユーザーレベルの Flameox データディレクトリが作成され、ネイティブバイト列と正規化されたエビデンスバンドルが SHA-256 で保存されます。別の場所を選ぶには FLAMEOX_DATA_DIR を設定します。保存は任意であり、コンソール出力がすべて保持されることを意味しません。

Flameox は、観測された主張、導出された主張、推定された主張を区別します。プロファイルは調査の指針になりますが、因果関係や性能向上を立証するものではありません。確認的な主張には、代表的なワークロード、宣言されたメトリクスと推定対象、互換性のある識別情報、保存されたサンプル、セマンティックオラクルが必要です。

MCP

MCP サーバーはワークスペースに紐付けられていません。CLI と同じオペレーションレジストリを通じて、名前付きの分析ツールとキャプチャツールを公開します。分析ツールは明示的なソースを受け取り、キャプチャツールは型付きのターゲットとプロバイダーを受け取ります。ツールスキーマでは、各オペレーション固有のフィールドが直接公開されます。flameox mcp inspect でカタログを確認できます。特定のスキーマと例に絞り込むには --tool TOOL_NAME を使用します。契約全体と現在のツールカタログはインターフェースガイドにあります。

ツールは、失敗や復旧アクションも含め、範囲が限定された結果全体をインラインで返します。保存されたエビデンスには永続的な evidence_id があり、inspect_evidence はその秘匿化されたメタデータとリプレイソースをインラインで返します。

キャプチャに渡すのは argv であり、シェル文字列ではありません。直接ターゲットには、絶対パスの作業ディレクトリと、範囲を限定した環境変数の上書きを指定します。結果には next_page が含まれる場合があります。その名前付き分析ツールと引数を変更せずに再実行してください。キャプチャの続きでは収集済みのアーティファクトを読み取り、ターゲットは再実行しません。MCP の処理は進行中のリクエストに紐付くため、キャンセルが直接適用され、再起動後も存続するデタッチ済みジョブはありません。

ドキュメント

• アーキテクチャでは、プロセスとパッケージの境界を説明します。
• ストレージとエビデンスでは、保存と来歴を定義します。
• 調査では、実験、比較、エビデンスの品質について説明します。
• アダプターでは、プロバイダーとの互換性と統合ポリシーについて説明します。
• ランタイムの安全性では、制限、復旧、整合性、プライバシーについて説明します。
• インターフェースでは、CLI と MCP の契約を定義します。
• テストでは、テストの選定と既知の証明上の不足について説明します。

開発

Flameox の実行には Python 3.12 以降が必要で、コミット済みの uv.lock を使用します。開発環境のセットアップとコントリビューションのガイダンスについては、 CONTRIBUTING.mdをご覧ください。

uv run ruff check src tests tools
uv run ruff format --check src tests tools
uv run mypy src tests tools
uv run pytest -q

Flameox は MIT License の下でライセンスされています。