deer-flow/llm-space 딥다이브
— 에이전트를 "한 걸음씩" 뜯어보는 실험실

1프로젝트 한 줄 요약

deer-flow/llm-space(제품명 LLM Space)는 "에이전트를 프로토타이핑하는 로컬 데스크톱 IDE"다. 보통의 챗 앱은 당신이 메시지를 치면 AI가 알아서 도구를 다 돌리고 최종 답만 보여준다. LLM Space는 정반대다 — 모델이 "이 도구를 이런 인자로 부르겠다"고 말하는 순간 루프를 멈추고, 그 도구 호출을 화면에 카드로 띄워 사람이 인자를 확인·수정하거나, 결과를 손으로 채워 넣거나, 재생성하게 한다. 즉 "생각→도구→관찰"이라는 에이전트 루프의 매 한 걸음을 사람이 직접 밟는 디버거에 가깝다.

작업의 단위는 스레드(Thread)다. 스레드 하나가 곧 저장 가능한 실험 파일(JSON) 하나이고, 그 안에 제목·모델과 파라미터·시스템 프롬프트·변수·도구 목록·메시지들·도구 호출·실행 이력·평가가 통째로 담긴다. 그래서 "모델만 바꿔서 다시" "이 도구 인자를 이렇게 고쳐서 다시" "실패했던 그 실행을 그대로 다시" 같은 실험을 파일 하나로 반복할 수 있다. 이름은 "LLM Space(엘엘엠 공간)"지만, 실체는 프롬프트·도구·모델을 이리저리 조립하며 노는 에이전트 실험실이다.

2왜 지금 주목받는가

2026년, 누구나 에이전트를 만들 수 있게 되면서 진짜 어려운 문제는 "내 에이전트가 왜 저기서 헛발질했는지"를 알아내는 것으로 옮겨 갔다. 프롬프트를 한 줄 바꾸면 결과가 통째로 달라지는데, 챗 UI로는 그 안에서 무슨 일이 벌어졌는지 보이지 않는다. LLM Space는 바로 이 지점을 판다 — 에이전트의 실행을 스텝 단위로 열어 보고, 실패를 리플레이하고, 프롬프트·모델·도구를 바꿔 가며 A/B로 채점하게 한다. 게다가 이걸 만든 팀이 바이트댄스의 유명 딥리서치 프레임워크 DeerFlow 팀이고, "우리가 DeerFlow를 디버깅하려고 실제로 쓰는 도구"라는 도그푸딩 서사가 신뢰를 얹는다.

주목 포인트 1 — "자동으로 안 돌리는" 에이전트라는 역발상

대부분의 에이전트 도구는 "얼마나 자율적으로 끝까지 해내는가"를 자랑한다. LLM Space는 반대로 기본값이 '수동'이다. 모델이 도구를 부르겠다고 하면 거기서 멈추고, 사용자가 재생 버튼(하나 실행)·"Call tools"(대기 중인 것 전부 병렬 실행)·"Continue"(루프 한 칸 전진)를 눌러야 나아간다. 원한다면 "Enable ReAct loop"를 켜서 사람 개입이 필요한 지점 전까지 자동으로 굴릴 수도 있다. "자율성"과 "관찰 가능성"을 맞바꾼 이 설계가, 에이전트를 디버깅하려는 개발자에게 정확히 맞는다.

주목 포인트 2 — 실패를 다시 돌려 보고, 점수로 비교한다

실행 이력(Run History)은 각 실행을 불변 스냅샷으로 남긴다. 그래서 "어제 실패한 그 실행"을 골라 그대로 다시 밟아 볼 수 있다(replay). 더 나아가 두 실행을 왼쪽/오른쪽에 놓고 채점한다 — 간단하게는 "어느 쪽이 낫다(verdict)", 정교하게는 2~6개 기준의 루브릭(각 1~5점)으로. 점수는 실행별 평균과 B − A 차이로 계산된다. 흥미로운 함정: 이 평가는 100% 사람이 매긴다 — LLM이 심판(LLM-as-judge)으로 끼어들지 않는다. 채점표를 나중에 고쳐도 과거 기록은 불변으로 남는다.

주목 포인트 3 — 두 개의 몸, 하나의 데이터

