cindy 딥다이브
— Claude Code·Codex를 한 앱에 묶은 로컬 에이전트 클라이언트

1프로젝트 한줄 요약

2왜 주목받는가

TrendShift 큐에서 20위로 잡힌 레포입니다. 순위 자체는 모멘텀 점수라 이유를 단정할 수 없지만, 저장소에서 확인되는 차별점은 세 가지입니다.

비슷한 도구와의 거리

3기술 스택 전체 지도

백엔드에 해당하는 것

서버는 별도 저장소입니다. 이 저장소에서 “백엔드”에 가까운 것은 두 가지입니다. 하나는 Electron main 프로세스(apps/desktop/src/main)로 DB, IPC, 에이전트 프로세스 관리, 스케줄러 호스트, 디바이스 링크를 맡습니다. 다른 하나는 요청 필드를 정리해 주는 anthropic-compat-proxy 같은 로컬 루프백 프록시입니다. 이 프록시는 Claude Code SDK가 비Anthropic 모델 게이트웨이와 대화할 때 Anthropic 전용 필드를 걷어냅니다.

프론트엔드

Electron renderer(src/renderer)와 Expo 앱(apps/mobile)이 각각 React로 작성됩니다. 디자인 토큰은 packages/design-tokens와 루트 DESIGN.md가 규정하고, CI에 하드코딩 색상 감사·디자인 근거 PR 검사 워크플로가 따로 있습니다.

인프라·배포

GitHub Actions 워크플로 4개(ci.yml, pr-code-review.yml, pr-design-basis.yml, pr-template-rules.yml), DCO 서명 검사, Dependabot이 있습니다. 데스크톱 빌드는 Electron Forge, 모바일은 EAS(eas.json)입니다.

4아키텍처 심화 분석

핵심은 packages/maker-core입니다. package.json 설명은 “agent abstractions, session orchestration, zero Electron deps”이고, index.ts 머리 주석이 “본 패키지는 Electron 의존이 없다. 모든 IO(safeStorage, userData, spawn 경로)는 host 층이 주입한다”고 못 박습니다. 그래서 같은 코어를 데스크톱과 cindy-headless가 함께 씁니다.

1. 하네스 추상화: BaseAgent

agents/base-agent.ts는 Claude Code·Codex 등을 통일하는 추상 클래스입니다. 주석의 설계 요점은 두 가지입니다. 지원하지 않는 기능은 기본적으로 NotSupportedError를 던지고, 하위 클래스가 capabilities에 맞춰 덮어씁니다. 의존성은 주입받되 사용 방식은 하위 클래스가 정합니다. 즉 “하네스마다 되는 일이 다르다”를 숨기지 않고 능력 표로 드러내는 방식입니다.

권한 모드도 이 차이를 그대로 반영합니다.

// packages/maker-core/src/types/common.ts
export type PermissionMode =
  | 'ask' | 'default' | 'acceptEdits'
  | 'plan' | 'auto' | 'bypassPermissions';
// 주석: Claude Code는 전체 집합, Codex는 ask / auto / bypassPermissions 부분집합.
//       나머지는 NotSupportedError

2. 세션 오케스트레이션

session.ts(3,632줄)와 maker.ts(1,832줄)가 세션 생명주기를 맡고, 테스트가 파일명으로 쪼개져 있어 다루는 문제를 알 수 있습니다: session.tool-loop, session.turn-stall, session.vision-bridge, session.async-user-questions, session-send-outcome. 데스크톱 쪽에는 AgentInputCoordinator가 “전송·큐잉·끼어들기·중지 후 계속” 입력 트랜잭션을 소유한다고 docs/dev-rules/repo-map.md가 적습니다.

3. 도구는 MCP로 노출

packages/lizi-mcps/src에 인프로세스 MCP 서버들이 있습니다. computer/tools.ts는 get_accessibility_tree, launch_app, click, type_text, press_key, hotkey, scroll, start_recording, replay_trajectory 등을 정의합니다. 화면 픽셀 추측이 아니라 접근성 트리와 창 상태(get_window_state, verify_state)를 기준으로 조작하는 구성입니다. android/는 폰 제어, orca/는 아래 협업 도구입니다.

4. Orca: Lead와 Worker

docs/dev-rules/orca-team-architecture.md가 권위 문서입니다. Lead 세션이 작업을 쪼개 배정하고 검수하며, Worker는 일회성 서브에이전트가 아니라 자기 모델·도구 호출 흐름·컨텍스트·기록을 가진 완전한 세션입니다. 로컬 Claude Code·Codex·Pi가 Lead나 Worker가 될 수 있고, SSH 원격 세션과 device-link 피어도 지원한다고 적혀 있습니다. lizi-mcps/src/orca/server.ts에는 get_workspace_info, worker_status, read_worker 같은 도구가 있는데, 설명문이 “정상 폴링에 쓰지 말라, Worker가 끝나면 알아서 알려준다”고 경고합니다. 상태를 계속 묻는 루프가 아니라 완료 통지로 움직이게 설계했다는 증거입니다.

