AgentBridge

상태: 마이그레이션 중이며, 이 README는 이전 구조를 설명합니다.

AgentBridge는 Claude-Code-to-Codex/Antigravity 브리지로 시작했으며, 아래 문서화된 모든 것은 현재도 동작합니다. 지원되는 CLI라면 무엇이든 오케스트레이터가 되고 다른 것은 워커가 되도록 일반화하는 중이며, 라우팅은 하드코딩된 모델 이름 대신 사용자별 프로필로 구동됩니다.

향후 방향은 docs/architecture.md와 docs/roles.md를 참조하세요. 진행 중: 공급자 어댑터 계층 (src/providers/), 라우팅 프로필 (src/profile/), 그리고 agentbridge init 설정 흐름. Cursor 어댑터는 존재하지만 검증되지 않았습니다 — 해당 플래그는 설치된 CLI에서 읽은 것이 아니라 사전 지식으로 작성되었으며, 파일 상단에 그렇게 명시되어 있습니다.

마이그레이션이 완료될 때까지 아래 섹션은 Codex 및 Antigravity 워커에 대해 정확하고, 문서는 설계에 대해 정확하다고 간주하세요.

오케스트레이터

AgentBridge는 /agentbridge … 명령 표면을 MCP 프롬프트로 제공하므로, prompts/list를 지원하는 모든 MCP 클라이언트는 호스트별 명령 파일을 설치하거나 동기화할 필요 없이 서버 자체에서 동일한 명령을 가져옵니다.

이러한 명령 뒤에 있는 원칙은 doctrine/에 있으며 모델을 이름으로 지정하지 않습니다 — 역할별로 라우팅하며, .agentbridge/profile.json은 역할을 사용자가 실제로 설치한 항목에 매핑합니다.

Claude Code가 Codex CLI 및 Antigravity CLI (agy) 에 외부 워커로 작업을 위임할 수 있게 해주는 소형 로컬 stdio MCP 서버 — 이미 로그인한 CLI 세션을 사용하며 API 키가 필요 없습니다.

Claude는 오케스트레이터로 유지됩니다. AgentBridge는 의도적으로 단순한 배관입니다. Claude의 구조화된 요청을 워커 프롬프트로 바꾸고, CLI를 실행하고, 간결한 구조화된 결과를 반환합니다.

User
 └─> Claude Code                      (orchestrator — decides what to delegate)
      └─> AgentBridge MCP tool        (codex_run / antigravity_run)
           └─> codex exec  |  agy --print
                └─> result
           <─ structured MCP result
      <─ Claude inspects the work and continues

Related MCP server: agent-intern

그렇지 않은 것

클라우드 서비스, 웹 UI, 데이터베이스, 데몬, 대시보드, 작업 대기열, 계정 시스템 또는 API 키 관리가 없습니다. Claude Code가 stdio를 통해 시작하고 종료할 때 중지하는 단일 Node 프로세스입니다.

작동 방식

1. Claude는 구조화된 요청(목표, 모드, 모델, 노력, 경로, 계약, 승인 기준 등)과 함께 codex_run 또는 antigravity_run을 호출합니다.

2. AgentBridge는 정확히 해당 필드에서 워커 프롬프트를 조합합니다. 자체 모델을 실행하지 않습니다 — 이것은 추론이 아닌 문자열 조합입니다.

3. 쓰기 범위를 예약하고, git 작업 트리를 스냅샷하고, 인수 배열로 CLI를 생성합니다(shell: false).

4. CLI의 기계 판독 가능 출력을 구문 분석하고, 워커의 최종 결과(내부 추론은 제외)를 추출하고, git 트리를 비교하여 실제로 변경된 사항을 확인하고, 간결한 JSON 결과를 반환합니다.

MCP 호출 한 번 = 워커 시도 한 번. AgentBridge는 절대 재시도하지 않습니다. 다른 시도가 가치가 있는지 여부는 Claude의 결정입니다.

요구 사항

AgentBridge는 Codex 또는 Antigravity 자격 증명을 읽거나, 복사하거나, 내보내거나, 수정하지 않습니다. 로그인한 사용자와 똑같이 CLI를 호출합니다.

설치 및 빌드

npm install

npm run build

npm test

