plasma-ai/fractal

fractal – 階層的な自律エージェントループ

何であるか

Python ライブラリおよび CLI で、Git worktree のツリーとして 再帰的 な自律エージェントを実行できます。ツリー内の各ノードは独立したエージェントループであり、サブタスク用に子ノードを生成でき、問題の規模に応じて成長する フラクタル 構造を形成します。
すべての実行はローカルの SQLite データベースに記録され、ターミナルベースの UI（TUI）から確認・制御できます。

動作方法

ルートノード – 現在の Git ブランチが最上位の「ユーザー」ノードとして機能します（独自の worktree は持ちません）。
生成 – /fractal スキル（または fractal CLI）を通じて自然言語の指示を出します。エージェントは指示を解析し、必要なパラメータを尋ね、その後子ノード用の新しい Git worktree を作成します。
反復 – 各ノードは tmux セッション内で自律ループを実行し、サポートされている LLM バックエンド（Claude、Codex、Grok、OpenCode、Oh My Pi）のいずれかを呼び出します。ループは反復、コードのコミット、コマンドの実行、さらなる子ノードの生成が可能です。
制限 – イテレーション数、深さ、子ノード数、時間、コストに関する上限により、すべてのループが制限されます。予算は実行ごとおよびステップごとに強制され、クリーンアップ用の予約もオプションで可能。
追跡 – すべてのイテレーション、ステップ、コスト、シグナルは単一の SQLite ファイルに保存されます。TUI ダッシュボードはツリーを可視化し、リアルタイムのメトリクスを表示し、ノードの一時停止・停止が可能です。

主な機能

再帰的な自己組織化 – ノードがさらにノードを生成でき、システムが問題に応じて構造を適応させます。
複数の LLM バックエンド – Claude、Codex、Grok、OpenCode、Oh My Pi に対応。OpenRouter を通じたオプションルーティングも可能。
細かい制御 – 各ノードごとに最大イテレーション数、最大深さ、タイムアウト、コスト上限、スコープなどを設定可能。
Git を中心としたワークフロー – 各ノードは独自の Git worktree で動作するため、コミットはブランチ単位で隔離され、プッシュまたはローカル保持が可能です。
ターミナル UI – ライブダッシュボード（fractal open）でツリー、コスト、進捗を確認できます。
スキル統合 – Claude Code や Codex エージェントに /fractal スキルをインストール可能。自然言語によるノード生成が可能。
セキュリティ警告 – ノードはデフォルトで権限の確認プロンプトなしで実行されます。README では、信頼できるタスクのみを実行し、可能な限り一時的なホスト上で実行することを推奨しています。

インストール

# PyPI から（パッケージ名は "plasma-fractal" ですが、"fractal" エントリポイントも提供）
pip install plasma-fractal   # または: pip install fractal

# 隔離インストール（pipx、uv）の場合、補助パッケージ "plasma-wiki" もインストール
pipx install plasma-fractal && pipx install plasma-wiki
# または uv で:
uv tool install plasma-fractal --with-executables-from plasma-wiki

インストール後、fractal init で初期化されたプロジェクトルートから fractal open を実行してください（README では初期化済みの fractal を前提としています）。

一般的なワークフロー

# ダッシュボードを開く（ライトテーマはオプション）
fractal open --light

# TUI またはスキルから指示を出します。例：
/fractal spawn name=docgen path=./docs title="APIドキュメントの生成" agent=claude max-iters=5

# システムは以下の処理を行います：
#   • 指示を解析し、不足しているフィールドを尋ねる
#   • ./docs 下に新しい Git worktree を作成
#   • Claude エージェントループを実行する tmux セッションを開始
#   • 各イテレーションを SQLite DB に記録
#   • ダッシュボードで進捗を表示

fractal node stop <name> コマンドや UI とのインタラクションで、ノードの停止・一時停止・調整が可能です。

セキュリティと制限

ノードは 権限の確認プロンプトなしで実行 されます。つまり、LLM は起動ユーザーの権限でホスト上の任意のコマンドを実行できます。README では、信頼できないタスクにはサンドボックスまたは一時的なマシンでの実行を強く推奨しています。
コスト上限は強制されますが、USD での実行ごとのみ。無制限の API 費用を避けるためには適切な max-cost 値を設定する必要があります。
システムは外部の LLM プロバイダーに依存しており、ネットワークアクセスおよび API キー（例：OPENROUTER_API_KEY）が必要です。

ドキュメントとコミュニティ

公式ドキュメント: https://docs.plasma.ai/fractal
PyPI ページ: https://pypi.org/project/plasma-fractal/
ソースコード: https://github.com/plasma-ai/fractal (Apache‑2.0 ライセンス)

誰が使うべきか

大規模なコードベースのリファクタリング、ドキュメント生成、複数ステップの AI ベースタスクに自動的かつ自己組織的なワークフローを求める開発者。
階層的な AI エージェントアーキテクチャを研究する研究者。
既に Claude、Codex、または他のサポートされている LLM を使用しており、Git とのより緊密な統合を望むチーム。

上記のすべての詳細は、リポジトリの README から直接抜粋されています。追加の機能は推測されていません。

plasma-ai/fractal

fractal – 階層的な自律エージェントループ

関連