5. 스케줄러와 메모리

maker-scheduler는 ScheduleKind = 'cron'만 정의하고 실행 모드는 'agent' | 'script'입니다. 실행 단계에 queued(대기 전용)를 두면서 동시 실행 한도에서 제외한 이유가 주석에 남아 있습니다. 2026-07-29 사고로 대기 중인 하트비트 4개가 모든 슬롯을 차지해 다른 작업이 3.5시간 멈췄다는 기록입니다. 메모리는 maker-core/src/memory(manager.ts, fts.ts, scope-resolver.ts)가 범위(scope)를 해석하고 전문 검색(FTS)을 제공합니다.

6. 모델 계층

packages/model-providers는 catalog.ts, byok.ts, localModelCatalog.ts, modelAccessValidator.ts 등으로 공식·직접 키·로컬 모델 목록과 가격·추론 단계 메타데이터를 층층이 합칩니다. responses-chat-bridge, anthropic-responses-bridge, responses-anthropic-bridge 같은 변환 패키지는 서로 다른 API 형식을 이어 붙이는 용도로 보입니다(이름과 구조에서 추정한 부분입니다).

2026-10-26 개정: 플러그인 하네스 브리지와 채팅 캐시

이번에는 커밋 abcc0e42b4013f0f58de312a94a3c1807b6e4467까지의 변경 중 실행 경계·이력 저장·시작 인증을 중심으로 읽었습니다. 아래의 큰 디렉터리별 파일 수는 초판 관측값이며 현재 개수로 다시 센 값이 아닙니다.

• 플러그인 하네스 브리지: cindy.harness()가 runtime·usage·status·messages·tool-content 읽기, 이벤트·훅·중단·수동 압축을 이름별 선언과 승인으로 나눕니다. harnessSlot.ts는 선언됨·승인됨·실제 연결됨을 각각 표시하고 runtimeId·turnGeneration을 검사합니다. 본문 읽기와 도구 내용 읽기는 별도 권한이며, 이 경로는 로컬 사용자 주 작업에 한정됩니다. IM·예약 작업·Orca Worker·다른 기기로 자동 확장되지 않습니다.
• Codex 훅 연결: agents/codex/harness-hooks.ts는 현재 루트 thread·turn과 실제 native hook/started 수신 이력을 묶어 일반 모델의 도구 호출이 훅 콜백인 척하지 못하게 합니다. 원래 설정에 활성화·신뢰된 cindy/harness_hook이 있어야 연결 상태가 됩니다. 플러그인을 승인하는 것만으로 네이티브 훅 신뢰를 만들지는 않습니다. 문서가 밝히듯 네이티브 도구 훅 오류는 fail open일 수 있어 전체 실행의 강제 보안 경계로 삼을 수 없습니다.
• 대화 이력 캐시: 마이그레이션 0133이 chat_cache_rooms와 chat_cache_messages를 추가합니다. namespace·room별 상태/메시지를 저장하고, chatCacheTx.ts가 version과 generation을 대조해 충돌을 반환합니다. 커서·페이지 범위와 메시지 변경을 하나의 SQLite 트랜잭션으로 반영하므로 새 커서에 옛 메시지가 붙는 불일치를 줄이는 구조입니다. 이는 서버 대화의 폐기 가능한 사본이며 모델의 전체 실행 이력이 아닙니다.
• 시작 인증 대기: authStartupGate.ts는 토큰 교체 중인 요청 자체를 취소하지 않고 UI가 기다리는 시간만 제한합니다. 늦은 갱신 결과는 인증 epoch를 확인하고 적용하며, 사용자가 그사이 로그인·로그아웃했다면 이전 결과가 새 상태를 덮지 못하게 합니다.

수동 압축은 별도 백그라운드 압축기를 만드는 기능이 아닙니다. 브리지 문서는 10초 뒤 결과를 모르는 경우 unknown을 반환하고 다른 requestId로 자동 재시도하지 않도록 합니다. 위 동작은 코드와 문서 대조이며 앱 실행·로그인·모델 호출은 검증하지 않았습니다.

2026-10-27 개정: 최종 응답 전달과 저장 모델 복구

현재 82d44ec3eedb923e268ae963114a09849ee62655에서는 Telegram 최종 응답이 긴 rate limit 대기에 막혀 작업 종료까지 지연되던 경로를 바꿨습니다. telegramTurnCarrier.ts는 진행 전송 대기·최종 분할·정리를 포함해 클라이언트 처리에 120초 상한을 둡니다. 기한이 지나면 기존 carrier를 닫고 false를 반환해 서버의 기존 발송 경로로 책임을 돌립니다. 제한 시간을 억지로 줄여 재요청하는 방식이 아니며, 늦은 실패 회신이나 진행 업데이트가 옛 메시지를 다시 보내지 않게 합니다.

봇의 저장된 모델 선택을 다시 승인하는 과정도 버전으로 기록합니다. updateBotProfile()은 acceptSavedModelSelectionVersion이 현재 버전과 맞는지 확인하고, 동일한 선택을 다시 승인해도 DB 버전을 올릴 수 있습니다. 다른 기기에서 설정이 바뀐 상태를 오래된 화면이 덮지 않도록 하는 조건입니다.

