grok-bot-0.18-reconstructed (b-nnett/grok-bot-0.18-reconstructed) 딥다이브
— 출시된 데스크톱 앱 "바이너리"를 읽을 수 있는 소스로 되살린 프로젝트

1프로젝트 한 줄 요약

먼저 "Grok Bot"이 대체 뭔지부터 정리하고 가자. 이름만 보면 xAI의 챗봇 같지만, 뜯어 보면 정체가 드러난다.

즉 Grok Bot은 Cursor를 만든 Anysphere의 "Sand" 에이전트 기술을 xAI 브랜드로 화이트라벨한 데스크톱 앱이다. 이 저장소는 그 앱의 공개 macOS 빌드를 받아 역컴파일·재구성한 결과물이고, 이름의 -reconstructed가 그 뜻이다.

재구성의 결과물은 하이브리드 앱이다. 저장소가 스스로 정리한 표현을 옮기면 이렇다.

얹은 실험 기능의 백미는 추론 라우터다. 설정 → Router에서 새 대화가 어느 백엔드로 갈지 고른다.

Claude Code·Codex는 별도 API 키가 필요 없다 — 이미 로컬에 로그인돼 있는 세션을 그대로 재사용한다. 이 "남의 로그인 재활용"이 어떻게 가능한지가 4장의 핵심 볼거리다.

2왜 주목할 만한가

"Electron 앱 뜯어봤다"류 글은 흔하다. 이 저장소가 공부 자료로서 특별한 건 결과물이 아니라 규율 때문이다. 네 가지가 겹친다.

① "증거 기반 재구성"이라는 성문화된 규칙

PROVENANCE.md에 Evidence-only reconstruction rule이라는 절이 있다. 요지는 이렇다 — 되살린 소스는 "검사 가능한 아티팩트 앵커가 최소 하나 이상 뒷받침하는 동작"만 표현할 수 있다. 앵커의 예: 방출된 코드나 소스 경로 마커, 추출된 소스맵, 출시된 문자열·에셋·CSS, 렌더러 DOM 시그니처, IPC/RPC 계약, 또는 실행 중인 런타임의 반복 관측.

이 규율은 매니페스트에까지 박제돼 있다. manifests/reconstruction/renderer-closure.json은 재구성한 프런트엔드가 출시 번들을 "기능 손실 없이" 대체할 수 있음을 증명하면서도, 703개의 JSX 런타임 후보는 1차 증거에 연결되지 않아 "기능으로도, 서드파티 면제로도 취급하지 않는다"고 정직하게 남겨 둔다. 모르는 걸 안다고 하지 않는 태도가 파일로 강제된다.

② 결정론적 재현 툴체인

이 프로젝트는 "소스를 읽었다"에서 멈추지 않고, 그 소스를 다시 동작하는 앱으로 빌드한다. 그것도 재현 가능하게. 원본 DMG를 SHA-256으로 고정해 내려받아 검증하고, 그 안의 app.asar도 다시 해시로 확인한 뒤, 재구성 런타임을 컴파일해 얹고, 새 번들 ID로 ad-hoc 서명한다. "실물을 안 건드리고 도면만으로 같은 차를 다시 조립할 수 있는가"를 실제로 증명하는 셈이다(자세히는 4장).

③ 이미 로그인된 CLI 세션을 재활용하는 라우터

대부분의 "멀티 LLM" 앱은 제공자마다 API 키를 새로 받는다. 이 프로젝트는 다르다. 사용자의 로컬 머신에 이미 설치·로그인된 Claude Code와 Codex를 찾아내 그 인증을 그대로 쓴다. Claude Code는 공식 @anthropic-ai/claude-agent-sdk로 호출하고, Codex는 로컬 로그인의 OAuth 토큰으로 ChatGPT 백엔드를 직접 친다. 키 관리 없이 "내가 이미 쓰는 도구"를 데스크톱 UI 안으로 끌어오는 구성이다.

④ "무엇을 새로 만들고, 무엇을 원본에서 남기는가"의 경계가 명확

