BoundedRelay

BoundedRelay를 사용하면 Claude Code가 범위가 명확히 지정된 작업을 MCP를 통해 로컬에 설치된 Codex CLI에 넘길 수 있습니다. 호출은 작업 핸들과 함께 즉시 반환됩니다. 그러면 Claude는 워커가 무엇을 하고 있는지 표시하고, 다음 실제 업데이트를 효율적으로 기다리며, 결과를 검색하거나 작업을 취소할 수 있습니다.

Claude Code  ── local MCP/stdio ──>  BoundedRelay  ── codex exec --json ──>  Codex
                                             │
                                             ├─ policy and resource limits
                                             ├─ deterministic SDD routing
                                             ├─ content-addressed dual review
                                             ├─ sanitized live activity
                                             └─ isolated proposal clone

지원되는 v0.1 토폴로지는 의도적으로 단방향입니다: Claude Code → BoundedRelay → Codex. BoundedRelay는 Codex에서 Claude로의 반환 경로를 제공하지 않으며, 워커는 생성된 변경 사항을 소스 저장소에 적용하지 않습니다.

[!IMPORTANT] BoundedRelay는 독립적인 커뮤니티 프로젝트입니다. Anthropic 또는 OpenAI와 제휴, 보증, 유지보수 관계가 없습니다. Claude, Claude Code, Codex, OpenAI는 각 소유주의 상표입니다.

0.1.0 버전은 로컬 개발 릴리스입니다. npm 패키지는 아직 게시되지 않았으며, v0.1에는 원격 서비스, 데몬, 데이터베이스, 영구 작업 저장소 또는 감사 원장이 없습니다.

BoundedRelay를 사용하는 이유

• 고정되지 않고 보이는 상태: 안전한 활동 라벨, 이벤트 카운터, 경과 시간, 마지막 업데이트 이후 경과 시간, 대기열 위치 및 리비전 인식 폴링.

• 기본적으로 읽기 전용: 분석은 항상 Codex의 read-only 샌드박스를 요청합니다.

• 제한된 권한: 서버가 작업공간 루트, 모델 오버라이드, 환경 전달, 타임아웃, 동시성, 출력 및 패치 한도를 소유합니다.

• 변경 전 검토: 제안 모드는 일회용 클론에서 작동하고, 결과 패치를 검증하며, 소스 작업 트리에 적용하지 않습니다.

• 적응형 작업 분할: 선택적 SDD 라우터는 먼저 최상의 버전별 작업 종류/레인 적합성을 선택하고, 적합성이 동률일 때만 선호도와 중립적 비율을 사용하며, 각각 최대 한 명의 작성자를 가진 의존성 안전 웨이브를 생성합니다.

• 체크포인트 실행: 선택적 Spec Kit 팩은 검증된 경로를 execution.json으로 변환하고, 한 번에 정확히 하나의 의존성 웨이브를 실행하며, 각 작성자 체크포인트가 활성 기준선을 직접 부모로 하는 하나의 비-병합 커밋이어야 합니다.

• 독립적 엄격 검토: 분리된 읽기 전용 클론에서 새로운 스키마 제약 Codex 검토 전에 Claude 호스트 증거가 고정되며, 두 승인 모두 하나의 현재 콘텐츠 주소 지정 봉인과 일치해야 합니다.

• 가짜 진행 상황 없음: BoundedRelay는 관찰된 수명 주기 활동을 보고합니다. 완료율이나 예상 시간을 만들어내지 않습니다.

• 명시적 공개 표면: 기능 탐색, 작업공간 검사, 라우팅, 검토, 제출, 상태, 결과, 취소 및 기록을 위한 집중된 MCP 도구.

Codex가 작업하는 동안 Claude가 표시할 수 있는 것

codex_worker_status는 다음과 같은 정화된 스냅샷을 반환합니다:

{
  "status": "running",
  "revision": 14,
  "progress": {
    "phase": "working",
    "activity": "running_command",
    "activityLabel": "Codex is running a sandboxed command",
    "eventCount": 8,
    "commandCount": 2,
    "messageCount": 0,
    "lastEventType": "item.started",
    "updatedAt": "2026-08-27T18:30:00.000Z",
    "elapsedMs": 12420,
    "sinceLastUpdateMs": 180
  }
}