같은 소스에서 두 에디션이 나온다. 기본 LLM Space는 OS의 시스템 웹뷰를 쓰는 가벼운 몸(다운로드 ~27MB, 메모리·배터리 절약), LLM Space Performance는 크로미움을 CEF로 임베드한 무거운 몸(~130MB, 무거운 화면도 매끈). 둘은 같은 ~/.llm-space 데이터를 공유하되 업데이트 피드는 따로 간다. "가벼움 vs 성능"을 사용자가 고르게 한 영리한 이원화다.

3기술 스택 전체 지도

이 저장소엔 Rust도 Go도 Python도 없다(파이썬은 CI에서 YAML 검증용 한 줄이 전부). 거의 순수 TypeScript/TSX 프로젝트이고, 런타임·패키지 매니저·빌드가 전부 Bun으로 돈다. 스택을 이해하는 축은 셋이다 — "무엇이 앱을 실행하는가(껍데기)", "무엇이 화면을 그리는가(렌더러)", "무엇이 에이전트를 돌리는가(엔진)".

껍데기·도구 (런타임 · 빌드 레이어)

화면 (React 렌더러 레이어)

두뇌 (에이전트 엔진 레이어)

4아키텍처 심화 분석

4-1. 전체 데이터 흐름 — "Run" 한 번이 거치는 길

LLM Space를 이해하는 가장 빠른 길은 사용자가 Run(실행)을 누른 순간부터 화면에 글자가 흐르기까지의 경로를 따라가는 것이다. 웹뷰(React)와 메인(Bun)이 분리돼 있으니, 그 사이를 어떻게 건너는지가 관건이다. 핵심 반전은 Electrobun의 RPC에는 '스트리밍'이 없다는 점 — 그래서 이 앱은 한 번 쏘고 잊는(fire-and-forget) 메시지들을 streamId로 엮어 스트림을 흉내 낸다.

여기서 계약서 역할을 하는 것이 src/shared/rpc.ts의 DesktopRPCType다. 요청/응답형(웹뷰→메인, 답을 기다림)에는 availableModels·프로바이더 CRUD·파일 조작(fsLs/fsRead/fsWrite/…)이 있고, 한 번 쏘고 잊는 메시지형에 스트리밍 3종(sendStreamThreadRequest·receiveStreamThreadResponse·abortStreamThread)이 있다. "스트리밍 없는 채널 위에 스트림을 얹는" 이 패턴은 그 자체로 좋은 교보재다.

4-2. 스텝별 정지 — 이 앱의 심장

이제 이 프로젝트를 "또 하나의 챗 앱"이 아니게 만드는 지점이다. 비밀은 놀랍도록 단순하다. core/server/agent/stream.ts에서 도구들을 에이전트 루프에 넘길 때 { stepByStep: true } 옵션을 준다. 그러면 모든 도구의 execute()가 실제로 도구를 실행하는 대신 { terminate: true }를 돌려주고 루프를 그 자리에서 멈춘다.

// core/server/agent/stream.ts — 스텝별 정지의 핵심 (요지)
const agentTools = _convertToAgentTools(tools, {
    stepByStep: true,     // ← 이 한 줄이 "수동 디버거"를 만든다
});
// stepByStep 이면 각 도구의 execute() 는 도구를 '실행'하지 않고
// { terminate: true, content: [...] } 를 반환 → 루프가 도구 호출 직후 멈춤
// → UI 가 그 도구 호출 카드를 띄우고 사람의 판단을 기다린다

멈춰 선 루프 앞에서 사용자는 세 가지를 할 수 있다. ① 도구 카드의 재생 버튼으로 그 도구 하나만 실행, ② "Call tools"로 대기 중인 도구를 전부 병렬 실행, ③ "Continue"로 ReAct 루프를 한 칸 전진. 그리고 인자를 고치거나 도구 결과를 가짜로 채워 넣어 특정 엣지 케이스를 재현할 수도 있다. "Enable ReAct loop"를 켜면 사람 개입이 필요한 스텝 전까지 자동으로 굴러간다. 자율성을 끄고 관찰 가능성을 켠 이 스위치가, 디버깅 도구로서의 정체성을 만든다.

4-3. 리플레이와 평가 — 불변 스냅샷의 힘