테스트 스위트는 전체적으로 프로세스를 모의 처리하므로 일반적인 npm test는 모델 할당량을 소비하지 않습니다.

Claude Code에 등록

사용자 범위에서 한 번 등록하면 모든 프로젝트에서 사용할 수 있습니다:

claude mcp add --transport stdio --scope user agentbridge -- node D:\Code\Agentbridge\dist\index.js

터미널에서 확인:

claude mcp list

claude mcp get agentbridge

그런 다음 Claude Code 내부에서 /mcp를 실행하여 확인합니다. agentbridge가 연결된 것으로 표시되고 codex_run, antigravity_run, bridge_status의 세 가지 도구가 표시되어야 합니다. 전체 상태 보고서는 Claude에게 bridge_status를 호출하도록 요청하세요.

AgentBridge를 다시 빌드한 경우 Claude Code를 다시 시작하거나(또는 /mcp에서 서버를 다시 연결하여) 새 dist/를 인식하도록 하세요.

프로젝트 디렉터리

워커는 단일 프로젝트 디렉터리에서 실행되고 범위가 지정되며, 다음 순서로 확인됩니다:

1. AGENTBRIDGE_PROJECT_DIR, 그 다음 레거시 CLAUDE_PROJECT_DIR (Claude Code가 내보냄).

2. MCP 클라이언트가 광고하는 첫 번째 file:// 루트.

3. 서버 프로세스의 작업 디렉터리.

bridge_status는 어떤 것이 사용되었는지 보고합니다.

도구

codex_run

모델. 세 개의 슬러그를 주소 지정할 수 있으며 각각은 그대로 CLI에 전달됩니다:

노력 매핑 (오케스트레이터 레이블 → Codex model_reasoning_effort):

매핑은 완전하고 결정적입니다. Codex의 ultra 계층은 의도적으로 노출되지 않습니다. 일부 모델만 제공하며, 세 모델 중 두 모델에서 작동하는 여섯 번째 레이블은 라우팅을 모델에 의존적으로 만들기 때문입니다.

가용성. 시작하기 전에 AgentBridge는 요청된 모델과 노력을 Codex CLI의 자체 모델 카탈로그(CODEX_HOME의 models_cache.json)와 대조하여 확인합니다 — 추론이 아닌 파일 읽기입니다.

• 모델 나열, 노력 나열 → 작업 실행

• 모델은 나열되나 노력이 없음 → invalid_effort, details.supported_efforts 포함

• 모델이 나열되지 않음 → requested_model_unavailable, details.available_models 포함

• 읽을 수 있는 카탈로그가 없음 → 가용성이 unverified라는 경고와 함께 작업이 계속 실행됨

다른 것으로 대체되는 것은 없습니다. 이행할 수 없는 라우팅 결정은 조용히 약한 모델로 대신하는 대신 한 단계로 다시 라우팅할 수 있는 충분한 메타데이터를 포함한 구조화된 오류로 반환됩니다.

구성된 호출은 다음과 같습니다:

codex exec --json --skip-git-repo-check -m <MODEL> -c model_reasoning_effort="<EFFORT>" \
           -s <read-only|workspace-write> -C <PROJECT> -o <tmpfile> --color never

프롬프트는 stdin으로 스트리밍됩니다. 모델, 노력 및 샌드박스는 모든 호출에 전달되므로 실행 시 ~/.codex/config.toml에 설정된 값을 상속하지 않습니다.

analyze 및 review는 Codex의 실제 read-only 샌드박스를 사용합니다 — 쓰기는 단순히 권장되지 않는 것이 아니라 실제로 방지됩니다.

antigravity_run

동일한 스키마이며, 다음이 추가됩니다:

논리적 이름은 실행 시 활성 agy models 목록에 대해 확인됩니다:

Antigravity는 추론 계층을 모델 ID에 인코딩하므로 model + effort는 단일 ID로 확인되며 별도의 --effort 플래그는 전송되지 않습니다 — 둘이 충돌할 수 없습니다. Flash에는 세 가지 계층만 있습니다: extra high 및 max는 요청한 것보다 약한 계층을 조용히 실행하는 대신 invalid_effort를 반환합니다.

