LoopXは、Claude Code・Codex・Cursorといった複数のAIエージェントホストを横断して、長時間タスクの「状態」を一元管理するOSSカーネルだ。GitHub★4,707・MITライセンスで、個人開発者huangruiteng氏がGitHub Trending掲載中の急成長プロジェクトとして開発している。当サイトが解説してきた「loop-engineering」という設計概念——エージェントの反復をどこで止め、どう再計画し、予算をどう区切るか——を、実際にインストールして動くOSSとして実装したのがLoopXにあたる。本記事ではインストールから loopx doctor / connect / status までを実機で動かし、README上の主張と実際の挙動の差分を検証する。

LoopX control-plane kernelの構成図。State is truth（状態が真実）を中心に、Agent runtimes・Human judgment・Interaction contract・Projection surfaces・Evidence writebackが接続する
LoopX公式が公開する「control-plane board」。状態（state）を中心に、人間の承認・エージェント実行・証跡の書き戻しが循環する構造を示す（出典: huangruiteng/loopx公式README `docs/assets/control-plane-board.svg`）。
30秒でわかる LoopX（2026年8月時点）
  • ・正体：個人開発者huangruiteng氏によるループ状態管理カーネル（Python 3.11+標準ライブラリのみ、ランタイム依存なし）。GitHub★4,707・fork 407・MIT
  • ・何ができる：Claude Code / Codex App / Codex CLI / OpenCode / Cursor等を横断して、goal・todo・quota・承認待ちの状態を `.loopx/registry.json` に一元記録する
  • ・何を代替できない：エージェントの実行そのもの。README自身が「another agent framework ではない」と明言しており、実行はホスト側に委ねる設計
  • ・実測：`curl | bash` インストールから `loopx doctor` 完了まで実測0.5秒（本日Ubuntu 24.04コンテナ・Python 3.11.15で計測）。`loopx connect` は人間の承認待ちAttention Queueを生成して停止した
  • ・注意：contributor 37名でも実装はほぼ作者1人に集中（バス係数1）。pre-1.0（v0.4.6）でもある

この記事では、Claude Codeエコシステムの実装パターンを幅広く解説している Claude Code｜2026年版・インストールからCLAUDE.md・Hooks・本番運用までの実装手引き を土台に、LoopXという具体的な状態管理OSSの中身を掘り下げる。

LoopXとは——Claude Code/Codex/Cursorを横断する状態管理カーネル

LoopXは「エージェントに何をどこまでやらせたか」をホストの種類に関係なく1つのレジストリで管理するためのOSSだ。公式ドキュメントとREADMEを実測した限り、次の3点が設計の核になっている。

・状態は真実（State is truth）：goal・user todo・agent todo・承認待ちゲート・実行履歴・証跡（evidence）をすべて .loopx/registry.json というローカルJSONに集約する
・実行はホスト任せ：Claude Codeの /loop、Codex Appのheartbeat自動化、Codex CLIの /goal、OpenCodeのコマンドファサードなど、実際にコードを書いたりコマンドを叩いたりするのはホスト側のエージェント。LoopXはそれらに「次にやるべきこと」を提示するだけ
・人間の承認がボトルネック：自律実行を許可するかどうか（autonomous=yes/no）を明示的に確認するゲートが標準で入っており、既定では人間の承認待ち状態（quota state = operator_gate）で止まる

長時間稼働エージェントを運用していると、「昨日どこまで進んでいたか」「どのタスクが承認待ちのままか」をエージェントホスト側の会話履歴だけから追うのは難しくなる。Claude Codeでセッションを跨いだり、Codex CLIとClaude Codeを併用したりすると、進捗管理はホストごとに分断されがちだ。LoopXが埋めようとしているのは、まさにこの「AIエージェント 状態管理」の空白で、複数ホストを使い分ける開発者でも1つのレジストリを見れば現在地が分かる、という体験を狙っている。Claude Code loop（/loopコマンドによる反復実行）についても、LoopXが承認ゲートを挟むことで実行のオン・オフを制御する構造になっている点は、後述の実機検証で確認した。

