dyad-sh/dyad 딥다이브
— "Lovable를 내 노트북 안에" 넣은 로컬 AI 코딩 에이전트

1한 줄 정체

Dyad는 AI 모델이 아니라 "AI가 짠 코드를 실제 프로젝트 폴더에 적용해 주는 로컬 프로그램"이다. package.json의 한 줄 설명 그대로 "Free, local, open-source AI app builder"다. 겉모습은 Lovable·v0·bolt.new 같은 채팅형 앱 빌더와 똑같지만, 그 서비스들이 사용자 코드를 회사 클라우드 서버에 두는 것과 달리 Dyad는 Electron 데스크탑 앱을 다운로드해 실행하는 순간부터 모든 프로젝트 파일이 사용자 디스크(~/dyad-apps 류의 로컬 폴더)에 그대로 존재한다.

기술적으로 핵심은 두 가지다. 하나는 LLM 프로바이더 추상화(Vercel AI SDK 기반, OpenAI·Anthropic·Google·Azure·xAI·Bedrock·OpenRouter·Ollama·LM Studio 등을 갈아 끼울 수 있음)이고, 다른 하나는 <dyad-write> 같은 전용 의사(疑似) XML 태그로 LLM 응답을 구조화해 그 자리에서 실제 파일 쓰기·삭제·이름변경·의존성 설치·git 커밋으로 변환하는 "응답 처리기"다. Electron 자체가 새로 만든 것은 없지만, 이 둘을 엮어 "채팅 한 번 = 실행 가능한 앱 한 조각"을 보장하는 파이프라인이 Dyad의 실체다.

2왜 지금 뜨는가

① 클라우드 AI 앱 빌더의 구독료·락인 피로감

Lovable·v0·bolt.new류는 대부분 사용량 기반 크레딧 과금이고, 프로젝트가 그 회사 인프라 안에 갇힌다. Dyad의 제품 문서(PRODUCT.md)는 타깃 사용자를 정확히 "Lovable/v0/Bolt-style 툴에서 넘어온, 코딩 배경이 없는 논테크니컬 빌더"로 명시한다. "그 경험은 좋았는데 요금과 락인이 싫다"는 사람들을 정면으로 겨냥한 포지셔닝이다.

② BYOK(Bring Your Own Key) + 로컬 모델이라는 선택권

Dyad는 OpenAI/Anthropic/Google 키를 직접 붙이는 것은 물론, Ollama·LM Studio로 완전히 무료·오프라인 모델을 쓸 수도 있다. "AI 앱 빌더를 쓰고 싶지만 특정 회사 모델에 종속되긴 싫다"는 개발자들의 요구와 맞아떨어진다.

③ "로컬 우선(local-first)" 트렌드와 신뢰 문제

AI에게 코드 생성을 맡기는 것 자체가 아직 신뢰 이슈가 있는 상황에서, "적어도 내 파일은 내 디스크에, 되돌리기(git)도 내 손안에" 있다는 사실은 심리적 안전판이 된다. PRODUCT.md는 이를 "Local-first (fast, private, no lock-in) is the core differentiator"라고 스스로 밝힌다.

3무엇을 해결하나

4전체 구조

Dyad는 일반적인 Electron 앱의 교과서적인 3계층 구조를 아주 크게 확장한 형태다. src/main.ts(1,544줄)가 앱 생명주기를 관리하고, src/preload.ts가 contextBridge로 안전한 통로만 열어주며, src/ipc/ipc_host.ts가 도메인별 핸들러 약 50개를 등록한다. 렌더러(React UI)는 이 통로로만 파일시스템·git·AI 호출에 접근할 수 있다.

주목할 점은 "Dyad 자신의 데이터"와 "사용자가 만드는 앱의 데이터"가 완전히 분리돼 있다는 것이다. Dyad 자체의 채팅 기록·설정·앱 목록은 src/db/schema.ts가 정의하는 로컬 SQLite(better-sqlite3 + drizzle-orm)에 저장되고, 사용자가 만드는 앱의 실제 소스코드는 그냥 디스크 위의 일반 폴더(그 자체가 독립된 git 저장소)로 존재한다. Dyad를 지워도 이미 만든 앱 폴더는 평범한 Vite+React 프로젝트로 그대로 남는다.

5핵심 설계·동작 원리

Dyad에서 가장 중요하게 봐야 할 코드는 "AI가 뭐라고 답해야 하는가"(시스템 프롬프트)와 "그 답을 어떻게 실제 파일로 바꾸는가"(응답 처리기) 두 파일이다. 이 둘의 계약이 Dyad라는 제품 전체의 심장이다.

① 코드 생성 계약 — <dyad-write> 의사 XML 태그

src/prompts/system_prompt.ts는 모델에게 "코드는 절대 마크다운 코드블록으로 쓰지 말고, 오직 전용 태그로만 출력하라"고 여러 번 강한 어조로 반복 지시한다. 실제 프롬프트 문구를 보면:

<dyad-write path="src/components/Button.tsx" description="...">
  ...파일 전체 내용...