Antigravity는 의도적으로 저렴한 Gemini 계층으로 범위가 제한됩니다. agy가 제공하는 Claude 모델은 라우팅 가능한 레이블로 노출되지 않습니다 — Claude급 추론의 경우 실제 샌드박싱과 (Codex의 경우) 선택 가능한 노력이 있는 Claude Code 또는 Codex를 사용하세요.

레이블에는 동일한 모델에 대한 정렬된 후보 ID 목록이 있습니다. 설치된 CLI가 그중 어느 것도 제공하지 않으면 호출은 requested_model_unavailable 및 전체 사용 가능 모델 목록과 함께 실패합니다. 다른 모델로 자동 대체되는 일은 절대 없습니다. 해석된 ID는 매 실행마다 warnings에 다시 표시됩니다.

구성된 호출은 다음과 같습니다:

agy --print <PROMPT> --model <RESOLVED_ID> --output-format json \
    --mode <plan|accept-edits> --add-dir <PROJECT> \
    --dangerously-skip-permissions --print-timeout <N>s

--disable-slash-commands는 implement 실행에만 추가됩니다. CLI는 슬래시 명령 확장이 비활성화되면 --mode plan을 무시하므로, 둘 다 보내면 Antigravity가 제공하는 유일한 쓰기 금지 동작이 조용히 무시됩니다.

bridge_status

인수 없음. 모델 추론을 소비하지 않습니다 — --version 프로브, agy models, git rev-parse 한 번, Codex CLI의 모델 캐시 읽기만 실행합니다.

반환:

• AgentBridge 버전, 프로젝트 디렉터리(및 해석 방식), node/플랫폼

• git_verification — git 기반 files_changed / scope_violations가 여기서 작동할 수 있는지 여부. 작동할 수 없는 경우 빈 scope_violations는 문제없음이 아니라 침묵이며, 경고에 그렇게 명시됩니다

• codex.installed / version / path / auth

• codex.model_status — 모델별: available | unavailable | unverified, AgentBridge 노력 레이블이 수용하는 값, CLI의 원시 추론 수준

• codex.model_source — 가용성이 어디서 왔는지, 얼마나 최신인지

• antigravity.installed / version / path / auth, 감지된 모델, 각 논리 레이블 + 티어가 어떻게 해석되었는지, 동일한 3-상태 형태의 model_status

• antigravity.unsupported_efforts — Flash가 처리할 수 없는 오케스트레이터 레이블

• 활성 작업 및 해당 쓰기 범위

• 경고

가용성은 절대 추측되지 않습니다. 설치된 CLI가 저렴한 증거를 제공하지 않으면 어느 방향으로든 주장하지 않고 상태는 unverified입니다.

자격 증명이나 환경 변수를 반환하지 않습니다.

결과 형식

{
  "status": "success",
  "provider": "codex",
  "model": "gpt-5.6-luna",
  "effort": "high",
  "mode": "implement",
  "duration_ms": 12345,
  "exit_code": 0,
  "summary": "...",
  "files_changed": ["src/upload.ts"],
  "scope_violations": [],
  "tests_or_checks_run": ["npm test -- upload"],
  "test_results": "12 passed",
  "concerns_or_blockers": [],
  "stderr_tail": "",
  "warnings": []
}

effort는 두 제공자 모두에 존재합니다 — Codex 추론 수준 또는 모델 ID가 인코딩하는 Flash 티어입니다. files_changed 및 scope_violations는 작업자의 말이 아닌 git에서 AgentBridge가 계산합니다. 내부 추론은 삭제됩니다. summary는 16,000자로 제한되며, 앞부분과 뒷부분을 유지하고 잘릴 때 summary_truncated: true를 설정합니다.

오류

실패는 동일한 봉투 형태로 status: "failed", error 범주, 실행 가능한 message, 그리고 가능한 경우 exit_code, stderr_tail, details 객체를 반환합니다.

Claude가 작업자를 호출하는 예시

저렴하고 빠른 분석:

{ "tool": "codex_run",
  "goal": "Explain how session refresh works and where it can race.",
  "mode": "analyze", "model": "gpt-5.6-luna", "effort": "light",
  "relevant_files": ["src/auth/session.ts"] }

하드 구현, 최대 추론, 엄격한 범위:

{ "tool": "codex_run",
  "goal": "Make the uploader retry 502s with exponential backoff.",
  "mode": "implement", "model": "gpt-5.6-sol", "effort": "max",
  "allowed_paths": ["src/upload.ts", "tests/upload.test.ts"],
  "no_touch": ["src/auth"],
  "contract": "export function upload(f: File): Promise<Result>",
  "acceptance_criteria": ["Retries up to 3 times", "Existing callers unchanged"],
  "tests": ["npm test -- upload"] }

서로 다른 범위의 두 Codex 작업자 — 이들은 동시에 실행됩니다:

{ "tool": "codex_run", "mode": "implement", "model": "gpt-5.6-sol",
  "effort": "high", "allowed_paths": ["src/api"], "goal": "..." }
{ "tool": "codex_run", "mode": "implement", "model": "gpt-5.6-luna",
  "effort": "medium", "allowed_paths": ["src/ui"], "goal": "..." }

저렴한 기계적 작업을 위한 Antigravity:

{ "tool": "antigravity_run", "goal": "Summarise every exported symbol in src/lib.",
  "mode": "analyze", "model": "Gemini Flash 3.7", "effort": "light" }

{ "tool": "antigravity_run", "goal": "Build the settings page from design.png.",
  "mode": "implement", "model": "Gemini Flash 3.7", "effort": "high",
  "allowed_paths": ["src/pages/settings"] }

동시성 및 파일 범위

• implement는 allowed_paths를 요구합니다. 경로는 프로젝트 루트를 기준으로 정규화됩니다. 이를 벗어나는 것(.., 다른 드라이브, 다른 곳의 절대 경로)은 프로세스가 시작되기 전에 거부됩니다.

• 활성 implement 작업은 메모리에 쓰기 범위를 보유합니다. 활성 작업의 범위와 겹치는 새 작업은 scope_conflict로 거부됩니다. 서로 다른 범위는 병렬로 실행됩니다 — 관련 없는 작업은 직렬화되지 않습니다.

• analyze 및 review는 아무것도 예약하지 않습니다: 차단하지 않으며 차단되지도 않습니다.

V1 제한: 격리가 아닌 감지

파일 범위 보호는 위반을 감지하고 보고합니다. 각 작업자를 자체 트리로 샌드박싱하지는 않습니다. Codex implement 작업자는 프로젝트 전체에 workspace-write로 실행되므로 allowed_paths 밖에 쓸 수 있습니다 — AgentBridge는 그러한 모든 파일을 scope_violations에 나열하고 상태를 success에서 강등시키며 명확히 알려줍니다.

자동으로 되돌려지는 것은 절대 없습니다. 작업자가 시작되기 전에 이미 수정된 파일을 되돌리면 기존 작업(사용자 또는 Claude의)이 파괴됩니다. 감지와 정직한 보고가 V1 계약입니다. git-worktree 격리는 의도적으로 범위 밖입니다.

귀속은 기존 상태에 대해 신중합니다: 실행 전에 이미 더티였고 이후 바이트 단위로 동일한 파일은 작업자 탓으로 돌리지 않습니다. 비교는 porcelain 상태와 콘텐츠 해싱을 사용하며, 커밋된 파일은 HEAD 이동 diff를 통해 포착됩니다.

보안

• 프로세스는 인수 배열과 shell: false 로 생성됩니다 — 보간된 명령 문자열은 절대 사용하지 않습니다. 인수의 셸 메타문자는 리터럴로 유지됩니다.

• Windows .cmd/.ps1 런처(Node가 셸 없이는 생성할 수 없음)는 실제 Node 진입 스크립트로 해석되어 node <script>로 실행되므로 shell: true가 절대 필요하지 않습니다.

• 프롬프트는 stdin을 통해 Codex로 전달됩니다. 과도하게 큰 Antigravity 프롬프트는 임시 파일에 기록되고 경로로 참조됩니다. 둘 다 Windows 32,767자 명령줄 제한에 도달할 수 없습니다.

• tests는 작업자를 위한 컨텍스트입니다. AgentBridge는 이를 실행하지 않으며, AgentBridge가 실행하는 명령이 되는 MCP 인수는 어디에도 없습니다.

