hierarchical-codex

hierarchical-codex は、ネイティブ Codex サブエージェントのための決定論的 MCP コントロールプレーンです。Codex は依然として spawn_agent により UI に表示される Sol → Terra → Luna スレッドを作成します。このプロジェクトは、それらのスレッドを囲む永続状態、ポリシーゲート、予算、アーティファクト、エビデンスワークフロー、およびリカバリプロトコルを提供します。

ステータス: エンジニアリング MVP。コントロールプレーン、Codex プロジェクト統合、フック、テスト、運用ドキュメントは実装済みです。ターゲットとなる各 App/IDE デプロイメントで、モデルの利用可能性と正確な Codex コアバージョンを検証してください。

設計上の選択

このプロジェクトは、1 つの明確なルートに従います:

モデル駆動のスポーン、コードによる制約の強制。

Codex native execution plane
  spawn_agent / wait_agent / send_message / Subagents UI
                  |
                  | task_id in TaskEnvelope
                  v
TypeScript MCP control plane
  SQLite task ledger / leases / budgets / artifacts / evidence / audit
                  ^
                  |
Codex Skills + Profiles + Hooks
  orchestration policy / model-effort routing / spawn veto / stop checks

MCP とフックはネイティブスレッドを作成しません。Sol または Terra モデルがネイティブの spawn_agent を呼び出し、コードが周囲のワークフローを検証して記録します。

Related MCP server: dingdawg-governance

実装済み機能

• 楽観的バージョンを持つミッションおよびタスク台帳。

• 直接親ロールポリシー: Sol ディレクター → Terra コーディネーター → Luna リーフ。

• モデル/エフォートマトリックス:

  • Sol: high, xhigh, max

  • Terra: xhigh, max

  • Luna: high, xhigh, max

• 依存関係を考慮した準備状態と、上限付きの子割り当て。

• 期限付きワーカーリース、ハートビート、解放、および安全な回収。

• 階層的なトークン、コスト、ウォールタイム、ツール呼び出し、子カウントの予算。

• コンテンツアドレス方式のアーティファクトストレージと、上限付き読み取り。

• 候補 → チェック済み → 検証済み → コミット済みのエビデンスゲート。

• プロデューサー/レビュアーの分離。

• リクエストハッシュによる冪等な変更と、追記専用の監査イベント。

• 再起動またはコンテキスト圧縮後のリカバリスナップショット。

• プロジェクトスコープの Codex スキル、エージェントプロファイル、MCP 設定、およびフック。

要件

• Node.js 22.5 以降。開発では Node 26 を使用しています。

• Codex ライフサイクルフック用に Python 3.10 以降。

• Codex 0.148.0 以降が推奨される本番ベースラインであり、ネイティブのマルチエージェントツール、カスタムエージェント、MCP、フックを備えています。

• .codex/config.toml とプロジェクトフックが読み込まれる、信頼された Codex プロジェクト。

クイックスタート

cd "/mnt/tools/others/codes/web project/hierarchical-codex"
npm install
npm run check
npm run doctor

次に:

1. Codex App、Codex CLI、または Codex VS Code 拡張機能で このリポジトリのルート を開きます。npm run doctor はスキルを ChatGPT にインストールしません。App はこのフォルダをワークスペースとして使用する必要があります。

2. プロンプトが表示されたらプロジェクトを信頼します。信頼されていないプロジェクトでは .codex スキルが非表示になります。

3. gpt-5.6-sol で 新しい ルート会話を開始します (スキルは起動時に読み込まれます)。

4. $ を入力して prism を選択するか、$prism <mission> を呼び出します。ピッカーが空の場合でも、AGENTS.md がルート Sol に指示を与えます。

5. Subagents UI でネイティブの子アクティビティを確認し、MCP ツールを通じて永続状態を確認します。

VS Code Codex 拡張機能または CLI で 他のフォルダ からフルスタックを使用するには、npm run build の後に npm run install:user を実行します。docs/USER_INSTALL.md を参照してください。このリポジトリの .codex/config.toml を ~/.codex にコピーしないでください。Sol がデフォルトモデルとして固定され、通常のサブエージェントがブロックされます。