이 저장소는 UI를 통째로 재현하려는 무모함을 피했다. 출시된 렌더러는 소스맵 없는 minified 프로덕션 번들이었고, 저자는 "그걸 같은 완성도로 재현하는 건 주말 프로젝트로 될 일이 아니다"라고 솔직히 적는다. 그래서 런타임·제어 평면만 재구성하고 렌더러는 해시로 고정한 채 유지하되, 라우터 설정만 최소 패치로 얹었다. 오픈코어처럼 경계를 긋는 판단 자체가 배울 점이다.

3기술 스택 전체 지도

이 저장소는 크게 세 덩어리다 — ① source/의 앱 런타임(재구성), ② frontend/의 렌더러 재구성 워크스페이스, ③ scripts/의 부트스트랩·빌드·검증 툴체인. 먼저 소스 규모를 직접 세어 보면(shallow clone 후 실측):

줄 수의 대부분(packages/ 33만 줄)은 재구성된 내부 라이브러리들이라는 걸 기억해 두자. 앱의 "새로 쓴 두뇌"는 host/·electron-main/·coordinator/ 쪽이다.

런타임 — Electron 42.1 + Node 26.5

package.json의 의존성은 이 앱이 무엇을 하는지 그대로 보여 준다. 성격을 말해 주는 것만 골라 보면:

빌드·재구성 툴체인 — devDependencies가 곧 "공장"

이 저장소의 개성은 devDependencies에 더 진하게 드러난다. 앱을 "굴리는" 것과 "되살리는" 도구가 섞여 있다.

원본 설치본 2종은 Git LFS로 저장소에 보존된다(.gitattributes가 *.dmg·*.exe를 LFS로 지정). 다만 추출한 앱 본체·빌드 산출물·크레덴셜·대형 포렌식 작업물은 커밋하지 않는다 — .gitignore가 .cache·.build·dist·src/app/dist·recovered·recovery를 막는다. 저장소엔 "검토된 재구성 + 재현 도구"만 남는다.

4아키텍처 심화 분석

런타임 경계 — 신호가 흐르는 다섯 층

실행 중 앱은 다섯 개의 경계로 나뉜다. 위에서 아래로 신뢰 수준이 좁아진다.

coordinator와 host는 ConnectRPC + protobuf로 대화한다. 이 RPC 계약이 재구성의 앵커 중 하나다 — 출시 바이너리에서 관측된 메서드·메시지 형태가 소스를 되살릴 근거가 된다.

설계의 중심축 ① — 원본을 "빌드 입력"으로 고정하는 파이프라인

이 프로젝트에서 가장 배울 게 많은 부분이다. npm run bootstrap → check → package → verify 네 단계가 "실물을 안 건드리고 도면만으로 같은 앱을 다시 조립"하는 흐름을 이룬다.

세 겹의 방어가 겹쳐 있다는 게 핵심이다. 입력은 해시로 고정하고(DMG·app.asar·원본 셸), 산출물은 전부 해시로 기록하고(reconstruction-build.json 등), 마지막에 포장물을 다시 열어 그 기록과 독립적으로 재대조한다. 여기서 "해시 기록"은 문서가 아니라 합격 판정 그 자체다 — 검증기가 그 기록을 계약으로 삼아 어긋나면 빌드를 떨어뜨린다.

설계의 중심축 ② — 렌더러는 "다시 안 그리고" AST로 한 지점만 판다

UI를 통째로 재현하지 않는 대신, minified 렌더러 청크에 라우터 설정 패널만 끼워 넣는다. 방식이 정교하다. 정규식 치환이 아니라 exact-once 앵커 수술이다.

// scripts/lib/router-renderer-patch.mjs (개념)
// ① 설정 탭 레지스트리가 든 청크는 "정확히 하나"여야 한다
// ② 패널 앵커가 든 청크도 "정확히 하나"여야 한다
// replaceExactlyOnce: 앵커가 없거나(missing) 여럿이면(ambiguous) 던진다

// 세 지점만 건드린다:
//  - const wDn=[...]  설정 탭 배열에 {id:"router",label:"Router"} 삽입
//  - x==="router" ? a.jsx(RRouterPanel,{}) ...  패널 스위치
//  - function Sa(s){ 앞에 RRouterPanel/RBoxRuntime 등 (이미 minify된) 컴포넌트 prepend

