Claude Code Codegraph Harness

Claude Code와 Codex를 위한 오프라인 로컬 코드그래프 게이트웨이, 이중 클라이언트 어댑터, 평가 실행기, 크로스 플랫폼 패키징 시스템입니다.

상태: v0.2.0-rc.1, 공개 픽스처 릴리스 후보입니다. 런타임은 동작하지만, 측정된 Codex 그래프 조건에서는 입력 토큰이 4852% 증가했고, 기존 Claude 그래프도 확대되었으며 유효 입력이 58112% 증가했습니다. 기업 내부 소스 코드는 엔터프라이즈 Windows/macOS 격리 증거가 승인될 때까지 사용이 불가능합니다. 이 릴리스는 토큰 절감 효과를 주장하지 않습니다.

기업 사용자와 관리자를 위한 일본어 설명은 이 하네스의 구조에서 시작하세요. 동일한 내용은 모든 생성된 오프라인 ZIP에 HOW-IT-WORKS-JA.md로 포함되어 있습니다.

구현 내용

• 회사 소유 Go stdio 게이트웨이 — 다섯 가지로 제한된 읽기 전용 도구를 제공합니다.

• 해당 게이트웨이 내부의 Codebase-Memory v0.10.8 네이티브 바이너리 지원.

• 명시적 관리자 인덱스 빌드, 불변 세대(immutable generations), 원자적 current 포인터, 리포지토리 바인딩 상태, 쿼리별 최신성 검사.

• 하나의 정식 라우팅 정책을 따르는 Claude Code Plugin/Rule 및 Codex 사용자 Skill.

• arm64와 x86_64 런타임 번들을 위한 macOS 및 Windows 설치 프로그램.

• 재현 가능하고 체크섬이 검증된 어댑터 전용 ZIP과 4개 플랫폼 대상 내부 ZIP.

• 프롬프트나 응답을 저장하지 않으면서 토큰 사용량, 지연 시간, 제한된 오라클 결과, 도구 이름을 기록하는 공개 픽스처 평가 실행기.

게이트웨이는 다음만 노출합니다.

• codegraph_status

• codegraph_search

• codegraph_neighbors

• codegraph_impact

• codegraph_architecture

인덱싱, 변경, 임의 그래프 쿼리, 소스 본문 검색, URL, 그리고 업스트림 MCP 도구는 모델이 호출할 수 없습니다.

Related MCP server: codebase-rag

런타임 아키텍처

Claude Code Plugin + Rule ----\
                               > registered local stdio gateway
Codex user Skill -------------/              |
                                              v
                                  pinned Codebase-Memory native binary
                                              |
                                              v
                              private repository-bound graph generations

administrator command -> gateway index build -> validate -> atomic activation

Claude Code와 Codex는 완전히 같은 게이트웨이, 백엔드, 인덱스, 최신성 모델, 다섯 가지 도구 계약을 공유합니다. Plugin과 Skill에는 라우팅 지침만 들어 있으며, 업스트림 백엔드를 직접 실행하지 않습니다.

현재 채택 결정

Graphify v0.9.48는 고정된 업스 MCP가 GitHub에 연결된 PR 도구와 외부 LLM 경로를 포함하고 있기 때문에 회사 소스 코드용으로는 거부되었습니다. Codebase-Memory v0.10.8이 조건부 네이티브 백엔드입니다. 실제 네이티브 경로에는 관찰된 외부 네트워크 의존성이 없고, UI/watch 전체 지연, 자동 인덱스를 비활성화할 수 있으며, 네 가지 대상 OS/CPU 조합에 대해 모두 제공되기 때문입니다. 이 프로젝트는 npm, PyPI, Go, 업스트림 설치 래퍼들이 모두 GitHub 다운로드에 의존하므로 금지됩니다.

게이트웨이와 백엔드는 외부 네트워크 접근을 차단한 macOS 샌드박스에서 일회용 공개 픽스처로 검증했습니다. 그 결과 759개의 노드와 1,760개의 엣지가 생성되었으며, 누락되거나 부분적 혹은 비인덱스 파일은 0개였습니다. 검색, 영향 추적, 아키텍처 분석, 스키마 검증, 만료 상태 및 루트 거부는 모두 성공했습니다.

반복된 Codex 비교 실험에서는 비용 절감 효과가 나타나지 않았습니다:

Claude Code에서도 게이트웨이 자체는 성공했지만 비용 절감은 나타나지 않았습니다:

| 작업 체계 | 기준 중간 유효 입력 | 그래프 강제 기준 중간 | 변화 | 품질 검증 | |---:|---:|---:|---:| | 단일 심볼 위치 찾기 | 54,464 | 115,250 | +111.61% | 3/3 vs 3/3 | | 호출자/직접 테스트/기본 프로필 추적 | 112,029 | 176,515 | +57.56% | 3/3 vs 3/3 |

Claude 실험은 실행당 정확히 하나의 제한된 게이트 도구만 호출한 뒤 소스를 검증했습니다. 강제 호출이 없는 그래프 사용 가능 상태의 프로브는 MCP 도구를 선택하지 않았으므로, 자동 도구 선택이 확립된 것은 아닙니다. OAuth/키체인은 일반적인 headless 모드에서 필요했습니다. 정확한 통제 방법과 제한 사항은 Claude Code 통계에 기록되어 있습니다.

따라서 그래프는 항상 켜둔 비용 최적화가 아니라 선택적으로 사용하는 구조적 탐색 기능입니다. Codex 평가도 참고하세요.

코드 유출 방지 경계선

엔드포인트 설치 파일에는 다운로더나 패키지 관리자 호출이 포함되어 있지 않습니다. 게이트웨이는 해시로 지정된 local 백엔드와 Git 실행 파일만, 가상의 개인 홈 디렉터리와 최소화된 환경변수에서 실행합니다. 상태는 항상 소스 리포지토리 밖에 존재합니다. 도구 결과에는 상대 경로의 제한된 경로와 그래프 근거만 포함되며, 원본 소스 본문은 포함되지 않습니다.

이러한 통제는 엔터프라이즈 샌드박스가 아닙니다. stdio는 자식 프로세스가 DNS를 열거나 HTTPS에 접속하는 것을막지 못합니다. 런타임을 설치하려면 명시적 절대경로 --allowed-root/-AllowedRoot가 필요하며, 각 릴리스 후보 게이트웨이 바이너리는 정확한 클린 공개 픽스처의 콘텐츠 지문(values), 지문 문자열, 또는 다른 체크아웃/저장소로는 활성화할 수 없는 방식으로 컴파일됩니다. 이 릴리스는 그대로 public-fixture 전용입니다. 기업 소스 코드에 사용하기 전덧, 엔드포인트 AppSec 반은 지원되는 모든 Windows와 macOS 아키텍처에서 해당 바이너리의 프로세스 트리 네트워크 차단과 파일시스템/credential 격리를 강제하고 이 기록을 남겨야 합니다.

공개 저장소와 릴리스에는 절대 회사 소스, 프롬프트, 결과물, 내부 경로, 관리 정책, 서명 키, 생성된 그래프, 서드 파티 네이티브 바이너리가 포함되지 않습니다.

어댑터 전용 공개 ZIP

공개 릴리스는 의도적으로 작게 만든, 어댑터 · 설치 프로그램 · 계약 · 문서 만을 담고 있습니다:

python3 -m venv .venv
. .venv/bin/activate
python -m pip install -e .
codegraph-harness bundle \
  --version 0.2.0-rc.1 \
  --profile packaging/profiles/public.json \
  --output dist/codegraph-harness-0.2.0-rc.1.zip

이 ZIP 하나를 설치한다고 그래프 런타임이 활성화되지는 않습니다.

내부 런타임 ZIP

내부 아티팩트 파이프라인은 네 가지 타깃을 위한 게이트웨이를 만들고, 승인된 미러에서 가져 온 정확한 네 개의 Codebase-Memory 실행 파일을 스테이징합니다. 그러고 나서 runtime-matrix.json.in의 게이트웨이 메타데이터 토큰을 대체하고 다음을 수행합니다:

codegraph-harness bundle \
  --version COMPANY_RELEASE_VERSION \
  --profile /approved/input/runtime-matrix.json \
  --vendor-dir /approved/input/native \
  --output /approved/output/codegraph-harness-COMPANY_RELEASE_VERSION.zip

빌더는 명시적으로 검증된 일반 파일만 읽고, 모든 SHA-256을 검증하며, 심볼릭 링크/디렉터리 침투/충돌을 거부하고, 결정적(zip) ZIP, 런타임 매니페스트, 번들 매니페스트, SHA256SUMS를 만듭니다. 현재 4플랫폼 테스트 ZIP은 눌러 면 172 MB, 압축 해제 시 1.1 GB입니다. 각 엔드포인트는 자신의 OS/CPU와 일치하는 게이트웨이/백엔드 쌍만 설치합니다.