상태 표면은 고정된 서버 소유 활동 어휘를 노출합니다. 체인 오브 소트, 명령 텍스트, 도구 인수, 이벤트의 저장소 파일 경로 또는 임의의 Codex 이벤트 페이로드는 노출하지 않습니다.

Related MCP server: cc-in-codex

이 프로젝트가 어디에 적합한가

일반적인 Claude Code-to-Codex 위임의 경우 먼저 OpenAI의 공식 openai/codex-plugin-cc를 평가하세요. Codex 하위 프로세스 주변에 로컬 MCP 정책 경계가 구체적으로 필요할 때 BoundedRelay를 사용하세요.

자세한 공식 플러그인 비교와 더 광범위하고 순위를 매기지 않는 생태계 비교를 참조하세요.

사전 요구 사항

• Node.js >=22.13.0 및 npm;

• PATH에 Git 사용 가능;

• 현재 운영 체제 사용자에 대해 설치 및 인증된 Codex CLI;

• 로컬 stdio MCP 지원이 있는 Claude Code;

• 각 위임 작업에 대한 Git 저장소.

BoundedRelay는 지원되는 codex exec --json 비대화형 인터페이스를 사용합니다. 자격 증명 입력이나 자격 증명 저장소가 없습니다. 저장된 Codex 인증은 일반 사용자 환경을 통해 사용됩니다. 직접 API 토큰 전달은 별도의 옵트인입니다.

소스에서 빠른 시작

패키지는 아직 npm에 없습니다. 이 저장소를 클론하거나 다운로드하여 로컬에서 실행하세요.

1. 로컬 환경 설치, 확인 및 검사

git clone https://github.com/mohammad19974/bounded-relay.git
cd bounded-relay
npm ci
npm run check
node dist/cli.js doctor

doctor는 모델 호출 없이 Node 관련 의존성, Codex 명령 호환성, Git 및 Codex 로그인 상태를 확인합니다.

소비자 저장소를 설치하거나 수정하지 않고 패키징된 Spec Kit 및 Claude Code 통합을 검사하려면:

node dist/cli.js sdd validate
node dist/cli.js sdd path

검증기는 패키징된 파일과 JSON 매니페스트를 확인합니다. Claude Code를 호출하거나 인증하지 않습니다. 별도의 호스트 측 검증 단계는 통합 가이드를 참조하세요.

2. 빌드된 워커를 Claude Code에 등록

셸이 절대 경로를 기록하도록 BoundedRelay 디렉터리에서 이 명령을 실행하세요. 사용자 범위는 Claude Code가 다른 프로젝트를 열 때도 동일한 설치를 사용할 수 있으므로 권장되는 개인 기본값입니다:

WORKER_ENTRY="$(pwd)/dist/cli.js"

claude mcp add \
  --transport stdio \
  --scope user \
  bounded-relay \
  -- node "$WORKER_ENTRY" serve

--scope user는 운영 체제 계정에 개인적이며 저장소에 커밋되지 않습니다. 대신 등록을 한 프로젝트에만 국한하려면 명령을 실행하기 전에 대상 Git 저장소로 변경하고 --scope local을 사용하세요. 로컬 범위는 명령이 실행된 프로젝트에 속합니다.

그런 다음 확인하세요:

claude mcp list

Claude Code 내부에서 /mcp를 실행하세요. bounded-relay가 연결됨으로 표시되어야 합니다.

3. 첫 번째 읽기 전용 위임 실행

Git 저장소 안에서 Claude Code를 열고 요청하세요:

Use bounded-relay to inspect this workspace and start a read-only architecture review.
Poll codex_worker_status with afterRevision so you show each new activity without spam.
When the job completes, retrieve the result and summarize only high-confidence findings.

Claude는 codex_worker_workspace, codex_worker_analyze, codex_worker_status, codex_worker_result를 사용해야 합니다.

macOS, Linux, Windows PowerShell, 프로젝트 범위 구성, 제거, 업그레이드 및 일반적인 설정 실패에 대해서는 전체 설치 및 첫 실행 가이드를 읽으세요.

MCP 도구