리플레이(replay)는 실행 이력에 남는 ThreadSnapshot으로 돌아간다. 되돌리기/다시하기(stores/thread-history.ts)는 복사-후-쓰기(copy-on-write) 참조를 써서 스냅샷 하나가 사실상 포인터 이동(O(1))이다 — 스레드를 통째로 복제하지 않는다(개수 + 보관 이미지 바이트 예산으로 상한). 평가(evaluate)는 두 실행(leftRunId/rightRunId)을 골라 비교한다.

점수는 실행별 가중치 없는 평균과 B − A 델타(evaluationScoreDelta)로 계산된다. 다시 강조할 함정 — 이 평가는 전부 사람 손이다. "성능 평가"라는 말에 자동 채점을 기대하면 안 된다. 대신 채점의 기록이 불변이라, 프롬프트를 바꿔 가며 실험한 결과를 신뢰 가능한 히스토리로 쌓을 수 있다.

4-4. HostServices 이음새 — 데스크톱과 웹이 같은 UI를 쓰는 비결

LLM Space에는 정적 웹사이트(공유된 스레드를 열어 보는 뷰어)도 딸려 있다. 그런데 데스크톱 앱과 웹사이트가 똑같은 React UI(packages/ui의 Thread Playground)를 공유한다. 어떻게? 파일 접근·모델 호출 같은 "환경에 의존하는 일"을 HostServicesProvider/useHostServices()라는 이음새(seam) 뒤로 숨겼기 때문이다.

// 같은 Thread Playground 컴포넌트, 주입되는 host 만 다르다
// 데스크톱 (apps/desktop/src/host/host-services.tsx)
<DesktopHostProvider>      // 진짜 Electrobun RPC 기반 구현 주입
   <ThreadPlayground />     //   fs 읽기/쓰기, 모델 호출이 실제로 동작
</DesktopHostProvider>

// 웹사이트 (web/)
<HostServicesProvider host={{ presentational: true }}>
   <ThreadPlayground />     // 표시 전용 no-op 스텁 — 클릭해도 실행은 안 됨
</HostServicesProvider>

덕분에 packages/ui는 Electrobun을 전혀 몰라도 되는(=의존하지 않는) 순수 UI가 되고, 같은 코드가 데스크톱에선 살아 움직이고 웹에선 읽기 전용으로 렌더된다. "환경 의존을 인터페이스로 뽑아 주입한다"는 의존성 역전의 교과서적 적용이다.

5디렉토리 · 모노레포 구조 해부

저장소는 Bun 워크스페이스 모노레포다. 크게 재사용 라이브러리(packages/), 실제 앱(apps/desktop), 웹사이트(web)로 나뉜다. "무엇을 먼저 읽어야 하는가" 관점의 지도는 아래와 같다.

꼭 먼저 볼 곳

6학습 포인트

배울 것 1 — 스트리밍 없는 채널 위에 스트림을 얹기

가장 재사용성 높은 기법. Electrobun RPC엔 스트리밍이 없는데, LLM 응답은 스트림이다. LLM Space는 streamId로 태깅한 '쏘고 잊는' 메시지들을 웹뷰에서 async iterator로 재조립해 이 간극을 메운다. WebSocket이 없거나, IPC가 요청/응답만 되는 어떤 환경에서든 그대로 응용할 수 있는 패턴이다. "전송 계층의 제약을 상위 추상화로 감추는 법"의 실물 교보재.

배울 것 2 — 자율성을 끄면 관찰 가능성이 켜진다

{ stepByStep: true } 한 줄로 도구의 execute()가 terminate:true를 뱉게 만들어, 에이전트 루프를 도구 호출마다 멈추는 설계. "얼마나 자율적인가"만 좇던 흐름에서 벗어나, "얼마나 들여다볼 수 있는가"를 1급 기능으로 끌어올린 발상이다. 에이전트를 디버깅·교육·감사해야 하는 상황이라면 반드시 참고할 만하다.

배울 것 3 — 환경 의존을 인터페이스로 뽑아 주입하기

HostServicesProvider/useHostServices() 이음새로 파일·모델 호출 같은 환경 의존을 숨겨, 같은 React UI가 데스크톱(실제 구현)과 웹(표시 전용 스텁)에서 모두 돈다. 의존성 역전(DIP)을 "한 코드베이스, 두 실행 환경"으로 구현한 깔끔한 사례. 테스트용 mock 주입, Storybook, 멀티 플랫폼 앱 어디에나 통하는 사고법이다.