• 프로젝트 루트 밖으로의 경로 탐색은 거부됩니다.

• 시간 초과는 전체 프로세스 트리를 종료합니다: Windows에서는 taskkill /T /F, POSIX에서는 프로세스 그룹에 SIGTERM을 보내고 3초 유예 후 SIGKILL로 확대합니다. 확대는 직접 자식의 종료를 의도적으로 생존합니다. 정확히 그때 자손이 여전히 실행 중일 수 있기 때문입니다. 이는 최선의 노력입니다 — Node는 Windows Job Object를 노출하지 않으므로 taskkill 자체가 시작할 수 없으면 직접 자식만 도달할 수 있습니다.

• 출력 버퍼는 제한되어 있으며(스트림당 8MB) UTF-8은 재조립 후에만 디코딩되므로 멀티바이트 문자가 분할되지 않습니다.

• 로그는 작업 메타데이터만 기록합니다. 토큰, 환경 변수는 절대 기록하지 않으며 프롬프트/출력은 AGENTBRIDGE_DEBUG=1일 때만 기록합니다.

• AgentBridge가 보호하지 못하는 것: 작업자는 사용자의 권한으로 실행되는 실제 코딩 에이전트입니다. implement 모드에서는 자체 도구를 통해 저장소 명령을 실행할 수 있습니다. allowed_paths를 그에 맞게 범위를 지정하세요.

검증

AgentBridge는 작업자가 종료된 후 샌드박스 밖에서 프로젝트 자체 검사를 직접 실행하고 실제 출력을 verification에 반환합니다:

"verification": [
  { "command": "npm run typecheck", "ok": true,  "exit_code": 0, "timed_out": false, "duration_ms": 4120, "output_tail": "..." },
  { "command": "npm run test",      "ok": false, "exit_code": 1, "timed_out": false, "duration_ms": 8830, "output_tail": "..." }
]

• verify_commands — 어떤 모드에서든 정확히 이것들을 실행합니다.

• implement 모드에서는 생략됨 — AgentBridge는 package.json을 읽고 typecheck 및 test 스크립트가 있으면 실행합니다. 자체 판단으로 build, dev, start를 실행하지 않습니다. 명시적으로 요청하세요.

• skip_verification: true — 아무것도 실행하지 않고 작업자의 설명에 의존합니다.

명령은 셸 없이 실행되므로 따옴표 밖의 |, &&, ;, > 및 백틱은 반쯤 실행되는 대신 거부됩니다. 실패한 검사는 error: "verification_failed"를 설정하고 success를 partial로 강등시키므로, 테스트 통과를 주장하는 작업자가 테스트 자체보다 우선할 수 없습니다.

tests_or_checks_run 및 test_results는 검증이 발생할 때마다 AgentBridge가 실제로 실행한 것을 보고합니다. 검증이 발생하지 않은 경우에만 작업자 자신의 주장으로 대체됩니다.

명령이 저장소에서 오기 때문에 잘못된 러너를 지정한 브리프가 AgentBridge가 그것을 실행하게 할 수 없습니다: 테스트 스크립트가 node --import tsx --test인 저장소는 브리프가 무엇을 말했든 그 명령으로 검사됩니다.

환경 변수

AGENTBRIDGE_CODEX_SANDBOX=auto는 analyze/review에 read-only를, implement에 workspace-write를 사용합니다 — 단, Windows에서는 샌드박스된 Codex 작업자가 하위 프로세스의 출력을 캡처할 수 없으므로(파이프된 stdio에서 spawn EPERM), npm 스크립트, 테스트 러너, 번들러가 모두 수행하는 작업이 불가능합니다 — 읽기와 편집은 가능하지만 테스트 러너, 타입 체커, 빌드를 실행할 수 없습니다. 이는 구성 노브가 없는 Codex 제한이므로, 일회성 프로브가 확인하면 implement 작업은 danger-full-access로 대체되고 warnings에 그렇게 명시합니다. Analyze와 review는 강제된 read-only 경계를 유지합니다. Windows에서 실행이 손상된 샌드박스 헬퍼(helper_unknown_error: apply deny-read ACLs)로 실패하면 AgentBridge는 해당 작업을 danger-full-access로 한 번 재시도하고, 프로세스의 나머지 기간 동안 그 판정을 기억하며, 경계가 강제되지 않았다는 경고를 영향을 받는 모든 결과에 첨부합니다. 다른 어떤 것도 이 대체를 트리거하지 않으며, AgentBridge를 다시 시작하면 실제 샌드박스를 다시 시도합니다 — 수정된 Codex 릴리스가 자동으로 복원합니다. macOS와 Linux는 프로브, 재시도, 대체를 절대 수행하지 않습니다.