안정적인 v0.1 프로토콜/구성 네임스페이스는 codex_worker_* 및 CCW_*로 유지됩니다. 공개 브랜드는 BoundedRelay입니다. 명시적 네임스페이스를 유지하면 계약이 안정화되기 전에 불필요한 호환성 깨짐 마이그레이션을 피할 수 있습니다.

모든 활동 상태, 입력, 출력 및 실패 코드를 포함한 전체 도구 참조를 읽으세요.

안전 계약

분석 모드 — 기본값

• 표준 허용 Git 저장소에서 Codex의 read-only 샌드박스를 요청합니다.

• writePaths 및 expectedRevision과 같은 제안 전용 필드를 거부합니다.

• Codex의 최종 분석과 관찰된 사용량 메타데이터를 반환합니다.

적응형 SDD 라우팅 — 모델 없음

• 파일을 읽거나 모델을 호출하지 않고 제한된 작업 DAG를 검증하고 표준화합니다.

• 먼저 하드 레인 자격을 사용한 다음 버전별 작업 종류 적합성을 사용합니다.

• 적격 선호도는 정확한 기본 적합성 동률에만 적용한 다음 중립적 노력/작업 수 비율을 참조합니다. 50/50을 강제하지 않습니다.

• 정책 버전, 레인 적합성 증거, 결정 단계, 이유, 편차, 안전한 웨이브 및 콘텐츠 지문을 반환합니다.

• 직접 쓰기 권한을 부여하지 않습니다. 각 웨이브에는 최대 한 명의 작성자가 있습니다.

구조화된 SDD 검토 — 읽기 전용

• Codex를 시작하기 전에 정규화된 Claude 호스트 증거를 고정하면서 그 결론은 Codex 프롬프트에 포함하지 않습니다.

• 엄격 모드는 깨끗한 전체 리비전을 요구하고, 정확한 아티팩트 바이트를 봉인하며, 봉인과 일치함이 입증된 분리된 origin 없는 클론에서 Codex를 읽기 전용으로 실행합니다.

• Codex 실행 후 소스를 다시 확인하고 두 독립 검토가 모두 동일한 현재 엄격 봉인을 승인할 때만 통과합니다.

• 초안 모드와 일반 분석은 참고용이며 엄격한 게이트를 충족할 수 없습니다.

제안 모드 — 기본적으로 비활성화

• 서버가 CCW_ENABLE_PROPOSALS=true로 시작할 때만 등록됩니다.

• 깨끗한 소스 트리, 정확한 전체 Git 객체 ID 및 명시적인 저장소 상대 쓰기 경로가 필요합니다.

• 고정된 리비전에서 깨끗한 일회용 클론을 생성합니다.

• 해당 클론 내에서만 workspace-write를 실행합니다.

• 변경된 refs, 변경된 HEAD, 범위 밖 파일, 보호된 경로, 심볼릭 링크 변경, 과도하게 큰 패치 및 과도한 변경 파일 수를 거부합니다.

• 검증된 전체 인덱스 바이너리 패치와 SHA-256 다이제스트를 반환한 다음 클론을 삭제합니다.

• 패치를 소스에 적용하거나 커밋, 푸시, 게시 또는 배포하지 않습니다.

읽기 전용 모드가 작동한 후에만 활성화하세요:

claude mcp remove bounded-relay --scope user

claude mcp add \
  --env CCW_ENABLE_PROPOSALS=true \
  --transport stdio \
  --scope user \
  bounded-relay \
  -- node /absolute/path/to/bounded-relay/dist/cli.js serve

codex_worker_result는 기본적으로 패치 텍스트를 생략합니다. 호출자는 includePatch=true를 요청하고, 반환된 다이제스트를 검증하고, 콘텐츠를 검토한 후 적용 여부를 별도로 결정해야 합니다. 제안을 활성화하기 전에 전체 보안 모델을 읽으세요.

아키텍처

