hierarchical-codex

hierarchical-codex ist eine deterministische MCP-Steuerungsebene für native Codex-Subagenten. Codex erstellt weiterhin sichtbare Sol → Terra → Luna-Threads mit spawn_agent; dieses Projekt liefert den dauerhaften Zustand, Richtlinien-Gates, Budgets, Artefakte, Evidenz-Workflow und das Wiederherstellungsprotokoll rund um diese Threads.

Status: Engineering-MVP. Die Steuerungsebene, Codex-Projektintegration, Hooks, Tests und Betriebsdokumentation sind implementiert. Validieren Sie die Modellverfügbarkeit und die exakte Codex-Kernversion auf jeder Ziel-App/IDE-Bereitstellung.

Designentscheidung

Das Projekt folgt einem expliziten Weg:

Modellgesteuerte Erzeugung; code-erzwungene Einschränkungen.

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 und Hooks erstellen keine nativen Threads. Das Sol- oder Terra-Modell ruft natives spawn_agent auf; Code validiert und protokolliert den umgebenden Workflow.

Related MCP server: dingdawg-governance

Implementierte Fähigkeiten

• Missions- und Aufgabenregister mit optimistischen Versionen.

• Richtlinie für direkte Elternrolle: Sol-Direktor → Terra-Koordinator → Luna-Blatt.

• Modell-/Aufwandsmatrix:

  • Sol: high, xhigh, max

  • Terra: xhigh, max

  • Luna: high, xhigh, max

• Abhängigkeitsbewusste Bereitschaft und begrenzte Kind-Zuweisung.

• Ablaufende Worker-Leases, Heartbeats, Freigabe und sichere Rückgewinnung.

• Hierarchische Token-, Kosten-, Wanduhrzeit-, Tool-Aufruf- und Kind-Anzahl-Budgets.

• Inhaltsadressierte Artefaktspeicherung mit begrenzten Lesevorgängen.

• Kandidat → geprüft → verifiziert → committet Evidenz-Gates.

• Produzent/Prüfer-Trennung.

• Anforderungsgehashte idempotente Mutationen und Nur-Anhängen-Überwachungsereignisse.

• Wiederherstellungs-Snapshots nach Neustart oder Kontextkompaktierung.

• Projektspezifische Codex-Skill-, Agentenprofile, MCP-Konfiguration und Hooks.

Anforderungen

• Node.js 22.5 oder neuer. Node 26 wird in der Entwicklung verwendet.

• Python 3.10 oder neuer für Codex-Lifecycle-Hooks.

• Codex 0.148.0 oder neuer ist die empfohlene Produktionsbasislinie, mit nativen Multi-Agenten-Tools, benutzerdefinierten Agenten, MCP und Hooks.

• Ein vertrauenswürdiges Codex-Projekt, damit .codex/config.toml und Projekt-Hooks geladen werden.

Schnellstart

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

Dann:

1. Öffnen Sie dieses Repository-Stammverzeichnis in der Codex-App, der Codex-CLI oder der Codex-VS-Code-Erweiterung. npm run doctor installiert die Skill nicht in ChatGPT; die App muss diesen Ordner als ihren Arbeitsbereich verwenden.

2. Vertrauen Sie dem Projekt, wenn Sie dazu aufgefordert werden. Nicht vertrauenswürdige Projekte deaktivieren .codex-Skills.

3. Starten Sie eine neue Stammkonversation mit gpt-5.6-sol (Skills werden beim Start geladen).

4. Tippen Sie $ und wählen Sie prism aus, oder rufen Sie $prism <Mission> auf. Wenn die Auswahl leer ist, weist AGENTS.md das Stamm-Sol dennoch an.

5. Inspizieren Sie native Kind-Aktivitäten in der Subagenten-UI und den dauerhaften Zustand über die MCP-Tools.

Um den vollständigen Stack aus anderen Ordnern in der VS-Code-Erweiterung oder der CLI zu verwenden, führen Sie npm run install:user nach npm run build aus. Siehe docs/USER_INSTALL.md. Kopieren Sie die .codex/config.toml dieses Repositorys nicht nach ~/.codex; das würde Sol als Standardmodell festlegen und normale Subagenten blockieren.

Die Projekt-MCP-Konfiguration startet node dist/cli.js mit dem Repository-Stammverzeichnis als Arbeitsverzeichnis. Führen Sie npm run build nach Quellcodeänderungen aus.

Entwicklungsbefehle

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

Der MCP-Server schreibt Protokollnachrichten an stdout. Die Anwendungsprotokollierung muss stderr verwenden; stdout-Protokollierung beschädigt den stdio-MCP-Transport.

Laufzeitzustand

Standardmäßig ist der Zustand projektspezifisch und wird von Git ignoriert:

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

Benutzerweite Installation (npm run install:user) speichert das Register unter ~/.local/share/hierarchical-codex/, sodass Codex-MCP-Sandboxes darauf schreiben können. Wenn dieses Verzeichnis nicht beschreibbar ist, fällt der Server auf einen temporären Pfad zurück und protokolliert das gewählte Home-Verzeichnis auf stderr.

Konfigurationsumgebungsvariablen:

• 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-Tools

Mission:

• mission_create

• mission_get

• mission_close

Aufgabe und Lease:

• 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

Artefakte und Evidenz:

• artifact_put

• artifact_get

• result_submit_candidate

• result_check

• result_verify

Buchhaltung und Wiederherstellung:

• budget_report

• recovery_snapshot

Siehe docs/API.md für Verträge und docs/PROTOCOL.md für das Orchestrierungsprotokoll.

Repository-Struktur

.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

Wichtige Grenzen

• Externer MCP-Code kann das interne native spawn_agent-Register nicht aufrufen.

• Hooks können Kontext verweigern, umschreiben oder hinzufügen, aber SubagentStart kann einen Subagenten nach der Erstellung nicht verhindern.

• Der native UI-Zustand ist beobachtend; SQLite ist die dauerhafte Workflow-Quelle.

• Dieses MVP ist Single-Host. SQLite serialisiert Mutationen, ist aber kein verteiltes Konsenssystem.

• Die Token-Nutzung wird von Agenten/Hosts gemeldet; der MCP-Server kann Modell-Token nicht unabhängig messen.

• Das Repository ist derzeit UNLICENSED; fügen Sie vor externer Verteilung eine ausdrückliche Lizenz hinzu.

Dokumentation

• Architektur

• Protokoll

• MCP-API

• Codex-Integration

• Benutzerweite VS-Code-/CLI-Installation

• Betrieb

• Sicherheitsmodell

• Entwicklungsleitfaden

• Teststrategie

• Roadmap

• Änderungsprotokoll

• Implementierungsprotokoll

• Architekturentscheidungen