설계의 중심축 ③ — "서명은 안 베끼고, 구조가 같다는 것만 증명"

가장 영리한 트릭이 여기 있다. 재구성 셸이 정품과 구조적으로 동일함을 증명하되, 정품의 서명된 바이너리를 복사하지는 않는다. macos-shell-invariant.mjs는 arm64 Mach-O를 직접 파싱해 __LINKEDIT 오프셋과 코드서명 로드 커맨드를 0으로 지운 뒤 나머지를 해시한다.

설계의 중심축 ④ — 추론 라우터의 실제 동작

이제 1장에서 예고한 "남의 로그인 재활용"을 뜯어보자. 라우터는 제공자별 어댑터로 나뉘고, 로컬 트랜스크립트를 별도로 관리하며, 에이전트별 직렬 큐로 턴을 처리한다.

// inference-router.ts — 턴 번호를 원격+로컬 양쪽에서 계산해 충돌 방지
const turn = Math.max(remoteTurn, localTurn) + 1;
const userEntry = { id: `t${turn}u`, role: "user", content: prompt, ... };

// 활동 표시(“생각 중…”)를 250ms 간격으로 펄스해 유지
const pulse = setInterval(publishRunning, 250);
// 출시된 가상 트랜스크립트가 활동 행을 만드는 데 ~350ms 걸리므로
// 첫 토큰 전에 1200ms를 의도적으로 기다려 “작성 중” 상태가 눈에 보이게 한다
await new Promise(r => setTimeout(r, 1_200));

이 두 줄(250ms 펄스 · 1200ms 지연)은 기능이 아니라 "원본 UI의 착시를 존중하는" 코드다. 원본 렌더러는 첫 어시스턴트 토큰이 오는 순간 활동 행을 지우도록 만들어져 있는데, 직접 제공자는 그 첫 토큰이 너무 빨리 와서 "작성 중" 상태가 인지되지 않는다. 그래서 로컬 상태를 잠깐 권위 있게 유지한다 — 증거 기반 재구성이 UX 디테일까지 파고든 사례다.

Codex — 로컬 로그인으로 ChatGPT 백엔드를 직접 친다

Codex 제공자는 CLI 바이너리를 실행 경로에 두지 않는다. 대신 ~/.codex/auth.json의 OAuth 토큰을 읽어 chatgpt.com/backend-api/codex/responses를 직접 호출한다. 파일 권한이 남에게 열려 있으면(mode & 0o077) 거부하고, 401이 오면 리프레시 토큰으로 조용히 재발급한다.

// provider-session.ts — 401이면 refresh 후 1회 재시도
let result = await perform();          // Bearer + ChatGPT-Account-Id 헤더
if (result.status !== 401) return result;
credentials = await refreshCodexCredentials(credentials);  // auth.openai.com/oauth/token
return await perform();

Claude Code — 공식 Agent SDK로, MCP 도구까지 라우팅

Claude Code 제공자는 @anthropic-ai/claude-agent-sdk의 query()를 쓴다. 여기에 Grok Bot의 플러그인 도구를 붙이는 방식이 재밌다 — 루프백 HTTP MCP 브리지를 띄우고 그 URL만 SDK에 넘긴다.

// routed-mcp-bridge.ts — 127.0.0.1에 임의 포트 + 비밀 경로
const secret = randomUUID();
server.listen(0, "127.0.0.1", ...);   // /mcp/<secret> 만 응답, 그 외 404
return { url: `http://127.0.0.1:${port}/mcp/${secret}`, close };

브리지는 도구 이름·설명을 훑어 읽기 전용 휴리스틱(read/search/list/get… 은 있고 send/create/delete… 는 없으면 read-only)으로 MCP annotations(readOnlyHint·destructiveHint)를 자동으로 채운다. Claude Code가 도구의 위험도를 판단할 근거를 만들어 주는 것이다.

설계의 중심축 ⑤ — 원격 대신 쓰는 로컬 Docker 샌드박스

