hierarchical-codex

hierarchical-codex는 네이티브 Codex 서브에이전트를 위한 결정적(deterministic) MCP 제어 평면(control plane)입니다. Codex는 여전히 spawn_agent로 UI에 표시되는 Sol → Terra → Luna 스레드를 생성합니다. 이 프로젝트는 해당 스레드를 둘러싼 지속 상태, 정책 게이트, 예산, 아티팩트, 증거 워크플로, 복구 프로토콜을 제공합니다.

상태: 엔지니어링 MVP. 제어 평면, Codex 프로젝트 통합, 훅, 테스트, 운영 문서가 구현되어 있습니다. 모든 대상 App/IDE 배포에서 모델 가용성과 정확한 Codex 코어 버전을 검증하세요.

설계 선택

이 프로젝트는 하나의 명시적 경로를 따릅니다:

모델 주도 스폰; 코드 강제 제약.

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

구현된 기능

• 낙관적 버전을 사용하는 미션 및 태스크 원장(ledger).

• 직접 부모 역할 정책: Sol 디렉터 → Terra 코디네이터 → Luna 리프.

• 모델/노력 매트릭스:

  • Sol: high, xhigh, max

  • Terra: xhigh, max

  • Luna: high, xhigh, max

• 의존성 인지 준비 상태와 제한된 자식 할당.

• 만료되는 작업자 임대, 하트비트, 해제, 안전한 회수.

• 계층적 토큰, 비용, 벽시계 시간, 도구 호출, 자식 수 예산.

• 콘텐츠 주소 지정 아티팩트 저장소와 제한된 읽기.

• 후보 → 확인 → 검증 → 커밋 증거 게이트.

• 생산자/검토자 분리.

• 요청 해시 기반 멱등 돌연변이와 추가 전용 감사 이벤트.

• 재시작 또는 컨텍스트 압축 후 복구 스냅샷.

• 프로젝트 범위 Codex Skill, Agent 프로필, MCP 구성, 훅.

요구 사항

• Node.js 22.5 이상. 개발에는 Node 26을 사용합니다.

• Codex 수명 주기 훅용 Python 3.10 이상.

• Codex 0.148.0 이상이 권장 프로덕션 기준이며, 네이티브 멀티 에이전트 도구, 커스텀 에이전트, MCP, 훅을 지원합니다.

• 신뢰할 수 있는 Codex 프로젝트로 .codex/config.toml과 프로젝트 훅이 로드되어야 합니다.

빠른 시작

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 설치

• 운영

• 보안 모델

• 개발 가이드

• 테스트 전략

• 로드맵

• 변경 로그

• 구현 기록

• 아키텍처 결정