로그는 작업당 JSON 한 줄입니다: 타임스탬프, 작업 ID, 제공자, 모델, 노력, 모드, 프로젝트, 기간, 종료 코드, 오류 범주.

문제 해결

executable_not_found — CLI가 Claude Code가 하위 프로세스에 내보내는 PATH에 없습니다. 동일한 셸에서 codex --version / agy --version으로 확인하거나 AGENTBRIDGE_CODEX_BIN / AGENTBRIDGE_AGY_BIN을 설정하세요.

authentication_required — CLI 세션이 만료되었습니다. 터미널에서 수정하세요: Codex는 codex login, agy는 다시 로그인하세요. AgentBridge는 의도적으로 이를 복구할 방법이 없습니다: 자격 증명을 건드리지 않습니다.

requested_model_unavailable — 모델 목록이 변경되었거나, 설치된 CLI가 해당 모델을 제공한 적이 없습니다. 실제로 제공되는 모델을 확인하려면 bridge_status(또는 agy models)를 실행하세요. 오류의 details에 이미 그 정보가 포함되어 있습니다. AgentBridge는 다른 모델을 조용히 실행하는 대신 의도적으로 여기서 실패합니다. 공급자가 모델 id를 변경한 경우, src/models/antigravity.ts의 해당 라벨 후보 목록(또는 src/models/codex.ts의 CODEX_MODELS)에 새 id를 추가한 후 다시 빌드하세요.

output_parse_failed — CLI가 기계 판독 가능한 출력 형식을 변경했습니다. 결과의 details.stdout_head를 확인한 다음 parseCodexEvents / parseAgyOutput과 비교하세요.

CLI 업데이트 후 — 테스트를 다시 실행한 다음 라이브 스모크 확인을 실행하세요:

SMOKE_LIVE=1 node scripts/smoke.mjs

이것은 실제 MCP 세션을 구동하고 각 워커의 가장 저렴한 구성을 실행합니다. SMOKE_LIVE=1이 없으면 핸드셰이크와 bridge_status만 수행하며, 비용이 발생하지 않습니다.

files_changed가 항상 비어 있음 — 프로젝트 디렉터리가 git 작업 트리 안에 있지 않습니다. 결과의 경고에 그 내용이 명시되어 있습니다. 변경 검증에는 git이 필요합니다.

/mcp 아래에 아무것도 표시되지 않음 — 등록된 경로가 dist/index.js(빌드된 파일, src/ 아님)를 가리키는지 확인하고, 다시 빌드한 후 Claude Code를 재시작하세요.

레이아웃

src/
  index.ts               stdio entry point
  server.ts              MCP server, tool schemas, dispatch
  config.ts              project-dir resolution, timeout clamping
  logging.ts             JSONL job log (stderr only, never stdout)
  parse.ts               worker-envelope parsing, summary capping
  types.ts
  cli/
    resolve.ts           PATH lookup + Windows shim unwrapping
    detect.ts            version probes, agy model listing, auth heuristics
    codex-catalogue.ts   zero-inference Codex model availability + effort capability
    codex-sandbox.ts     sandbox policy decision and helper-failure detection
  models/
    codex.ts             effort map, argv construction
    antigravity.ts       logical→real model resolution, argv construction
  process/
    runner.ts            shell-free spawn, bounded output, tree kill
  prompts/
    worker-prompt.ts     structured request → worker prompt
  scope/
    paths.ts             normalisation, traversal rejection, overlap
    locks.ts             in-memory write-scope registry
    git-state.ts         snapshot/diff file attribution
  tools/
    codex.ts  antigravity.ts  status.ts  common.ts
tests/                   252 tests, mocked processes, no quota used
scripts/smoke.mjs        real MCP end-to-end check