flowchart TB
    Human[Human developer] <--> Host["Claude Code<br/>host orchestrator<br/>user-selected Claude model"]
    Host --> Plan["Spec Kit plan, committed tasks manifest,<br/>reviews, and human gates"]
    Plan --> Route["Verified adaptive route<br/>exact pending-ID coverage"]
    Route --> Ledger["execution.json<br/>dependency-ordered waves"]

    subgraph Relay["BoundedRelay MCP policy boundary"]
        Router["Deterministic router"]
        Review["Codex read-only lane<br/>analysis or detached strict review"]
        Proposal["Codex proposal<br/>revision-pinned disposable clone"]
    end

    Route <--> Router
    Ledger -->|Codex read-only task| Review
    Ledger -->|Codex write task| Proposal
    Ledger -->|claude-host task| Host
    Proposal -->|patch bytes + digest;<br/>never integrated by BoundedRelay| Host
    Host -->|inspect and integrate one writer| Checkpoint["Tested Git tree + exactly one<br/>non-merge checkpoint commit"]
    Checkpoint -->|next exact wave| Ledger
    Checkpoint -->|freeze host findings| Host
    Host -->|fresh strict review request| Review
    Host -->|frozen host evidence| Dual["Same-seal dual-review<br/>verification"]
    Review -->|strict sealed Codex evidence| Dual
    Dual --> Converge["Fail-closed convergence audit<br/>no direct implementation"]
    Converge -->|no new work| Proof["Revalidated proof pack<br/>isolated recheck + atomic handoff"]
    Converge -->|new pending tasks| Restart["Abort stale chain<br/>fresh routed run"]
    Restart --> Plan
    Proof --> Human

Claude Code는 단일 호스트 오케스트레이터입니다. Opus, Sonnet 및 기타 Claude 모델은 이 다이어그램에서 별도의 에이전트가 아니라 사용자가 선택할 수 있는 호스트 모델입니다. BoundedRelay는 Claude를 시작하거나 이러한 모델 선택을 3-모델 오케스트레이션 시스템으로 전환하지 않습니다.

Orchestrator는 Claude Code 호스트가 명령, 아티팩트, 게이트, 공급자 호출 및 승인된 통합을 조정함을 의미합니다. 이는 제3의 모델, 모델 선택기 또는 자동 병합기가 아닙니다. BoundedRelay는 로컬 오케스트레이션 경계이자 Codex 워커 제어 평면입니다. 이를 대칭적인 Claude/Codex 오케스트레이터라고 부르는 것은 그 권한을 과장하는 것입니다.

아키텍처 및 아키텍처 결정 기록을 참조하세요.

계획, 실행 및 검토: BoundedRelay 도입 전과 후

이는 워크플로 아키텍처에 대한 정성적 비교이지 벤치마크가 아닙니다. 실제 정확성, 속도, 토큰 사용량 및 비용은 작업, 모델, 프롬프트, 저장소 및 계정에 따라 달라지며, 어떤 개선이나 절감도 보장되지 않습니다. 예시 노력 포인트나 공급자 비중은 설명용 계획 메타데이터일 뿐, 측정된 사용량, 품질 점수 또는 벤치마크 결과가 아닙니다.

관리되는 경로는 신뢰 경계에서 의도적으로 순차적입니다:

flowchart LR
    S[Specify] --> P[Plan]
    P --> PR[Independent<br/>dual plan review]
    PR --> R[Quality-first<br/>task routing]
    R --> X[Verified execution.json]
    X --> W[Do-while waves<br/>one writer + checkpoint]
    W --> IR[Routing-base-to-HEAD<br/>dual implementation review]
    IR --> V[Fail-closed convergence audit<br/>no direct implementation]
    V -->|no new work| CR[Fresh no-delta<br/>dual review]
    V -->|new pending tasks| NR[Fresh routed run]
    CR --> E[Revalidated proof pack<br/>isolated recheck + atomic handoff]

선택적 Spec Kit 워크플로

이 소스 저장소는 자체의 중요한 변경 사항에 .specify/를 사용하지만, Spec Kit는 의도적으로 BoundedRelay 런타임 종속성이 아닙니다. npm 패키지에는 integrations/ 아래에 독창적인 선택적 Spec Kit 워크플로/확장 및 Claude Code 플러그인이 포함되어 있으며, 둘 중 어느 것도 자동으로 설치하지 않습니다.