</dyad-write>

<dyad-rename from="src/components/UserProfile.tsx" to="src/components/ProfileCard.tsx"></dyad-rename>
<dyad-delete path="src/components/Analytics.tsx"></dyad-delete>
<dyad-add-dependency packages="react-hot-toast"></dyad-add-dependency>
<dyad-chat-summary>Adding a new component</dyad-chat-summary>

/* 프롬프트 원문 경고 문구 그대로: */
"ONLY use <dyad-write> tags for ALL code output."
"NO MARKDOWN CODE BLOCKS. USE <dyad-write> EXCLUSIVELY."

이 태그는 HTML/XML 표준이 아니라 Dyad가 자체적으로 정의한 규약이다. dyad-write(파일 생성/전체 덮어쓰기) 외에도 dyad-rename·dyad-delete·dyad-add-dependency(패키지 설치)·dyad-execute-sql(DB 마이그레이션 실행)·dyad-search-replace(부분 수정)·dyad-copy·dyad-command(rebuild/restart/refresh 제안)·dyad-chat-summary(채팅 제목) 태그가 있다.

② 스트리밍 파서 — streamingMessageParser.ts

LLM 응답은 토큰 단위로 조금씩 도착하는데(스트리밍), <dyad-write> 태그가 아직 다 안 닫힌 상태에서도 UI는 "지금까지 써진 코드"를 실시간으로 보여줘야 한다. src/lib/streamingMessageParser.ts(528줄)는 이 미완성 태그를 안전하게 부분 파싱해 채팅 화면에 코드가 타이핑되듯 나타나게 만든다.

③ 적용 엔진 — response_processor.ts (854줄)

응답이 끝나면 src/ipc/processors/response_processor.ts가 전체 텍스트에서 src/ipc/utils/dyad_tag_parser.ts의 getDyadWriteTags·getDyadRenameTags·getDyadDeleteTags 등으로 태그를 모두 뽑아낸 뒤 순서대로 실행한다.

• 쓰기/삭제/이름변경 — path_utils.ts의 safeJoin·assertNotProjectRootPath로 경로 탈출(path traversal)을 막으면서 실제 fs 호출로 파일을 조작한다.
• 의존성 설치 — executeAddDependency.ts가 감지된 패키지 매니저(npm/pnpm)로 실제 설치 명령을 실행한다.
• SQL 실행 — doesSqlMutateSchema()로 스키마 변경 여부를 판단한 뒤 executeSupabaseSql/executeNeonSql로 연결된 백엔드에 바로 쿼리를 던진다.
• git 커밋 — 적용이 끝나면 gitAddAll + gitCommit으로 그 턴에서 바뀐 모든 파일을 커밋 하나로 묶는다. 이것이 UI의 "버전(version)" 되돌리기 기능의 정체다 — 별도 버전 관리 시스템을 만든 게 아니라 순수 git 커밋 히스토리를 재활용한다.

④ LLM 프로바이더 추상화 — get_model_client.ts (679줄)

src/ipc/utils/get_model_client.ts는 Vercel AI SDK(ai 패키지)의 프로바이더 팩토리들(createOpenAI, createAnthropic, createGoogle, createAzure, createXai, createGoogleVertex, createAmazonBedrock, createOpenAICompatible)을 한 함수 뒤로 감춘다. model.provider 문자열 하나로 어떤 회사 API를 부를지 갈아 끼우고, ollama_provider.ts·lm_studio_utils.ts로 완전히 로컬에서 도는 모델도 동일한 인터페이스로 붙일 수 있게 만든다.