読者の3つの問いへの答え
① 何ができる：Claude Code・Codex・Cursorなど複数ホストにまたがる長時間タスクの進捗・承認待ち・実行履歴を1つのレジストリで追跡できる。② 何を解決する：エージェントホストごとにバラバラだった「今どこまで進んだか」の状態管理を統一し、無人暴走を防ぐ承認ゲートを挟む。③ 何を代替できる：タスク管理・進捗追跡の手作業メモやTodoリストは代替できるが、エージェントの実行エンジン自体は代替しない（Claude Code等が引き続き必要）。

LoopXを実機インストール：doctor・connect・statusの出力を検証する

README「Try LoopX」に沿って、Python 3.11.15・curl・tarが入ったLinux環境（Docker相当のコンテナ）で実際にインストールした。

curl -fsSL https://huangruiteng.github.io/loopx/install.sh | bash
export PATH="$HOME/.local/bin:$PATH"
loopx doctor

インストールスクリプトはGitHub API経由で stable ブランチの最新コミットを解決し、tarballを取得してローカルにリリースを展開する方式だった。実測では以下の点が確認できた。

・インストール自体は数秒で完了し、loopx doctor の実行はtime計測で実測0.517秒（command_available / module_importable / global_registry_writable などのチェックがすべて True）
・stable チャンネルが指すバージョンは v0.4.3だった。一方でGitHub Releases APIで確認できる最新タグはv0.4.6（30リリース目）——つまり curl | bash の既定インストールは「その時点の最新リリースタグ」ではなく「stable として指定されたコミット」を指す。最新機能を試したい場合は LOOPX_REF 環境変数でタグを明示する必要がある
・Python標準ライブラリのみという主張どおり、pip install 等の追加依存インストールは発生しなかった

続けてテスト用ディレクトリで loopx connect → loopx status を実行すると、実行エンジンではなく状態管理レイヤーであることを裏付ける出力が得られた。

mkdir testproj && cd testproj
loopx connect
loopx status

loopx connect はプロジェクトを読み取り専用でスキャンし（”Onboarding Scan”）、シグナルが少ない場合は「まず限定的な repo intake から始めよう」という提案タスクを1件だけ作る。ここで即座にタスクを実行するのではなく、「どの候補を受け入れるか」「自律実行を許可するか（autonomous=yes/no）」「Codex Appのheartbeatを有効にするか」を人間に問い合わせるステップが挟まる。続く loopx status では、この未承認タスクが Attention Queue に quota state=operator_gate（保留中）として表示され、handoff_readiness: ready=False のまま止まっていた——つまり人間が明示的に応答しない限り、エージェントは先に進まない設計を実機で確認できた。

