간체 중국어 · Documentation · Security
Coordinate Agents는 Codex와 Antigravity 협업을 위한 로컬 Web Workspace입니다.
npm 3.0.1은 Web 우선 배포판입니다: 페어링된 터미널, 프로젝트/작업 지속성 및 경량 역할 프롬프트를 갖춘 작고 독립적인 작업대입니다.
npx @hogancv/coordinate-agents@latest web
# 폴더와 포트 선택 (0은 사용 가능한 포트):
npx @hogancv/[email protected] web --root "/path/to/project" --port 3000
Node.js >=18, Git, 그리고 Codex/Antigravity CLI를 별도로 설치하고, 작업을 시작하기 전에 각 CLI에 로그인해야 합니다. 출력된 localhost URL을 열어 사용하세요. agy-proxy와 같은 사용자 지정 명령은 터미널 설정을 사용하여, Codex 모델 및 추론을 활용할 수 있습니다.
작업을 생성하고, Codex에 요구 사항을 입력한 다음, 이를 workspace-message를 통해 작업의 Antigravity로 전송하도록 합니다. Codex는 응답을 검토하고 사용자에게 보고합니다. 여러 프로젝트, 원시 터미널 I/O, 크기 조정(resize), 닫기/재시작(close/restart), 새로고침 및 독립적인 세션 호스트(Session Hosts)에 대한 재연결은 계속 사용할 수 있습니다.
Node 18은 소유된 stdio 폴백을 유지합니다. Windows Node >=20에서는 npm 3.0.1이 node-pty를 선택하기 전에 폐기 가능한, 분리된 세션 호스트에서 네이티브 PTY 시작 및 실제 TTY 동작을 검증합니다. 실패하거나 시간 초과된 프로브는 소유 프로세스 정리(owned-process cleanup)가 확인된 후에만 stdio 폴백을 선택하며, 실제 세션 실패 시 에이전트 작업은 자동으로 재시도되지 않습니다. 세션 진단에는 backend가 포함됩니다.
폴백은 제한된 I/O/수명 주기를 보존하지만, 실제 터미널이 아니므로 네이티브 TUI나 자식 관찰 크기 조정(child-observed resize)을 제공할 수 없습니다.
GitHub Plugin / Legacy CLI / MCP / Task Graph 소스는 로컬 우선 조정 프로토콜 및 런타임을 포함하여 여전히 완전합니다.
구조화된 협업을 위해 GitHub Plugin을 설치하세요. 이 버전은 독립적으로 관리됩니다 (현재 2.4.0). npm 3.x는 플러그인 매니페스트(Plugin manifests), 스킬 리소스(Skill resources), MCP, Task Graph, Adapter SDK/conformance/examples, 테스트 및 개발자 도구링을 제외합니다. skills/ 아래에는 필수 실행 시간 모듈과 신뢰할 수 있는 알림 스크립트만 남아 있습니다.
tarball 내에 있습니다. 이는 패키징된 Codex Skill이 아닙니다. 빌드 또는 사전 패키지 단계가 필요하지 않습니다.
| 모드 | 실행 및 보장 사항 |
|---|
| Web Workspace | 새로 생성된 페어링 PTY, 경량 역할 프롬프트, 작업 기반 터미널 메시징. Codex에 요구사항을 입력하면 Antigravity가 구현합니다. 자동 스킬 호출이나 Task/Graph 라이프사이클은 없습니다. |
| Structured Skill / CLI / MCP | Agent Bus 메시지, 영속적인 Task 및 Task Graph, 기록된 구현 증거, 검토 결정, 명시적 복구 기능. |
Web 작업 그룹 상태는 구현 또는 검토 완료가 아닌 터미널 라이프사이클을 설명합니다. 역할 프롬프트는 에이전트의 동작을 안내하며, 강제되는 워크플로우 상태 머신은 아닙니다. 두 모드 모두 해당 워크플로우에 적용 가능한 커밋(commit), 푸시(push), 릴리스(release)에 대한 명시적인 사용자 승인을 유지합니다. Web 프롬프트는 승인 없이 이러한 작업을 금지합니다.
diff 검토 피드백은 각 전송 전에 Codex가 빈 입력 프롬프트 상태임을 확인해야 합니다. 성공적으로 전송하면 해당 확인이 지워집니다. 전송된 피드백을 편집하려면 다시 확인해야 합니다. 파일을 전환하거나, diff를 새로 고치거나, Changes 서랍을 닫는 동안 사전 비행(preflight) 과정 중에는 터미널 입력이 전송되기 전에 보류 중인 피드백이 취소됩니다.
Web Workspace는 Codex와 구성된 Implementer를 로컬의 나란히 배치된 브라우저 작업 공간에서 페어링합니다:
아래의 엔드투엔드(end-to-end) 터미널 기록은 동일한 경량 워크플로우가 작동하는 것을 보여줍니다:
이 기록은 npm run demo에서 가져온 것입니다.
격리된 Git 저장소 내에 있습니다. 그 정제된 소스 트랜스크립트는 assets/demo-transcript.txt에서 확인할 수 있습니다.
유능한 코딩 에이전트는 단독으로 작업할 수 있습니다. 조정(Coordination)은 Codex가 명세 및 검토 경계를 명확하게 유지하는 동안 두 번째 에이전트가 구현하기를 원할 때 유용해집니다.
- Codex는 작업을 명확히 하고, 승인 기준을 기록하며, 작업을 할당하고, 증거를 검토합니다.
- 설정된 Implementer CLI는 소유 실행 세션 내에서 코드를 편집하고 테스트를 실행합니다.
- Agent Bus는 작업(task), 메시지(message), 검토(review), 세션(session), 그리고 복구(recovery) 사실을 로컬에 보존합니다.
- 릴리스 액션은 구현과 분리되어 있으며 명시적인 사용자 승인을 필요로 합니다.
런타임은 자신이 생성한 세션만 소유합니다. 건강한(Healthy) 세션은 검토 재작업에 재사용될 수 있지만, 실패하거나 종료된 세션은 명시적인 새 할당을 필요로 합니다. 상세한 작업, 메시지, 세션 계약은 프로토콜 문서에 있습니다.
공식 GitHub 마켓플레이스에서 플러그인을 설치하세요:
codex plugin marketplace add hogancv/coordinate-agents
codex plugin add coordinate-agents@coordinate-agents
그런 다음 Codex 앱에서 Git 리포지토리를 열고 다음 프롬프트 중 하나로 시작합니다:
Use $coordinate-agents to inspect this repository and explain the available coordination setup.
Use $coordinate-agents to configure my installed Antigravity or other coding-agent CLI as the Implementer.
Use $coordinate-agents to implement this task. Clarify acceptance criteria first, dispatch implementation, then review the result: <task>
플러그인 경로는 전역 npm 설치를 요구하지 않습니다. 선행 조건(prerequisites), 검증(verification), 업그레이드 및 제거 단계는 'Getting Started', 'Install with AI', 그리고 플러그인 엔드투엔드 가이드를 참조하세요.
예를 들어, 다음과 같이 요청한다고 가정해 봅시다:
Use $coordinate-agents to fix the intermittent cache invalidation test. Preserve the public API, add a regression test, and do not release anything.
Codex는 이를 영구적인 작업(durable task)으로 변환하고, 설정된 Implementer 어댑터를 선택하며, 소유 실행 세션을 열거나 재사용하고, 구현 증거를 기다린 후, diff와 테스트를 검토합니다. 검토가 실패하면 동일한 작업을 통해 구체적인 발견 사항을 반환하며, 검토가 성공하더라도 릴리스는 승인되지 않습니다.
- 영구적인 로컬 작업(tasks), 메시지(messages), 검토 결정(review decisions), 그리고 런타임 이벤트(runtime events).
- 선택적 Intent Map v1 쓰기 범위 선언을 포함하는 추가적 작업 그래프(Additive Task Graph) v1 유효성 검사, 제한된 위험 및 리소스 추정치를 갖는 결정론적 충돌 인식 그래프 사전 비행(deterministic conflict-aware Graph Preflight), 명시적인 제한된 다중 웨이브 전진(explicit bounded multi-wave advance), 실행 후 범위 감사(post-execution scope auditing), 격리된 집계 통합/검토(isolated aggregate integration/review), 그리고 작업 트리 및 세션 전반의 사실 기반 복구(facts-first recovery).
- 명시적인 플래너(Planner), 구현자(Implementer), 및 검토자(Reviewer) 역할 경계.
- 정확하게 구성된 CLI 명령어에 대한 어댑터 기반 실행(Adapter-based execution).
- 영구적이고, 제한되며, 검사 가능한 실행 세션.
- 무한 재시도 루프 없이 건강한 컨텍스트를 재사용하는 검토 수정 작업(Review rework).
- 중단된 그래프 실행에 대한 복구(Recovery), 명시적 재개(explicit resume), 제한된 중지(bounded stop), 그리고 소유권 안전 정리(ownership-safe cleanup); 파일 이름/산문 성공 추론 또는 자동 재시도 루프 없음.
- 명시적인 그래프 통합(Explicit graph integration)은 완료된 하위 작업 참조를 검증하고 이를 별도의 검토 작업 트리에서 정렬된 순서로 적용하며; 검토는 오래된 소스 사실이나 커밋되지 않은 집계 변경을 거부하지만, 충돌은 여전히 검사 가능하며 사용자 체크아웃을 절대 수정하지 않음.
- 작업, 세션 및 이벤트에 대한 로컬 Inspector 타임라인.
- 정확한 권한 의미론(authorization semantics)을 갖는 별도의 검토 게이트와 릴리스 게이트.
Task Graph 사용자는 모든 필수 하위 작업이 성공한 후 명시적으로 task graph-integrate를 실행하고, 그런 다음 task graph-review 또는 일치하는 MCP 도구를 사용하여 집계 결정을 검사하고 기록할 수 있습니다. 통합 작업 트리, 소스 참조(source refs), 적용된 커밋(applied commits), 충돌 사실(conflict facts), 및 검토 증거(review evidence)는 영구적입니다. REVIEW_APPROVED 결과가 병합(merge), 푸시(push), 태그(tag), 게시(publish), 배포(deploy), 또는 릴리스를 승인하는 경우는 없습니다.
그래프 생성 시, 사용자는 --intent-map <intent-map.json> 또는 MCP의 intentMap 객체를 추가할 수 있습니다. 이 동반 지도(companion map)는 모든 하위 작업을 정확히 한 번 다루며, 기본값은 `scopePolicy:
declaration.
커버리지가 사용 가능한 경우, 플래닝은 maxConcurrency까지 안정적인 서브태스크-ID 순서를 탐욕적으로 선택하고,
보수적으로 중복되는 쓰기 의도(write intents)는 건너뛰며,
경계가 지정된 WRITE_INTENT_CONFLICT 사실을 반환합니다. 검증된 완료 후, 런타임은 종속성을 잠금 해제하기 전에 커밋된 변경 사항과 커밋되지 않은 변경 사항을 선언(declaration)과 비교합니다. observe
은 드리프트(drift)를 기록하고, warn
도 성공 상태를 유지하면서 INTENT_SCOPE_DRIFT 경고를 노출하며, strict
은 커밋/작업트리(commit/worktree)를 보존하지만 복구 가능한 실패를 기록합니다. 이러한 검사들은 결코 종속성 엣지(dependency edges)를 생성하거나 사용자 체크아웃을 변경하지 않습니다.
번들된 참조 워크플로우는 Planner와 Reviewer로 Codex를 사용합니다. 구현자(Implementers)는 어댑터(adapters)를 통해 선택됩니다:
| 어댑터 | 의도된 용도 |
|---|
antigravity-cli | Google Antigravity CLI, agy-proxy와 같은 정확한 사용자 정의 실행 파일 포함 |
codex-cli | Codex CLI가 외부 런타임으로 명시적으로 구성될 때 |
generic-cli | 로컬에서 구성된 Claude 명령어와 같은 기타 대화형 코딩 CLI |
프로젝트 명령 구성이 사용자 구성보다 우선하며, 사용자 구성은 어댑터 기본값보다 우선합니다. 최종 실행 가능 식별자는 절대 추측되지 않습니다. Codex CLI, Antigravity CLI, 그리고 런타임 비교를 참조하십시오.
GitHub 소스/플러그인 및 npm 2.4.0에서는 adapter-sdk.mjs에서 버전이 지정된 검증 경계(validation boundary)를 노출합니다.
; npm 2.x 사용자는 @hogancv/coordinate-agents/adapter-sdk.mjs를 가져옵니다.
. npm 3.x는 SDK 내보내기 및 준수 리소스를 제거합니다. 계약 v1은 어댑터 식별자, 기능, 감지, 구성 호환성, 인자 배열 실행 계획, 영구 세션 초기 입력 및 실행 정책을 다룹니다. 런타임은 계속해서 실행 파일/경로 검증, 프로세스 및 세션 수명 주기, 경계가 지정된 출력, 영속 상태, 검토 및 출시 게이트를 소유합니다.
공개 Adapter Conformance Kit은 공백 및 셸 메타 문자가 포함된 경로를 포함하여 격리된 임시 루트에서 동일한 Contract v1 검사를 결정론적 가짜 실행 파일에 대해 실행합니다. 이는 제한된 CI 진단만 반환하며 제공업체와 접촉하거나 사용자 구성을 변경하지 않습니다. 명시적인 로컬 모듈은 coordinate-agents adapter register <local-file>로 등록할 수 있습니다.
; 선택된 정규 .mjs,
, .js, 또는 .cjs 경로만 로드되며, 디스크립터/구성 실패는 사용자 및 프로젝트 상태를 변경하지 않습니다. 이 모듈은 현재 Node.js 권한으로 실행되는 신뢰 코드이며, 계약 검증은 악성 JavaScript 샌드박스가 아닙니다. 번들된 Adapter Contract v1 참조를 확인하십시오.
내장 Codex CLI, Antigravity CLI 및 범용 CLI 어댑터는 검증된 Contract v1 디스크립터를 통해 생성되며 동일한 컨포먼스 러너를 통과합니다. 런타임 세션 결정은 동결된(frozen) 디스크립터 기능을 사용하며, 레거시 어댑터 메타데이터 메서드는 여전히 호환됩니다.
제3자 작성자를 위해 External Adapter Author Guide는 공개 임포트, Contract v1 메서드, 오프라인 고정 장치(fixture), 명시적 신뢰 로컬 등록 및 패키지 페이로드를 안내합니다. 완전한 최소 외부 어댑터 예제는 내장 레지스트리 외부에 있으며 제공업체 액세스가 필요하지 않습니다.
저장소 Adapter SDK 수락 게이트는 플러그인(Plugin), 레거시 CLI 또는 공유 Adapter/Session 소스가 변경되거나 명시적인 수동 디스패치 시 독립적인 Legacy Plugin CI에서 실행됩니다. Web npm 버전 증가만으로는 이 매트릭스가 실행되지 않습니다. 이 게이트는 Linux Node.js 18/22 및 macOS/Windows Node.js 22를 다룹니다. Web CI와 격리된 npm tarball 수락은 별도의 책임이 있으므로, CI 커버리지 및 비용을 확인하십시오.
설정 검색(Setup discovery)과 기존 MCP 설정/Task 도구는 동일한 추가적인 adapters를 노출합니다.
레지스트리 스냅샷에는 등록된 외부 ID와 계약(Contract) 기능이 포함됩니다. 디스커버리는 어댑터를 실행하지 않으며, 구성된 외부 에이전트는 오직 자신들의 계약으로 정의된 탐지 사실만을 기여합니다. 설정은 Agent, Adapter, 그리고 실행 가능한 ID를 병합하지 않고도 외부 어댑터를 선택할 수 있으며, 표준 Task/persistent-Session 경로는 정확한 프로젝트 명령어 > 사용자 명령어 > 어댑터 기본 우선순위를 유지합니다.
Web Workspace는 주요 로컬 브라우저 진입점입니다. 폴더에서 실행하면 루프백 전용의 다중 프로젝트 듀얼 터미널 워크벤치가 시작됩니다. Codex 플러그인이나 글로벌 설치가 필요하지 않습니다 (에이전트 CLI는 여전히 구성된 제공업체를 사용합니다):
npx @hogancv/coordinate-agents@latest web --port 3000
이중 언어(zh-CN / en-US)