유료 Dyad Pro를 켜면 createDyadEngine(llm_engine_provider.ts)이 요청을 Dyad가 직접 운영하는 게이트웨이(DYAD_ENGINE_URL)로 우회시켜, "스마트 파일 컨텍스트"·"레이지 에딧"(전체 파일 재작성 대신 부분 수정) 같은 부가 기능과 dyad/auto/* 자동 모델 별칭을 추가한다. 이 경로가 꺼져 있으면 사용자의 API 키가 각 프로바이더로 직접 나간다 — 즉 기본값은 완전 BYOK, Pro는 그 위에 얹는 부가 레이어다.

⑤ 앱 스캐폴딩 — scaffold/ 폴더와 템플릿

새 앱을 만들 때 기본 "react" 템플릿을 고르면 createFromTemplate.ts가 저장소에 통째로 들어있는 scaffold/ 디렉토리(Vite + React + TypeScript + Tailwind + shadcn/ui 기반의 이미 동작하는 최소 앱)를 그대로 복사해온다. 다른 커뮤니티 템플릿을 고르면 cloneRepo()가 HTTPS GitHub URL만 허용하는 검증을 거쳐 해당 저장소를 클론한 뒤 앱 폴더로 복사한다.

⑥ "에이전트 모드"는 같은 태그로 수렴한다 — 도구 호출 → XML 역변환

Dyad Pro의 로컬 에이전트(src/pro/main/ipc/handlers/local_agent/)는 한 번에 통짜 텍스트를 뱉는 대신 write_file·delete_file·rename_file·add_dependency·execute_sandbox_script 같은 구조화된 AI SDK 도구 호출(tool calling)을 쓴다. 그런데 tools/write_file.ts의 buildXml() 함수를 보면, 이 도구 호출 결과를 다시 <dyad-write path="...">...</dyad-write> 형태의 같은 XML 문자열로 역변환해 돌려준다. 즉 "한 방에 텍스트로 답하는 기본 모드"와 "단계적으로 도구를 부르는 에이전트 모드"가 서로 다른 입력 방식을 쓰면서도, 결국 같은 response_processor.ts 파이프라인 하나로 수렴하도록 설계돼 있다 — 적용 로직을 두 번 만들지 않으려는 선택이다.

에이전트가 임의 스크립트를 돌려야 할 때는 Node.js eval이 아니라 mustardscript라는 별도의 제한된 스크립팅 언어를 worker_threads 안에서(sandbox/runner.ts, sandbox_worker.ts) 실행해, 시간·메모리 제한(limits.ts)을 두고 read_file/list_files/file_stats/write_file 같은 딱 정해진 호스트 함수만 호출하게 한다(capabilities.ts의 SANDBOX_HOST_CALL_NAMES).

⑦ 동시성 제어 — 자체 액터 모델(distributed_machines/)

Dyad는 src/distributed_machines/ 아래 직접 만든 액터(actor) 모델 프레임워크(actor_host.ts, keyed_admission_gate.ts, remote_protocol.ts)를 갖고 있다. 앱 실행 상태·채팅 스트림 같은 것들을 "액터"로 다루면서, 같은 키(예: 같은 앱)에 대한 중복·낡은 명령이 잘못 끼어들지 못하게 "입장 게이트(admission gate)"로 세대(generation)를 관리한다. 이 저장소를 클론한 시점의 가장 최근 커밋(#4139, "keyed actor admission fences")이 정확히 이 모듈을 강화하는 리팩터링이었다 — 여러 창·여러 앱을 동시에 다루는 데스크탑 앱에서 레이스 컨디션을 막는 문제가 여전히 활발히 다뤄지고 있다는 뜻이다.

6기술 스택·의존성

7설치·요구사항

8실제 사용 흐름

9함정·오해 방지

10대안 비교

11정리 · 누가 쓰면 좋은가

Dyad를 한 문장으로 정리하면 "클라우드 AI 앱 빌더의 UX를, 로컬 Electron 앱 + git + BYOK 조합으로 재구현한 오픈코어 도구"다. 핵심 설계는 화려한 신기술이 아니라 "LLM 응답을 태그로 구조화하고, 그 태그를 안전하게 실제 파일 시스템 작업으로 변환하는" 지극히 실용적인 파이프라인이다. 여기에 Vercel AI SDK로 프로바이더를 추상화하고, git 커밋을 버전 관리로 재활용하는 두 가지 선택이 제품 경험 대부분을 만들어낸다.

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

명령은 Dyad 저장소 루트에서 실행한다. 소스 읽기는 의존성 설치 없이 진행할 수 있으며, 테스트 명령은 의존성이 이미 설치된 별도 학습용 사본을 전제로 한다. 아래 과제는 API 키나 외부 서비스 연결 없이 진행할 수 있다.

cat package.json scaffold/package.json
cat scaffold/src/main.tsx scaffold/src/App.tsx scaffold/src/pages/Index.tsx
rg -n 'templateId|scaffold|copyDirectoryRecursive|fullAppPath' src/ipc/handlers/createFromTemplate.ts

<dyad-write path="src/sample.ts">export const value = 1;</dyad-write>

<dyad-write path="src/sample.ts">export const value = 1;

<dyad-write>export const value = 1;</dyad-write>

rg -n 'parseFullMessage|advanceParser|getParserBlocks' src/lib/streamingMessageParser.ts
rg -n 'getDyadWriteTags|parseDyadFileTags|pathMatch' src/ipc/utils/dyad_tag_parser.ts
npm run test:watch -- --run src/lib/streamingMessageParser.test.ts

rg -n 'safeJoin|assertNotProjectRootPath|isProjectRootPath' src/ipc/utils/path_utils.ts
npm run test:watch -- --run src/ipc/utils/path_utils.test.ts -t safeJoin
rg -n 'dyadDeletePaths|assertNotProjectRootPath|prepareDeletePath' src/ipc/processors/response_processor.ts

rg -n 'beginFence|seal|commit|release|assertCurrentGeneration' src/distributed_machines/keyed_admission_gate.ts
rg -n 'deferred|command.resolve|stale-generation' src/distributed_machines/keyed_admission_gate.test.ts
npm run test:watch -- --run src/distributed_machines/keyed_admission_gate.test.ts

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

매주 개념 정리 → 소스 추적 → 결과물 검토 순서로 진행한다. 앞 주에 만든 흐름도를 다음 주의 입력으로 삼으면, 개별 파일이 전체 앱에서 맡는 역할을 놓치지 않을 수 있다.

14핵심 키워드 사전