배울 것 4 — 파일이 곧 데이터베이스인 로컬 퍼스트

SQLite도 ORM도 없이 ~/.llm-space 아래 JSON·마크다운 파일로 모든 것을 저장한다. 스레드는 사람이 읽을 수 있는 JSON이라 Git으로 diff·버전 관리·공유가 된다. 쓰기는 임시 파일→rename 원자적 교체로 안전하게. "DB를 두지 않고도 견고한 영속성을 얻는 법", 그리고 "사용자가 자기 데이터를 소유한다"는 로컬 퍼스트 철학의 실전 구현이다.

배울 것 5 — 사람이 매기는 평가 루프(불변 스냅샷)

두 실행을 루브릭(2~6기준, 1~5점)으로 채점하고 B − A 델타로 비교하되, 평가는 안정적 run ID를 키로 하는 불변 스냅샷으로 저장된다. LLM 심판을 끼우지 않아 재현 가능하고 신뢰할 수 있는 실험 기록을 남긴다. "프롬프트 실험을 어떻게 과학적으로 관리하는가"의 미니멀한 답. LLM-as-judge의 편향이 부담스러운 상황에서 특히 참고할 만하다.

배울 것 6 — Bun · Electrobun 모노레포 운영

Node·npm 없이 Bun 하나로 런타임·패키지·테스트를 통일하고, mise로 툴체인을 못 박고, "환경을 아는 코드"를 apps/desktop에만 격리한 워크스페이스 설계. 렌더러 빌드가 --max-old-space-size=4096 없이는 14701개 모듈에서 OOM 나던 실전 교훈(build:view)까지 남아 있다. "가벼운 대안 스택으로 크로스 플랫폼 데스크톱 앱을 짜는 법"을 통째로 볼 수 있다.

7시스템 · 실행 요구사항

대부분의 사용자는 릴리스에서 macOS 앱을 내려받으면 된다. 반면 소스에서 빌드하려면 Bun 툴체인이 필요하다. 아래 표가 두 경로를 가른다.

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

먼저 설치. macOS라면 릴리스에서 DMG를, 소스를 볼 거라면 클론 후 Bun으로.

# 소스에서 실행 (macOS + Bun 1.3)
git clone https://github.com/deer-flow/llm-space.git
cd llm-space
bun install          # 또는 mise run setup (고정 툴체인)
mise run dev         # Vite HMR + electrobun dev

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

10핵심 키워드 사전

11참고 링크

공식
· GitHub 저장소: github.com/deer-flow/llm-space (MIT · Electrobun 데스크톱 앱)
· TrendShift 카드: trendshift.io/repositories/83147 (Daily #13 · #AI agent)
· 공식 사이트: deer-flow.github.io/llm-space (랜딩 + 공유 스레드 뷰어)
· 자매 프로젝트(별개): github.com/bytedance/deer-flow (DeerFlow 딥리서치 — 이 문서 폴더의 deer-flow-deep-dive.html)

저장소 안에서 꼭 읽을 것
· packages/core/server/agent/stream.ts — streamAgent() + 스텝별 정지(엔진의 심장)
· packages/core/client/{api,reducer}.ts — streamThread() · reduceMessages()
· packages/ui/src/components/thread-playground/ — 제품의 얼굴(Build·Trace·Debug·Evaluate)
· apps/desktop/src/shared/{rpc,commands}.ts — 웹뷰↔메인 계약서
· packages/core/types/ — 스레드·모델·도구 typebox 스키마
· docs/core-concepts.md — 스레드 JSON 스키마 공식 설명

곁들여 학습
· Bun · Electrobun — Node 없는 런타임 · Bun 기반 데스크톱 셸
· React 19 · Zustand · TanStack Query · Tailwind v4 · shadcn/radix
· @earendil-works/pi(pi-agent-core/pi-ai) — 경량 에이전트 프레임워크
· MCP(Model Context Protocol) · SKILL.md 스킬(Claude Code/Codex 호환)
· 이미 분석한 다른 에이전트 도구 딥다이브와 비교(§인덱스 cat-agents — DeepTutor·airi 등)