プロジェクトの MCP 設定は、リポジトリルートを作業ディレクトリとして node dist/cli.js を起動します。ソース変更後は npm run build を実行してください。

開発コマンド

npm run dev          # Run the stdio MCP server from TypeScript
npm run doctor       # Validate runtime and Codex integration files
npm run test         # Unit and integration tests
npm run typecheck    # Strict TypeScript checks
npm run lint         # ESLint
npm run format       # Prettier
npm run build        # Compile dist/
npm run check          # Full local quality gate
npm run install:user   # Install skill, agents, hooks, and MCP into ~/.codex
npm run doctor:user    # Verify the user-global install
npm run uninstall:user # Remove the managed user-global files

MCP サーバーはプロトコルメッセージを stdout に書き込みます。アプリケーションログは stderr を使用する必要があります。stdout へのログ出力は stdio MCP トランスポートを破損させます。

ランタイム状態

デフォルトでは、状態はプロジェクトローカルであり、Git によって無視されます:

.hierarchical-codex/
├── control-plane.sqlite
└── artifacts/
    └── <sha-prefix>/<sha256>

ユーザーグローバルインストール (npm run install:user) は、台帳を ~/.local/share/hierarchical-codex/ に保存するため、Codex MCP サンドボックスが書き込めます。そのディレクトリが書き込み可能でない場合、サーバーは一時パスにフォールバックし、選択したホームを stderr に記録します。

設定環境変数:

• HIERARCHICAL_CODEX_HOME

• HIERARCHICAL_CODEX_DB

• HIERARCHICAL_CODEX_ARTIFACTS

• HIERARCHICAL_CODEX_MAX_ARTIFACT_BYTES

• HIERARCHICAL_CODEX_DEFAULT_LEASE_SECONDS

• HIERARCHICAL_CODEX_MAX_LEASE_SECONDS

• HIERARCHICAL_CODEX_EVENT_PAGE_SIZE

MCP ツール

ミッション:

• mission_create

• mission_get

• mission_close

タスクとリース:

• task_allocate

• task_get

• task_claim

• task_start

• task_heartbeat

• task_release

• task_block

• task_fail

• task_cancel

• task_supersede

• task_set_effort

• task_commit

アーティファクトとエビデンス:

• artifact_put

• artifact_get

• result_submit_candidate

• result_check

• result_verify

会計とリカバリ:

• budget_report

• recovery_snapshot

契約については docs/API.md を、オーケストレーションシーケンスについては docs/PROTOCOL.md を参照してください。

リポジトリ構造

.agents/skills/             Codex orchestration Skill
.codex/agents/              Sol/Terra/Luna custom profiles
.codex/hooks/               Python policy gates
.codex/config.toml          MCP and native agent configuration
src/domain/                 State and policy definitions
src/infra/                  SQLite repository and artifact storage
src/mcp/                    MCP tool registration
tests/                      Control-plane, policy, and hook tests
docs/                       Architecture, protocol, operations, ADRs, records

重要な境界

• 外部 MCP コードは内部のネイティブ spawn_agent レジストリを呼び出せません。

• フックはコンテキストを拒否、書き換え、または追加できますが、SubagentStart は作成後のサブエージェントを防ぐことはできません。

• ネイティブ UI の状態は観察用です。SQLite が永続的なワークフローソースです。

• この MVP はシングルホストです。SQLite は変更を直列化しますが、分散コンセンサスシステムではありません。

• トークン使用量はエージェント/ホストによって報告されます。MCP サーバーはモデルトークンを独立して計測できません。

• このリポジトリは現在 UNLICENSED です。外部配布の前に明示的なライセンスを追加してください。

ドキュメント

• アーキテクチャ

• プロトコル

• MCP API

• Codex 統合

• ユーザーグローバル VS Code / CLI インストール

• 運用

• セキュリティモデル

• 開発ガイド

• テスト戦略

• ロードマップ

• 変更履歴

• 実装記録

• アーキテクチャ決定