비즈니스 엔드포인트에는 GitHub, npm, PyPI, Go 레지스트리, 또는 벤더 서버가 필요 없습니다. 대신 조직이 관리하는 Git 실행 파일이 필요하며, 이 파일은 설치 시점에 기록됩니다.

엔드포인트 명령들

어댑터만 들어 있는 공개 ZIP의 경우:

./install.sh --dry-run
./install.sh

powershell.exe -NoProfile -File .\install.ps1 -DryRun
powershell.exe -NoProfile -File .\install.ps1

런타임 ZIP을 사용한다면 관리자는 그 게이트웨이 바이너리에 컴파일된 정확한 공개 픽스처 체크아웃으로 범위를 한정해야 합니다:

./install.sh --dry-run --allowed-root /absolute/approved/public-fixtures
./install.sh --allowed-root /absolute/approved/public-fixtures

powershell.exe -NoProfile -File .\install.ps1 -DryRun -AllowedRoot C:\Approved\PublicFixtures
powershell.exe -NoProfile -File .\install.ps1 -AllowedRoot C:\Approved\PublicFixtures

어셈블리 시점에 번들 빌더는 모든 게이트웨이가 가진 임베디드 픽스처 허용 목록이 런타임 프로필와 일치하는지 확인합니다. 엔드포인트에서 설치기는 추출한 모든 항목을 SHA256SUMS와 대조 검증하고, 로컬 OS/CPU쌍을 선택하며, 소유되지 않은 파일을 덮어쓰지 않고 Claude Rule과 Codex Skill을 설치하고, 옵션으로 로컬 Claude 마켓플레이스 플러그인을 설치하며, 동일한 게이트웨이를 두 클라이언트에 모두 등록하고, 수신 확인의해 포함한 해시 영수증을 씁니다. 일부 실패가 있으면 롤백됩니다.

기본적으로 제거 유예되는 것—파생 그래프 상태는 보존되어 조용한 데이터 손실이 생기지 않습니다. 정책상 삭제가 필요하면 기본 제거 명령에 --purge-graph-state 또는 -PurgeGraphState를 지정하세요.

압출 해제 전, ZIP 별도로 받은 서명 또는 SHA-256으로 완전한 검증하십시오. ZIP 안에 들어 있는 SHA256SUMS는 부분적 교체는 잡아내지만, 아카이브 전체가 교체된 경우에는 신뢰 근거가 될 수 없습니다.

평가 실행기

검사 대상 실행리는 공개 픽스처만 허용하며, 조건 JSON을 읽거나 프로세스를 시작하기 전에 company-source 를 거부합니다. Claude Code와 Codex의 베이스라인/게이트웨어 상태, 그리고 잠재적 각 레거시 호환 ID 비교를 지원합니다. 원시 stdout/stderr는 항상 해시로 변환되지만 명시적 요청이 없으면 저장되지 않습니다.

평가 프로토콜을 참조하세요. 조건 파일은 실행 구성을 담고 있으므로 신뢰할 수 있는 코드로 취급해야 합니다.

검증

현재 로컬 검증 체계는 Python 테스트 85개 이상, Black, mypy strict, Go unit/vet/race, 네 개 타깃 크로스 컴파일, Claude Plugin 엄격 검증, 체크섬/아카이브 테스트, 실제 macOS arm64 설치→인덱스 생성→MCP 쿼리→제거까지 실행을 포함합니다. Windows 실행 파일은 크로스로 만들어지고 PowerShell 흐름은 GitHub Actions에서 검증됩니다. 네이티브 Windows Codebase-Memory 실행과 엔터프라이즈 EDR 취득은 아직 회사 소스 코드로서의 릴리스 게이트로 남아 있습니다.

추가 설명

• Architecture

• Internal harness integration

• Offline distribution

• Threat model

• Backend selection ADR

• Wrapper ADR

• Dual-client ADR

• Candidate egress audit

• Runtime evidence

라이선스

저장소의 코드는 Apache-2.0로 배포됩니다. Codebase-Memory는 MIT 라이선스를 유지하며, 해당 고지사항을 포함한 내부 승인된 번들로만 재배포됩니다.