원본 앱은 코드 실행을 원격 "box"에 맡긴다. 이 프로젝트는 그 자리에 소유형 로컬 컨테이너를 끼운다. 안전장치가 촘촘하다.

설계의 중심축 ⑥ — 정직한 안전 봉합선(seam)들

재구성 빌드는 원본의 자동 업데이트·Sentry·텔레메트리를 패키징 경계에서 끈다. 방식은 멱등한 환경변수 prepend 하나다.

// build-asar.mjs — electron-main 폴백 앞에 붙는 가드(멱등)
process.env.SAND_DISABLE_UPDATES  ??= "1";
process.env.SAND_DISABLE_SENTRY   ??= "1";
process.env.SAND_DISABLE_TELEMETRY??= "1";

런타임을 "clean 소스에서 컴파일"로 승격하는 것도 fail-closed다. electron-main은 16개, host는 8개의 바인딩 슬롯을 선언해 두고, 각 슬롯이 원본 main.cjs의 특정 줄·문자열(앵커)과 clean 소스 모듈에 모두 연결될 때만 clean으로 인정한다. 하나라도 미연결이면 "증거 부족"으로 남기고 원본 바이트 폴백(+가드)을 쓴다 — 그래서 electron-main은 기본 clean, host는 기본 폴백이다. 이 경계는 숨겨진 구멍이 아니라 문서화된 상태다.

5디렉토리 구조 해부

구조를 읽는 열쇠는 세 가지 성격의 폴더가 섞여 있다는 점이다.

frontend/src/의 세 하위 폴더가 특히 재구성 철학을 보여 준다 — production/(원본에 얹는 좁은 패치 컴포넌트), recovered/(증거로 되살린 기능들, features/settings·terminal·permissions 등 폴더별 정리), dev/(DOM 인스펙터가 든 개발 셸). "확인된 것"과 "패치한 것"과 "실험 중인 것"이 폴더로 분리돼 있다.

6학습 포인트

① 리버스 엔지니어링을 "규율 있는 공학"으로 하는 법

가장 큰 배움은 코드가 아니라 태도다. 증거 앵커 없이는 아무것도 주장하지 않기, 불확실성을 파일에 집계하기, "타입체크 통과 ≠ 출처 증명"으로 선 긋기, 추측을 릴리스 결함으로 취급하기. 이 규칙들이 감사 스크립트로 기계화돼 있어, 원칙이 말이 아니라 CI로 강제되는 걸 직접 볼 수 있다.

② Electron 앱의 해부학

app.asar 구조, main/preload/renderer 3층 분리, preload가 왜 "좁은 신뢰 브리지"인지, Info.plist의 번들 정체성(CFBundleIdentifier·CFBundleURLTypes·ElectronAsarIntegrity), 그리고 네이티브 애드온을 Electron ABI에 맞춰 재빌드하는 이유. 데스크톱 앱을 만들거나 분석할 때 그대로 쓰이는 지식이다.

③ 결정론적·재현 가능 빌드

체크섬 고정 입력, 해시 기록 산출물, 독립 재검증의 3단 구조. import.meta.url을 배너 상수로 define해 ESM 소스를 바이트 재현 가능한 CJS로 뽑는 트릭, ASAR 재포장 시 무결성 스냅샷·롤백, git 트리 오브젝트 비교로 "무손실 공개"를 증명하는 법까지. 공급망 신뢰가 화두인 지금 값진 패턴이다.

④ 멀티 제공자 추론 라우터 설계

제공자별 어댑터(각기 다른 스트리밍 API를 하나의 fullStream으로 통일), 에이전트별 직렬 큐, 로컬/원격 트랜스크립트 병합, 턴 번호 충돌 회피, OAuth 토큰 재사용과 401 리프레시, 루프백 MCP 브리지. "여러 LLM을 한 UI에 붙이는" 앱을 만든다면 이 파일들이 교과서다.

7하드웨어·시스템 요구사항

8직접 해볼 수 있는 실습 과제

9관련 기술 심화 학습 로드맵

10핵심 키워드 사전

11참고 링크