flowchart TD A["loopx connect
初回接続"] --> B["Onboarding Scan
プロジェクトを読み取り専用スキャン"] B --> C["Attention Queue生成
user_todos + agent_todos"] C --> D{"人間が応答したか？
autonomous=yes/no"} D -- 未応答 --> E["quota state = operator_gate
実行は保留のまま"] D -- 承認 --> F["ホスト側エージェントが実行
Claude Code /loop・Codex heartbeat 等"] F --> G["Run History
.loopx/registry.json に書き戻し"] G --> C

実行後にプロジェクト直下へ生成されていたのは .loopx/registry.json のみで、サイズは8KB程度。中身を見ると、goalごとの状態（status・role・adapter.kind・spawn_policy・coordination.requires_parent_approval）がフラットなJSONとして保存されていた。

loopx doctor の出力には “Install Freshness” というブロックもあり、current_version / current_version_tag / release_age_hours / manifest_archive_sha256 といったフィールドで、今インストールされているリリースがどのコミットから作られたか（manifest_source_git_commit）まで追跡できるようになっていた。今回の実測では status: fresh・release_age_hours: 0.0（インストール直後のため）で、requires_upgrade: False と表示された。バージョン管理の透明性という点では、単に --version を表示するだけのCLIより一段細かい情報を返す設計になっている。

{
  "schema_version": "0.1",
  "goals": [{
    "id": "testproj-goal",
    "domain": "project-goal-control-plane",
    "status": "active",
    "role": "controller",
    "adapter": { "kind": "generic_project_goal_v0", "status": "connected" },
    "spawn_policy": { "mode": "default", "allowed": false, "max_children": 3 },
    "coordination": {
      "requires_parent_approval": ["write", "publish", "production-action"]
    }
  }]
}

spawn_policy.allowed: false や requires_parent_approval に write / publish / production-action が並ぶ点からも、書き込み・公開・本番操作の手前には常に承認ゲートを噛ませる設計思想が読み取れる。

LoopXが管理するもの・しないもの：実行エンジンではなく状態管理レイヤー

README上で明言されている境界線は次の通りだ。

・LoopXが管理するもの：goal（目標）・user todo / agent todo・承認ゲート・quota（実行枠）・run history（実行履歴）・evidence（検証結果や成果物への参照）
・LoopXが管理しないもの：コードの実行そのもの、モデル呼び出し、ファイル編集——これらはすべてClaude Code / Codex / Cursor等のホスト側が担う
・LoopXは「another agent framework or a provider-specific orchestration runtime」ではないとREADMEが明言。つまり「LoopXを入れればエージェントが動く」わけではなく、既に動いているエージェントホストに「状態管理」を後付けするツールという位置づけ

LoopXのレイヤー構成図。L4エージェントホスト（Claude Code/Codex/Cursor）、L3 LoopXアダプタ、L2状態管理カーネル、L1ローカルレジストリの4層
LoopXの4層構成（README記載の統合方式・レジストリ構造をもとに編集部が作図）。実行を担うのはL4のホスト側で、LoopX本体はL1〜L3の状態管理に徹する。

READMEには作者自身によるドッグフーディング実績として、200時間超にわたり volcengine/OpenViking へ実際にPRを送り続けた記録が「Evidence」節で公開されている。ただしREADME自身が “not a claim of continuous compute, independent reproduction, a production result” と明記しているとおり、これは作者本人の運用実績＋数件の匿名ユーザー報告であり、第三者による独立検証ではない。誇張せず、あくまで開発者自身の長期実運用ログとして扱うのが正確だ。

OpenVikingリポジトリに対する200時間超のPR/Issue対応トラジェクトリ図。主線A（Focused Fix PR交付）と主線B（Agent/LoopX能力演進）の2系統でPR番号が時系列に並ぶ
作者huangruiteng氏がLoopXを使って `volcengine/OpenViking` へ送り続けたPR群のトラジェクトリ（出典: huangruiteng/loopx公式README掲載の実データ画像）。個々のPR番号・Issue番号が実測値として記録されている。

Claude Code・Codex・Cursorとの統合方法比較

LoopXはエージェントホストごとに専用の統合方式を用意している。README「Start From Your Agent」表を実測ベースでまとめた。

統合先 起動方法 ループの主導権
Claude Code 専用アダプタをインストール後 /loopx <task> → /loop Claude Code純正の/loopをLoopXがゲート
Codex App エージェントに接続を依頼、$loopx <task> または /skills から選択 Codex Appのheartbeat自動化
Codex CLI codex 起動後に接続を依頼 可視の /goal <task_body>（隠れた無人実行は既定で無効）
OpenCode 静的コマンドファサードをインストール OpenCodeコマンドファサード
Cursor / shell / カスタムランナー インストーラ＋loopx doctor 自前のシェル・スケジューラ・ランナー

いずれの経路でも「実行するのはホスト、LoopXは状態管理」という役割分担は変わらない。実機検証では、Claude Codeアダプタ・OpenCodeブリッジは既定インストールではopt-in扱いで導入されず、LOOPX_INSTALL_CLAUDE=1 のような環境変数か install.py --scope project|user の明示指定が必要だった。

この比較表で特に注目したいのはCodex CLIの列だ。他社製の自動化ツールでは「バックグラウンドでエージェントを回し続ける」隠れた無人実行が既定で有効になっているケースが少なくないが、LoopXのCodex CLI統合は /goal <task_body> という可視のコマンドを起点にしており、隠れた無人実行は既定で無効という設計が明記されている。前述の operator_gate による承認待ちと合わせて、「気づいたらエージェントが勝手に大量の変更をコミットしていた」という事故を構造的に避けようとしている点は、複数のエージェントホストを併用する開発者にとって実務上のメリットになりそうだ。

LoopXのstar数とcontributor数の実体評価：バス係数1という現実

star 4,707・fork 407・contributor 37名という数字だけを見ると中規模コミュニティのプロジェクトに見えるが、GitHub API実測ではcontributions数の内訳に明確な偏りがある。

LoopXのcontributor別contributions数バーグラフ。作者huangruitengが4170、2位のcocolordが62、3位以下36名の合計が120
GitHub API `contributors?per_page=100` の実測値。作者1人が全体のcontributionsの大半を占め、2位以下とは2桁の差がある。

・作者huangruiteng氏：4,170 contributions
・2位 cocolord氏：62 contributions（作者の約1.5%）
・3位以下36名：合計でも数十件規模
・ライセンス：MIT。GitHub APIのlicense.spdx_idとLICENSEファイル原文（Copyright (c) 2026 LoopX contributors）、READMEバッジの表記が一致しており、ライセンス表記の齟齬は無い

つまり実態は「個人開発者が主導し、周辺に小規模な貢献が付いている」プロジェクトであり、37名という数字だけで組織的な開発体制を連想するのは早計だ。企業スポンサーの明記もなく、最新版はv0.4.6（30リリース目でもまだ0.x系＝pre-1.0）という点も踏まえ、本番環境への導入は依存リスクとして認識しておく必要がある。一方で、前日にもpushがあり約2.5ヶ月で30リリースを消化するハイペースな開発速度は、個人開発としては非常に活発な部類に入る。

LoopX導入前に知っておきたい注意点

実機検証で見つかった落とし穴
・インストーラが `~/.claude/skills` を書き換える：Claude Codeアダプタ自体は既定でopt-in（未導入）だが、それとは別にインストーラは `~/.claude/skills` と `~/.codex/skills` 配下へLoopX関連のスキルファイルを合計37件生成した（実機検証で確認、`created=37` とログに表示）。Claude Codeを使っている端末でこのインストーラを実行すると、明示的な同意ステップなしにグローバルなスキルディレクトリが変更される点は事前に把握しておきたい
・`stable` チャンネル ≠ 最新リリースタグ：既定の `curl | bash` インストールではv0.4.3が入ったが、GitHub Releases最新タグはv0.4.6だった（本記事執筆時点実測）。最新機能を検証したい場合は `LOOPX_REF` でタグを明示指定する
・「200時間」実績は第三者検証ではない：README自身が明記する限定を超えて「LoopXは200時間動作実績あり」と単純化しないこと
・pre-1.0：v0.4.6の時点でAPI・レジストリスキーマが将来変わる可能性がある

まとめ：loop-engineering概念の「次の一歩」としてのLoopX

ループエンジニアリングとは｜AIエージェントのループ設計5軸と本家OSS実装を解説 や Loop Engineering実践ツールキット解説｜Cobus Greylingが示す7パターンとloop-audit で扱ってきた「停止条件・再計画・予算・自己修正・エスカレーション」という設計軸を、LoopXは「状態をローカルレジストリに集約し、承認ゲートを挟む」という具体的な実装に落とし込んでいる。Claude Code Dynamic Workflows解説：1,000サブエージェント並列とOpus 4.8 が示すような大規模並列実行の文脈でも、「誰が何をどこまで進めたか」を横断的に把握する状態管理レイヤーの必要性は増していくはずだ。

LoopXは「動くエージェントを増やす」OSSではなく、「増えたエージェントの状態を見失わない」ためのOSSだ。実機検証では、承認ゲートによって無人暴走を防ぐ設計・インストーラのグローバル書き換え・`stable`チャンネルとリリースタグの差異、いずれもREADMEの言葉通りではなく実際にコマンドを叩いて初めて分かる挙動だった。導入前には必ず `loopx doctor` で自分の環境の実際のバージョン・チェック結果を確認してから使いたい。

参照ソース

・huangruiteng/loopx（公式リポジトリ・README） — 機能概要・インストール手順・統合方式表
・LoopX Docs（公式ドキュメント） — Getting Started・Developer Book
・LoopX Getting Started Guide — 導入手順の一次ソース