createBotModelRouteApplier()는 선택을 대기열에 넣었다는 사실만으로 복구 표시를 지우지 않습니다. 하네스 전환 대기와 같은 하네스 내 runtime 변경 대기를 모두 확인하고, 실제 적용 완료 뒤 정리합니다. 대응 단위 테스트는 대기 중 취소·재시도와 적용 완료 후 표시 제거를 다룹니다. 이 문서에서는 테스트 소스를 읽었고 앱·모델·Telegram 전송은 실행하지 않았습니다.

5디렉토리 구조 해부

cindy/
├─ apps/
│  ├─ desktop/            9,936개  Electron 클라이언트 (main / renderer / preload / shared)
│  ├─ mobile/             2,381개  Expo 앱 + modules/ 네이티브 모듈
│  ├─ cindy-headless/        82개  CLI·Harbor 어댑터 (Electron 없이 maker-core 사용)
│  └─ android-platform-tools-bin/   윈도우 패키징용 (바이너리는 커밋하지 않음)
├─ packages/              (34개)
│  ├─ opencli-vendor/     1,443개  OpenCLI 레시피 벤더링 (jackwener/opencli)
│  ├─ browser-control-runtime/ 412  브라우저 제어
│  ├─ maker-core/           405   에이전트 코어
│  ├─ lizi-mcps/            397   MCP 서버 묶음
│  ├─ maker-shared/         240   공용 타입·판정
│  ├─ device-link/          132   기기 간 링크 프로토콜
│  ├─ lizi-im/ · model-providers/ · model-compat/ · voice-input-core/ ...
├─ docs/                  dev-rules(46) · product-rules(37) · design-rules(32) · legal ...
├─ config/                endpoint.json (공식 서비스 엔드포인트)
├─ scripts/               ensure-agent-binaries.mjs, test-workspaces.mjs ...
├─ tools/                 claude / codex-package / ripgrep / pi 바이너리 갱신 스크립트
└─ AGENTS.md · CLAUDE.md · DESIGN.md · CONTRIBUTING*.md · SECURITY*.md

데스크톱 main 프로세스 안쪽

이 폴더 이름만으로 정확한 책임을 단정하기는 어렵습니다. 위 “맡은 일”은 문서(repo-map.md)에서 확인되거나 파일명에서 읽은 것이며, 확인하려면 각 폴더의 __tests__를 보는 편이 빠릅니다.

규칙 문서가 코드만큼 중요하다

루트 AGENTS.md는 Codex와 Claude Code가 함께 쓰는 정본이고 CLAUDE.md는 @AGENTS.md 한 줄만 둡니다. 수정 범위별로 읽어야 할 문서를 표로 연결하고(예: Desktop 변경 → docs/dev-rules/desktop-development.md), 모델 카탈로그·자격증명 저장·미디어 프로토콜처럼 사고가 나기 쉬운 영역은 “수정 전 반드시 읽을 것”으로 지정합니다. 에이전트가 코드를 고치는 저장소의 모범적인 운영 사례입니다.

6학습 포인트 (기술별)

이 저장소를 읽는 가장 좋은 순서는 UI가 아니라 maker-core의 타입(types/)과 BaseAgent이고, 그 다음 Orca 문서입니다. 나머지는 이 뼈대에 붙은 기능이기 때문입니다.

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

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

git clone https://github.com/makecindy/cindy.git
cd cindy
git ls-files | awk -F/ '{print $1"/"$2}' | sort | uniq -c | sort -rn | head
sed -n 1,60p docs/dev-rules/repo-map.md

pnpm install            # postinstall이 바이너리 내려받음 (위 경고 참고)
pnpm restart:desktop:remote -- --mock

interface MiniAgent {
  capabilities: { plan: boolean; resume: boolean };
  send(msg: string): AsyncIterable<AgentEvent>;
  setPermission(mode: 'ask' | 'auto'): void; // 미지원이면 NotSupportedError
}

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

함께 보면 좋은 외부 주제: MCP 명세, Electron 보안 모델(contextIsolation, IPC 경계), Drizzle ORM 마이그레이션, Expo 개발 빌드.

10핵심 키워드 사전

11참고 링크

• github.com/makecindy/cindy — 저장소
• cindy.app — 공식 사이트와 다운로드
• AGENTS.md — 엔지니어링 규칙과 문서 색인 (중국어 문서가 많음)
• docs/dev-rules/repo-map.md — 기능별 코드 위치
• orca-team-architecture.md — 다중 에이전트 협업 정본
• CONTRIBUTING.en.md — 기여 절차
• jackwener/opencli — 벤더링된 OpenCLI 원본

개정 근거: 플러그인 브리지 계약 · 캐시 트랜잭션 · 인증 시작 게이트.

이번 개정 근거: 최종 전송 기한 · 모델 적용·복구 표시 · 설정 버전 검증.