이 워크플로는 새로운 Codex 검토 전에 Claude의 호스트 검토를 고정하고, 승인된 작업을 codex_worker_sdd_route를 통해 라우팅하며, routing.json을 검증한 다음 execution.json을 생성합니다. Spec Kit do-while은 표준 의존성 웨이브를 순서대로 실행합니다. 각 웨이브는 이전에 검증된 클린 커밋에서 시작하여, 단일 가능한 작성자 전에 준비된 읽기 전용 작업을 처리하고, 인간 체크포인트가 진행되기 전에 수용된 결과와 확인 영수증을 기록해야 합니다. 기본 5,000베이시스 포인트 Codex 비중은 중립 메타데이터이지 할당량이 아닙니다. 자격과 적합성은 한 레인에 모든 구현 작업을 포함하여 어떤 실제 비중도 합법적으로 생성할 수 있습니다.

라우팅은 해당 리비전의 정확히 커밋된 tasks.md에서 준비됩니다. 표준 체크박스 작업 ID(T### 또는 더 긴 것)는 콘텐츠 주소 지정 매니페스트를 구성하며, 할당은 완료되었거나 임의로 만든 ID를 라우팅하지 않고 모든 미완료 ID를 정확히 한 번씩 포함해야 합니다. 승인된 계획-검토 리비전은 해당 작업 체크포인트의 조상이어야 합니다. spec.md와 plan.md는 변경되지 않아야 하며, 라우팅을 계속하기 전에 완전한 엄격 계획 증거가 재검증됩니다.

확인 영수증은 명령, 출력, 작업 디렉터리, 종료 상태 0, 타임스탬프 및 테스트된 정확한 Git 트리에 대한 비공개 처리된 코디네이터 증명 다이제스트 기록입니다. 작성자 영수증은 해당 웨이브의 체크포인트 트리와 일치해야 하며, 수렴 영수증은 봉인된 검토 트리와 일치해야 합니다. 이는 서명된 CI 증명이 아니며, 원시 출력을 포함하지 않고, 코디네이터가 주장된 명령을 실행했음을 독립적으로 증명할 수 없습니다.

Codex 쓰기 슬라이스는 격리된 제안으로 유지됩니다. 정확한 패치 바이트는 무시되는 실행-로컬 patches/<task-id>.patch에만 보관됩니다. 실행 검증기는 다이제스트를 다시 계산하고, 해당 바이트를 활성 기준선의 일회용 Git 인덱스에 적용하며, 결과 트리가 체크포인트 트리와 같아야 합니다. 각 작성자 체크포인트는 활성 기준선을 유일한 부모로 하는 정확히 하나의 non-merge 커밋이어야 합니다. Claude Code 또는 인간 코디네이터가 패치를 검사하고 통합합니다—BoundedRelay는 절대 그렇게 하지 않습니다. 거부된 게이트는 해당 증거 체인을 중단합니다. 아티팩트나 코드를 수정하고 새 실행을 시작하십시오. 거부된 라우트, 실행 원장, 검토 또는 증명 팩을 재사용하지 마십시오.

모든 Codex 실행 결과는 model과 reasoningEffort를 기록하며(라우트가 서버 기본값을 사용할 때 null 포함), 둘 다 라우팅된 정책과 정확히 일치해야 합니다. Critical Claude-호스트 작업은 후속 Codex 교차 검토 정책을 명시적으로 허용 목록에 있는 gpt-5.6-sol / ultra 프로필로 강제합니다. 사용 불가능하면 폐쇄적으로 실패합니다. 호스트 모델은 사용자가 Claude Code에서 선택한 그대로 유지됩니다.

구현 검토는 승인된 라우팅 기준 리비전과 최종 HEAD를 비교하고 256개 초과 변경 경로의 범위를 거부합니다. 수렴은 폐쇄적 실패 방식입니다. 감사만 수행하며 직접 구현하지 않습니다. 새 대기 작업을 추가하면 현재 증거 체인이 중단되고 해당 작업은 새 라우트와 웨이브 실행이 필요합니다. 변경 없음 결과만 승인된 구현 리비전을 기반으로 한 무-델타 검토로 진행할 수 있습니다. 구현 및 수렴의 경우, 고정된 호스트 검토 ID가 실행, 단계, 논스, 봉인된 리비전, 소스-증거 다이제스트, 확인 다이제스트 및 준비된 Codex 검토 정책을 바인딩합니다. 최종 다이제스트 전용 proof-pack.json은 전체 라우팅 프로젝션, 정확한 실행-대-구현-대-수렴 소스 체인, 과거 웨이브 체크포인트, 엄격 증거 및 현재 수렴 신선도를 정적으로 재검증합니다. 프롬프트나 원시 공급자 출력을 복사하지 않고 다이제스트와 수용된 식별자를 인덱싱합니다.

증명 승인 후, Claude는 실행-로컬 handoff-draft.md만 작성합니다. 검증자는 최종 리비전과 실행 증거를 격리된 Git 클론에 복사하고, 거기서 증명을 재검증하며, 초안의 정확한 바인딩 마커를 확인하고, .specify/agents/HANDOFF.md를 원자적으로 게시합니다. 동일한 유효한 초안으로 검증을 반복하는 것은 멱등적입니다. 공급자 작업을 다시 실행하지 않습니다.

claude-host는 항상 Claude Code에서 선택된 모델을 의미합니다. BoundedRelay는 Claude를 실행하거나, Opus/Sonnet을 선택하거나, 호스트가 선언한 모델 라벨을 검증하지 않습니다. 모든 Critical 라우트는 명시적으로 허용 목록에 있는 gpt-5.6-sol / ultra Codex 레인을 하나 요구합니다. Codex가 작업을 소유하면 실행, claude-host가 소유하면 교차 검토입니다. 프로필을 사용할 수 없으면 조용히 대체하지 않고 실패합니다.

로컬 로딩, 워크플로 증거, 엄격-게이트 규칙, 복구 및 제거에 대해서는 전체 Spec Kit 통합 가이드를 사용하십시오.

구성

안전한 기본값은 프로젝트 구성이 필요 없습니다.

비밀을 전달하거나 제안을 활성화하기 전에 구성을 읽으십시오.

BoundedRelay가 주장하지 않는 것

• 객관적으로 “최고”인 모델을 선택하지 않습니다. 선택적 모델 및 추론 값은 명시적이고 서버 허용 목록에 있는 선택으로 유지됩니다.

• 더 나은 코드, 더 낮은 토큰 사용량 또는 더 낮은 비용을 보장하지 않습니다.

• 로컬 확인 영수증, 모델 메타데이터 또는 패치-대-트리 일치를 서명된 CI/공급자 증명이나 정확성 증명으로 바꾸지 않습니다.

• 정확한 매니페스트 적용 범위는 기록된 대기 ID가 라우팅되었음을 증명할 뿐, tasks.md가 완전하거나 그 작업이 잘 설계되었음을 증명하지 않습니다.

• High/Critical 차단은 기록된 구조화된 발견 사항에 적용됩니다. 검토자 누락을 감지할 수 없습니다.

• 격리된 핸드오프 재검증과 원자적 이름 변경은 핸드오프에 서명하거나 나중에 무관한 프로세스가 이를 변경하는 것을 막지 않습니다.

• 비공개 사고 과정을 진행 상황으로 노출하지 않습니다.

• stdio 서버 프로세스가 종료된 후 작업을 유지하지 않습니다.

• 수동으로 또는 무관한 도구에 의해 이루어진 쓰기를 막지 않습니다.

• Codex를 오프라인으로 만들거나 공급자 보존 정책을 변경하지 않습니다.

• 원격 상태를 자동 적용, 커밋, 푸시, 게시, 배포 또는 변경하지 않습니다.

문서

• 시작하기

• 문서 색인

• 아키텍처

• 보안 모델

• 실시간 상태 및 MCP 도구

• 구성

• 호환성

• Spec Kit 통합

• 생태계 비교

• 문제 해결

• 개발

• 로드맵

• 레시피

• 브랜드 자산 및 생성 노트

프로젝트 상태

0.1.0은 의도적으로 사전 안정 버전입니다. 계약은 1.0.0 이전에 변경될 수 있습니다. 업그레이드 전에 CHANGELOG.md 및 호환성 노트를 확인하십시오.

기여, 보안 및 지원

• 풀 리퀘스트를 열기 전에 CONTRIBUTING.md를 읽으십시오.

• 취약점은 SECURITY.md를 통해 비공개로 신고하십시오.

• 지원 범위와 진단 세부 정보는 SUPPORT.md를 사용하십시오.

라이선스

MIT