목표는 용어 암기가 아니다. Dalkkak을 제품 목적, desktop architecture, AI/agent control, memory spine, Mission Control, trust gap까지 네 입으로 설명하게 만드는 것이다.
Dalkkak is a local-first work OS that lets a founder run BYO Claude/Codex agents across panes, worktrees, actions, memory, evidence, and gates.
AI를 대신 호출하는 제품이 아니라, AI worker가 실제 일을 하도록 둘러싼 workspace, memory, approval, verification, mission-control layer다.
여기는 용어 암기장이 아니라 Dalkkak을 설명하기 위한 스택 해부다. 각 카드를 열면 이 기술이 뭔지, 왜 썼는지, 대안과 trade-off가 뭔지, 어디 코드에 있는지, 면접 영어 문장까지 바로 나온다.
사용자 로컬 컴퓨터에서 AI 작업장을 직접 운영하는 제품 구조다.
Dalkkak is local-first because the product needs to control real terminals, files, worktrees, and AI sessions on the user's machine.
desktop app이 terminal, worktree, graph memory, approvals, mission control을 묶는다.
AI worker가 실제 파일/프로세스와 일하려면 브라우저 SaaS만으로는 부족해서 local runtime이 필요하다.
로컬 환경 차이, 권한, 설치, 업데이트, crash recovery를 제품이 책임져야 한다.
순수 web SaaS는 배포/접근성이 좋지만 local process 제어가 약하고, CLI-only는 강력하지만 UX와 memory가 약하다.
ddalkkak apps/desktop, docs/product
로컬 앱이라고 cloud가 전혀 없다는 뜻은 아니다.
renderer, web, server, shared package의 주 언어다.
TypeScript keeps UI, server, and action contracts understandable and refactorable across the monorepo.
React UI, Hono API, action contracts, shared types를 타입 있는 JS로 작성한다.
UI와 tool/action contract를 같은 언어로 정의하면 제품 iteration이 빠르다.
runtime validation이 없으면 type은 외부 입력을 막지 못한다.
Rust만으로 UI까지 짜면 생산성이 낮고, plain JS는 refactor 안정성이 떨어진다.
ddalkkak package.json, apps/*/src, packages/*
TypeScript type과 실제 외부 데이터 검증을 혼동하지 말라.
desktop local backend의 언어다.
Rust owns the dangerous local capabilities: spawning processes, reading files, storing secrets, and streaming terminal output.
PTY, tmux, file access, keyring, graph capture, process lifecycle 같은 OS 가까운 일을 처리한다.
local process control과 safety boundary가 중요해서 memory safety와 시스템 프로그래밍 생태계가 장점이다.
학습 난이도와 compile time이 있고, UI iteration은 TS/React보다 느릴 수 있다.
Node child_process는 빠르게 만들 수 있지만 native packaging/security boundary가 약하고, Go는 단순하지만 Tauri와 직접 결합이 약하다.
apps/desktop/src-tauri/src, Cargo.toml
Rust라고 자동으로 제품이 안전한 건 아니다. exposed command surface가 중요하다.
여러 앱/패키지를 한 repo에서 관리하는 패키지 매니저 구조다.
pnpm workspaces let the desktop, web, server, and shared packages evolve in one repo with explicit internal dependencies.
desktop, web, server, action-sdk, shared packages를 workspace dependency로 연결한다.
monorepo에서 설치 속도와 disk 효율이 좋고, 내부 패키지 변경을 한 번에 검증할 수 있다.
workspace boundary가 흐려지면 package 간 결합이 커질 수 있다.
npm workspaces는 표준성이 좋고, yarn/berry는 기능이 강하고, nx/turborepo는 task orchestration이 강하다.
ddalkkak/package.json, pnpm-workspace.yaml
monorepo는 자동으로 아키텍처가 좋은 게 아니다.
웹 UI와 native Rust backend를 묶는 desktop app framework다.
Tauri gives Dalkkak a lightweight desktop shell where the web UI can safely call native Rust capabilities.
React renderer를 OS WebView에 띄우고, Rust command로 파일/프로세스/알림/업데이트를 처리한다.
Electron보다 가볍고 local capability가 필요해서 browser-only보다 맞다.
OS WebView 차이와 Rust/native boundary를 이해해야 한다. Electron보다 web compatibility가 낮을 수 있다.
Electron은 Chromium 포함이라 일관성이 좋지만 무겁고, native Swift/Kotlin은 platform fit은 좋지만 cross-platform 비용이 크다.
apps/desktop/src-tauri, apps/desktop/package.json
Tauri가 Electron보다 가볍다는 말만 하고 권한 boundary를 빼먹으면 안 된다.
Rust 비동기 runtime이다.
Tokio lets the Rust backend handle multiple terminal streams and background tasks without blocking the UI.
process IO, timers, async commands, background tasks를 동시에 처리한다.
terminal output과 여러 pane/session을 막힘 없이 다루려면 async runtime이 필요하다.
async Rust는 복잡하고 blocking 작업을 잘못 섞으면 runtime이 막힌다.
표준 thread만 쓰면 단순하지만 확장성과 IO 관리가 떨어지고, async-std는 대안 runtime이다.
apps/desktop/src-tauri/Cargo.toml, src-tauri async commands
async를 쓰면 race condition이 사라진다고 생각하면 안 된다.
Rust와 JSON 사이 직렬화 도구다.
Serde is the bridge that turns Rust structs into JSON contracts for the renderer and local ledgers.
Tauri command payload, graph node, receipts, settings 같은 데이터를 구조화해서 주고받는다.
renderer와 Rust 사이 contract를 타입 있는 struct와 JSON으로 연결하기 좋다.
schema evolution을 신경 쓰지 않으면 오래된 JSONL이나 settings가 깨질 수 있다.
manual parsing은 제어가 강하지만 오류가 늘고, protobuf는 contract가 강하지만 tooling이 무겁다.
Cargo.toml, graph/memory/settings code
JSON이 flexible하다고 아무 모양이나 저장하면 안 된다.
React가 호출할 수 있는 Rust 함수와 통신 경계다.
Tauri commands are the explicit boundary where the UI asks Rust to perform local privileged work.
renderer가 invoke로 pty_spawn, graph_query, vault action 같은 backend 작업을 요청한다.
권한 있는 native 작업을 명시적 command surface로 제한할 수 있다.
command를 너무 많이/넓게 열면 공격면이 커진다. validation과 permission check가 필요하다.
HTTP localhost server 방식도 가능하지만 desktop IPC보다 인증/포트/보안 문제가 늘 수 있다.
apps/desktop/src-tauri/src/lib.rs, apps/desktop/src
IPC가 직접 함수 호출처럼 보여도 serialization, async, permission 경계가 있다.
Tauri 앱 안에서 React UI를 그리는 브라우저 엔진이다.
The WebView renders the React cockpit, while Rust handles capabilities the browser sandbox cannot access.
macOS/Windows/Linux의 WebView가 HTML/CSS/JS UI를 렌더링한다.
React 생산성을 유지하면서 native app처럼 배포할 수 있다.
OS별 WebView 차이가 생길 수 있고, Electron처럼 같은 Chromium을 모두 포함하지 않는다.
Electron은 runtime 일관성이 좋고, native UI는 OS fit이 좋다.
Tauri renderer, apps/desktop/src
WebView가 local file/process 권한을 직접 가진다고 생각하면 안 된다.
Rust에서 pseudo terminal을 만드는 라이브러리다.
portable-pty is the substrate that makes CLI agents behave like they are running in a real terminal.
Claude, Codex, shell, tmux 같은 interactive CLI를 진짜 terminal처럼 실행한다.
plain subprocess pipe로는 color, resize, interactive input이 깨질 수 있어서 PTY가 필요하다.
OS별 PTY 동작 차이와 EOF/resize/encoding edge case를 처리해야 한다.
Node pty, system terminal app automation, raw process pipe가 대안이다.
apps/desktop/src-tauri/Cargo.toml, pty.rs
xterm.js가 PTY를 만드는 게 아니라 Rust 쪽 PTY가 실제 process를 붙잡는다.
터미널 세션을 유지/분할하는 multiplexer다.
tmux helps decouple long-running terminal sessions from the UI view lifecycle.
앱 재시작이나 pane 전환 후에도 session을 붙잡거나 여러 agent session을 관리한다.
AI 작업이 오래 걸리므로 UI lifetime과 process lifetime을 분리하는 데 유용하다.
사용자 machine에 tmux가 없거나 PATH가 다르면 실패한다. 설치/진단 UX가 필요하다.
직접 session manager를 만들 수 있지만 복잡하고, OS terminal tabs에 맡기면 제품 통제가 약하다.
session backend docs, pty.rs, CLAUDE.md env hygiene
tmux를 쓰면 process recovery가 자동으로 완벽해진다고 말하지 말라.
Rust에서 쓰는 단순 HTTP client다.
ureq is a simple HTTP client for straightforward Rust-side service calls.
local backend가 외부 endpoint나 local service를 호출할 때 사용할 수 있다.
blocking/simple request에는 가볍고 이해하기 쉽다.
대량 async HTTP나 streaming에는 reqwest/async client가 더 맞을 수 있다.
reqwest는 기능이 풍부하고, hyper는 low-level 제어가 강하다.
apps/desktop/src-tauri/Cargo.toml
blocking client를 async path에서 아무 생각 없이 쓰면 안 된다.
desktop renderer와 web UI를 component로 만든다.
React is the cockpit layer: it renders panes, mission state, graph views, and user approvals.
workspace, panes, graph, mission board, forms, receipts 같은 화면을 상태 기반으로 그린다.
상호작용이 많은 조종석 UI라 component/state model이 잘 맞는다.
상태 ownership이 흐려지면 UI가 복잡해지고 성능 문제가 난다.
Vue/Svelte는 더 간결할 수 있고, native UI toolkit은 platform integration이 강하다.
apps/desktop/src, apps/web/src
React가 local process를 직접 spawn할 수 있다고 생각하면 안 된다.
desktop renderer 개발 서버와 빌드 도구다.
Vite is a good fit for a Tauri renderer because the desktop shell needs a fast SPA bundle, not a server-rendered web app.
React renderer를 빠르게 dev/build하고 Tauri shell 안에 넣을 frontend bundle을 만든다.
desktop SPA renderer에는 Next보다 단순하고 빠른 Vite가 맞다.
SSR/route conventions가 필요한 web app이면 Next가 더 적합할 수 있다.
Next.js는 full web framework이고, webpack은 성숙하지만 설정/속도 부담이 있다.
apps/desktop/package.json, vite config
Vite는 desktop backend가 아니라 frontend build tool이다.
브라우저/WebView 안에 terminal 화면을 그리는 라이브러리다.
xterm.js renders the terminal UI; the actual process is still owned by the Rust PTY layer.
PTY output bytes를 화면에 표시하고 사용자의 keystroke를 backend로 보낸다.
터미널 UX를 직접 구현하지 않고 검증된 renderer를 쓸 수 있다.
실제 shell 실행은 하지 않는다. rendering과 process layer를 혼동하면 안 된다.
Monaco terminal-like UI나 custom textarea는 interactive terminal fidelity가 약하다.
apps/desktop/package.json, TerminalPane.tsx
xterm이 명령을 실행한다고 말하면 레이어 설명이 틀린다.
여러 pane을 나누어 배치하는 UI 라이브러리다.
A pane layout is core to the product because the user supervises multiple sessions and evidence surfaces at once.
multi-agent terminal, logs, graph, mission board를 split pane으로 보여준다.
Dalkkak은 한 작업만 보는 앱이 아니라 여러 AI worker를 동시에 조종하는 cockpit이라 pane layout이 중요하다.
layout state와 resize/drag UX가 복잡해질 수 있다.
custom CSS grid는 단순하지만 drag split이 어렵고, IDE급 layout engine은 무겁다.
apps/desktop/package.json, workspace layout
pane UI가 있다고 병렬 작업 coordination이 자동으로 되는 건 아니다.
3D/시각화 UI를 위한 rendering stack이다.
Three.js is useful for immersive state visualization, but it should not replace clear operational UI.
mission/world/graph 같은 richer visualization surface를 만들 때 사용된다.
복잡한 작업 상태를 시각적으로 보여주는 제품 경험에 도움이 될 수 있다.
3D는 성능/접근성/유지보수 비용이 크고, 핵심 workflow를 가리면 해롭다.
2D graph, table, timeline은 더 명확하고 빠를 수 있다.
apps/desktop/package.json, 3D components
3D가 있으면 제품 가치가 자동으로 올라간다고 생각하면 안 된다.
텍스트로 diagram을 그리는 도구다.
Mermaid can turn structured explanations into readable architecture and workflow diagrams.
workflow, architecture, sequence diagram을 앱/문서에서 빠르게 보여줄 수 있다.
AI가 생성한 설계 설명을 사람이 볼 수 있는 diagram으로 바꾸기 쉽다.
복잡한 diagram은 layout이 깨질 수 있고, 보안상 user-provided diagram rendering을 조심해야 한다.
custom SVG/canvas, PlantUML, Excalidraw-style editor가 대안이다.
apps/desktop/package.json, docs screens
diagram이 예쁘다고 실제 시스템 검증이 된 것은 아니다.
가벼운 TypeScript HTTP framework다.
Hono is a lightweight TypeScript API layer for cloud-side endpoints around the workspace.
apps/server가 cloud API surface를 제공할 때 사용한다.
TS monorepo 안에서 작고 빠른 API를 만들기 좋다.
큰 enterprise backend에는 NestJS/Spring 같은 구조적 프레임워크가 더 나을 수 있다.
Express는 생태계가 크고, Fastify는 성능/스키마가 강하고, tRPC는 TS end-to-end contract가 강하다.
apps/server/src/app.ts
Hono가 desktop local runtime을 대신하는 것은 아니다.
이메일 읽기/파싱/발송 관련 Rust dependency다.
Mail dependencies point toward connector workflows, but real email automation needs approval, audit, and provider-specific handling.
connector 실험이나 inbox/action workflow에서 메일을 가져오고 파싱하고 보낼 수 있다.
업무 자동화 제품은 email 같은 실제 외부 시스템과 연결될 가능성이 크다.
이메일은 인증, rate limit, deliverability, privacy, provider policy가 복잡하다.
Gmail API/Graph API는 provider-native이지만 OAuth와 quota가 필요하고, generic IMAP은 범용이지만 기능 차이가 있다.
apps/desktop/src-tauri/Cargo.toml
메일 라이브러리가 있다고 실제 Gmail 제품 연동이 완성된 건 아니다.
작업 기억을 node/edge로 남기는 로컬 ledger다.
GraphStore turns scattered agent work into cited memory rather than disposable chat history.
work, issue, action, artifact, evidence, follow-up을 append-only JSONL graph로 저장한다.
AI가 한 일을 나중에 근거 있게 recall하려면 chat transcript보다 구조화된 기억이 필요하다.
JSONL ledger는 query/index가 약할 수 있어 derived index나 DB가 필요해질 수 있다.
SQLite는 query가 강하고, event store는 audit가 강하며, vector DB는 semantic retrieval에 강하다.
docs/CONNECTIVE_LAYER.md, capture.rs, memory.rs
검색 index를 source of truth로 착각하면 안 된다.
한 줄에 JSON 하나씩 저장하는 파일 형식이다.
JSONL is simple, inspectable, and append-friendly for local memory logs.
GraphStore node/edge/event를 append-only로 저장하기 쉽다.
local-first 제품에서 단순하고 diff/debug가 쉬운 저장 형태다.
복잡한 query, transaction, compaction은 직접 처리해야 한다.
SQLite는 query/transaction이 강하고, plain JSON file은 작은 설정에는 단순하지만 append log에는 약하다.
GraphStore JSONL docs/code
JSONL은 database가 아니라 파일 형식이다.
정보가 어디서 왔고 얼마나 믿을 수 있는지 표시하는 metadata다.
Provenance lets the system distinguish confirmed facts from AI guesses before feeding memory back to agents.
confirmed, inferred, hypothesis를 구분하고 evidence를 붙인다.
AI 제품에서 추론과 사실을 섞으면 신뢰가 무너지므로 provenance가 필수다.
사용자에게 너무 많은 badge를 보여주면 UX가 무거워질 수 있다.
단순 timestamp/source만 기록할 수도 있지만 신뢰 레벨 구분이 약하다.
GraphStore validator, memory bundle docs
provenance는 UI 장식이 아니라 신뢰 경계다.
충돌 시 마지막 변경을 이기는 단순 동기화 정책이다.
Last-write-wins is acceptable for simple state, but not for high-value collaborative edits.
단순 widget/state sync에서 복잡한 merge 없이 최신 timestamp를 채택한다.
초기 cloud sync에는 이해하기 쉽고 구현이 빠르다.
동시에 중요한 내용을 수정하면 데이터 손실이 생길 수 있다.
CRDT는 협업 merge에 강하고, explicit conflict UI는 안전하지만 UX가 복잡하다.
cloud sync docs/code
LWW를 모든 데이터에 쓰면 위험하다.
로컬 embedding 생성을 위한 Rust dependency다.
fastembed supports local semantic retrieval without sending every memory item to a cloud embedding API.
텍스트를 vector로 바꿔 비슷한 memory/ticket/case를 찾는 기반이 된다.
local-first memory search에서 cloud embedding API 없이 semantic retrieval을 할 수 있다.
모델 크기, CPU cost, index freshness, 품질 tuning 문제가 있다.
OpenAI embeddings는 품질/운영이 쉽지만 데이터가 외부로 나가고 비용이 든다.
apps/desktop/src-tauri/Cargo.toml, vector index docs
embedding이 있으면 답이 정확해진다고 말하면 안 된다.
AI에게 관련 기억을 찾아 context로 넣는 방식이다.
RAG in Dalkkak should mean grounded memory bundles with citations, not dumping random notes into the prompt.
GraphStore에서 근거 있는 node/evidence를 찾아 Claude/Codex prompt에 전달한다.
긴 chat history 대신 필요한 context만 넣어 AI 작업 품질과 일관성을 높인다.
검색이 틀리면 오히려 잘못된 context를 넣을 수 있다. citation과 provenance가 필요하다.
fine-tuning은 모델 자체를 바꾸고, long context stuffing은 단순하지만 비용/노이즈가 크다.
local MCP handlers, memory bundle docs
RAG라는 말만 붙이면 memory 문제가 해결된다고 생각하면 안 된다.
Claude/Codex 같은 AI client에 Dalkkak 도구를 노출하는 표준 gateway다.
MCP is the tool gateway between BYO agents and Dalkkak's grounded local memory.
graph search, WorkItem recall, workflow prepare 같은 local memory tool을 제공한다.
BYO AI가 제품 기억을 사용할 수 있게 하되, 처음에는 읽기 중심으로 안전하게 여는 게 맞다.
mutation tool을 열면 권한, approval, audit, idempotency 문제가 급격히 커진다.
custom CLI protocol은 단순하지만 표준 client 호환성이 떨어진다.
apps/local-mcp-server/src
MCP가 곧 안전한 자동 실행 권한이라는 뜻은 아니다.
action/connector/runner/receipt 계약을 정의하는 패키지다.
The Action SDK defines the contract for safe, auditable actions before connecting real external services.
위험도, permission, approval, dry-run, result envelope를 표준화한다.
AI가 외부 일을 할수록 버튼 하나가 아니라 검증 가능한 action contract가 필요하다.
SDK가 있어도 실제 connector 구현과 runtime enforcement가 없으면 껍데기다.
화면별 ad-hoc handler는 빠르지만 audit/permission consistency가 약하다.
packages/action-sdk, screen actions
SDK 타입만 있다고 실제 외부 mutation이 안전한 건 아니다.
외부 변경 없이 결과를 미리 보여주는 안전 모드다.
Dry-run makes it explicit when an action produced a preview rather than changing the outside world.
mock connector나 approval pending 상태에서 이메일/결제/삭제가 실제로 일어나지 않았음을 명시한다.
사용자가 AI 제안을 검토할 수 있게 하고 거짓 완료 claim을 줄인다.
dry-run 결과를 실제 완료로 착각하면 product trust가 깨진다.
sandbox account, staging connector, approval-gated real run이 다음 단계다.
Action SDK tests, screenSpec
차단 상태를 실패로만 보면 안 된다. 안전한 정상 상태일 수 있다.
cloud workspace의 Postgres/Auth/Realtime backend platform이다.
Supabase supports the cloud-augmented layer while the core desktop runtime stays local-first.
web workspace, tickets, presence, sync state, RLS policy를 제공한다.
로컬 앱만으로 부족한 team/cloud view를 빠르게 붙일 수 있다.
vendor dependency와 RLS 설계 책임이 있다. local core와 cloud augmentation 경계를 지켜야 한다.
Firebase는 realtime이 강하고, self-hosted Postgres는 통제가 강하지만 auth/realtime을 직접 붙여야 한다.
apps/web/supabase/schema.sql, apps/web
Supabase를 쓰면 multi-tenant 보안이 자동 완성된다고 말하면 안 된다.
cloud workspace에서 누가 접속했는지와 상태 변화를 보여주는 기능이다.
Realtime presence helps the cloud layer show live workspace activity, but it must respect tenant boundaries.
team view, active members, ticket/widget sync 같은 실시간 UI를 보조한다.
팀 협업 제품으로 확장할 때 현재 상태를 공유하는 UX가 필요하다.
privacy와 channel 권한을 잘못 잡으면 workspace 정보가 샐 수 있다.
WebSocket 직접 구현은 통제가 강하고, Pusher/Ably는 managed realtime에 강하다.
apps/web, usePresence.ts, Supabase schema
presence는 보기 좋은 기능이지만 권한이 없으면 정보 노출이다.
DB row별 접근권한을 Postgres가 강제하는 기능이다.
RLS makes the database enforce tenant boundaries instead of relying only on frontend filters.
tenant/user/service가 자기 row만 보게 policy를 DB에 둔다.
multi-tenant cloud에서 앱 코드 필터보다 강한 보안 경계다.
policy를 잘못 쓰면 접근이 막히거나 새는 문제가 생긴다. 테스트가 필요하다.
API server에서만 authorization을 강제할 수도 있지만 DB direct client가 있으면 약하다.
apps/web/supabase/schema.sql
RLS가 켜져 있다는 사실과 policy가 정확하다는 사실은 다르다.
OS 보안 저장소에 secret을 넣는 Rust crate다.
The keyring crate stores secrets in the operating system's credential store rather than plain app files.
API key, token 같은 민감값을 plain file 대신 macOS Keychain/Windows Credential Manager 등에 저장한다.
desktop app은 사용자의 local secret을 다루므로 OS-level secure storage가 필요하다.
OS별 동작과 권한 prompt, migration, backup behavior를 테스트해야 한다.
암호화된 local file은 통제가 쉽지만 key 관리가 문제이고, cloud vault는 동기화는 좋지만 외부 의존이 생긴다.
apps/desktop/src-tauri/Cargo.toml, vault.rs
keyring을 쓰면 log/prompt 유출 위험까지 사라지는 건 아니다.
secret을 handle로 다루고 노출을 줄이는 계층이다.
The vault should let agents reference secrets without seeing raw secret values.
AI에게 실제 API key 값 대신 name/handle만 주고, 실행 경계에서만 접근하게 한다.
connector와 MCP가 늘어날수록 secret minimization이 제품 신뢰의 핵심이다.
vault UI가 있어도 logs, crash reports, prompts, receipts에서 새면 의미가 없다.
환경변수는 단순하지만 desktop multi-project secret 관리에는 약하고, external vault는 강하지만 설정이 무겁다.
vault.rs, secret_guard.rs, redaction tests
secret을 저장했다는 것과 secret flow가 안전하다는 것은 다르다.
같은 action을 여러 번 실행해도 결과가 한 번과 같게 만드는 성질이다.
Idempotency is essential because agents and retries can repeat the same operation.
retry/replay에서 duplicate receipt, duplicate email, duplicate graph node를 막는다.
AI/action 제품은 같은 지시를 반복하거나 재시도할 일이 많아서 생존 조건이다.
외부 API가 idempotency key를 지원하지 않으면 구현이 어려워진다.
dedupe table, deterministic id, provider idempotency key, manual reconciliation이 보완책이다.
GraphStore deterministic ids, Action SDK design
읽기 idempotency와 외부 mutation idempotency는 난이도가 다르다.
위험한 AI 행동을 막거나 사람 승인 뒤 실행하게 하는 규칙이다.
Guardrails and approvals are how the product turns AI autonomy into controlled execution.
send/delete/spend/deploy 같은 action을 approval 없이 실행하지 못하게 한다.
AI가 똑똑해질수록 deterministic safety boundary가 더 중요하다.
너무 빡빡하면 UX가 느려지고, 너무 느슨하면 신뢰가 깨진다.
policy engine, permission scopes, sandbox accounts, audit review가 보완책이다.
Action SDK, safety docs, approval UI
LLM judge만으로 guardrail을 대체하면 안 된다.
TS/JS formatter와 linter다.
Biome keeps formatting and basic lint rules fast and consistent across the TypeScript workspace.
monorepo의 코드 스타일과 기본 오류를 빠르게 검사한다.
여러 패키지가 있는 repo에서 format/lint 기준을 통일한다.
타입체크나 테스트를 대체하지 않으므로 동작 검증은 별도로 필요하다.
ESLint+Prettier는 생태계가 크고 설정이 세밀하지만 toolchain이 둘로 나뉜다.
ddalkkak/package.json
lint 통과는 제품 동작 보장이 아니다.
TypeScript/React 단위 테스트 도구다.
Vitest is useful for fast TypeScript-level feedback, especially around contracts and UI logic.
Action SDK, renderer logic, package helper, component behavior를 빠르게 테스트한다.
Vite ecosystem과 잘 맞고 dev 속도가 빠르다.
desktop native/Rust/PTY integration은 Vitest만으로 검증하기 어렵다.
Jest는 널리 쓰이고, Playwright는 브라우저/e2e, cargo test는 Rust logic에 맞다.
apps/desktop/package.json, packages tests
Vitest만으로 Tauri/Rust/OS behavior까지 검증됐다고 말하면 안 된다.
Rust crate 빌드와 테스트 도구다.
Cargo is the build and verification entry point for the native Rust side of the desktop app.
src-tauri backend의 compile, unit test, dependency resolution을 관리한다.
PTY/session/vault 같은 native backend는 Rust toolchain에서 검증해야 한다.
OS integration은 unit test만으로 부족해서 manual/e2e smoke가 필요하다.
Tauri driver/e2e, shell smoke scripts, snapshot logs가 보완책이다.
apps/desktop/src-tauri/Cargo.toml
Rust가 컴파일되면 UX가 맞다는 뜻은 아니다.
Rust backend 로그와 span을 남기는 도구다.
Tracing gives the local backend a way to explain what happened when a pane, command, or memory write fails.
PTY spawn, command execution, graph writes, mission scans 같은 runtime events를 추적한다.
로컬 desktop 장애는 서버 로그가 없으므로 structured local diagnostics가 중요하다.
민감한 path/secret/output을 과하게 남기면 privacy risk가 생긴다.
log crate는 단순하고, OpenTelemetry는 distributed tracing에 강하다.
apps/desktop/src-tauri/Cargo.toml, logging code
로그가 많으면 디버깅이 쉬운 게 아니라 중요한 필드가 있어야 쉽다.
desktop 앱을 안전하게 업데이트하는 배포 계층이다.
A desktop product needs signed updates because users do not automatically get a new build like a web app.
signed bundle과 update metadata로 사용자 앱이 새 버전을 받게 한다.
desktop 제품은 웹처럼 새로고침만으로 배포되지 않아서 updater가 필수다.
인증서, notarization, platform별 packaging, rollback을 관리해야 한다.
수동 다운로드는 단순하지만 retention이 약하고, app store 배포는 신뢰는 좋지만 심사/제약이 있다.
tauri.conf, updater.ts, release scripts
빌드 성공과 사용자에게 안전하게 배포되는 것은 다른 문제다.
배포 전 위험 항목을 확인하는 script/process다.
The release gate is a lightweight way to stop shipping without evidence.
빌드, 테스트, readiness checklist를 묶어 release 전 확인한다.
AI/desktop 제품은 기능이 많아질수록 릴리즈 전 검문소가 필요하다.
체크리스트가 실제 fail condition과 연결되지 않으면 형식이 된다.
CI pipeline, GitHub Actions required checks, manual QA checklist가 보완책이다.
scripts/release-readiness-gate.mjs, package.json
gate script가 있다고 품질 문화가 자동으로 생기지는 않는다.
한 repo의 여러 branch를 여러 폴더에서 동시에 checkout하는 Git 기능이다.
Git worktrees make parallel agent work safer by giving each worker an isolated checkout and branch.
parallel agents가 각자 독립 작업 디렉터리에서 파일을 바꾸게 한다.
AI worker들이 같은 파일을 동시에 덮어쓰는 위험을 줄이고 merge queue를 만들 수 있다.
disk 사용량과 branch cleanup, dependency install 관리가 필요하다.
branch만 바꾸며 작업하는 방식은 단순하지만 병렬성이 약하고, repo clone 복사는 느리고 무겁다.
parallel mission docs, git workflow
worktree가 있으면 merge conflict가 사라지는 건 아니다.
이 순서대로 가면 terminal 바닥에서 AI completion control까지 한 줄로 이어진다.
terminal, shell, process, event를 먼저 잡는다.
Dalkkak의 가장 밑에는 화면이 아니라 로컬 process가 있다. 화면은 그 process와 대화하는 UI다.
At the bottom, Dalkkak runs local processes. The UI is just the control surface around them.
Code focus: spawn a process, stream output, show close/error state
browser sandbox와 native desktop의 차이를 이해한다.
브라우저는 내 로컬 Claude/Codex process를 직접 띄울 수 없다. 그래서 Tauri와 Rust backend가 필요하다.
A browser-only app cannot safely spawn local Claude or Codex processes, so Dalkkak needs a native shell.
Code focus: React invoke -> Rust command -> OS process
renderer, command, PTY, event stream, xterm을 연결한다.
UI가 Rust에게 PTY를 만들라고 요청하고, Rust는 child process 출력을 event로 보내고, xterm이 그린다.
The renderer asks Rust to spawn a PTY, Rust streams bytes back, and xterm renders the terminal.
Code focus: invoke('pty_spawn'), listen('pty-output'), term.write(data)
PATH, shell, GUI app env, Homebrew path를 이해한다.
iTerm에서는 되는 명령도 Tauri 앱에서 PATH가 다르면 command not found가 난다.
A GUI app may have a different PATH than iTerm, so spawned CLIs need explicit environment hygiene.
Code focus: construct child env, prepend Homebrew paths, print visible failure
BYO AI와 control plane의 차이를 말한다.
Dalkkak은 모델이 아니라 작업공간과 통제층이다. 사용자의 Claude/Codex가 worker다.
Dalkkak is not the model. It is the operating layer around the user's own AI workers.
Code focus: spawn claude/codex as a local CLI process, observe transcript
WorkItem, receipt, evidence, follow-up을 잡는다.
AI가 한 일은 WorkItem timeline, receipt, artifact, follow-up으로 남아야 다시 볼 수 있다.
Work must become durable records: WorkItems, receipts, artifacts, and follow-ups.
Code focus: WorkItem -> action -> artifact -> receipt -> follow-up
GraphStore, JSONL, append-only, node/edge/provenance를 이해한다.
Dalkkak의 기억은 그냥 요약 문서가 아니라 검증된 노드와 엣지가 쌓이는 append-only ledger다.
Dalkkak memory is an append-only graph ledger with provenance, not just chat history.
Code focus: validate node, append JSON line, query by startup/type
RAG, memory bundle, MCP를 연결한다.
AI가 기억하는 게 아니라, Dalkkak이 관련 기억을 찾아 context로 넣어줘야 한다.
The model does not magically remember; Dalkkak retrieves relevant memory and passes it as context.
Code focus: MCP handler -> graph query -> cited context bundle
dry-run, approval, guardrail, external mutation boundary를 이해한다.
이메일/환불/삭제 같은 외부 부작용은 dry-run, approval, receipt 없이 실행하면 안 된다.
External mutations must go through dry-run, approval, receipts, and deterministic guardrails.
Code focus: if approval pending, return blocked receipt instead of mutating
ParallelRun, AgentTask, worktree, file ownership, merge queue를 이해한다.
병렬 AI 작업은 터미널 여러 개가 아니라 소유권, 증거, 검증, merge 순서가 있는 운영 시스템이다.
Parallel AI work needs ownership, evidence, verification, and a merge queue.
Code focus: task packet with allowed files, branch, tests, result artifact
intent, acceptance, verification, final gate를 이해한다.
worker는 done candidate를 만들 뿐이고, 완료는 증거와 gate가 판단한다.
The worker can propose done, but the system decides completion through evidence and gates.
Code focus: done_candidate -> verification -> review -> human acceptance
eval, injection, reliability, observability, release trust를 냉정히 구분한다.
Dalkkak은 substrate가 강하지만 trust/safety는 아직 더 만들어야 한다. 이걸 알아야 제대로 방향을 잡는다.
The substrate is real, but the trust layer still needs evals, injection defense, reliability, and stronger gates.
Code focus: fixture tests, bounded retries, trace IDs, release evidence
아래 10개 층을 말할 수 있으면 제품 구조의 뼈대는 잡힌다.
The human sees startups, zones, panes, WorkItems, approvals, and receipts.
사용자가 실제로 보는 조종석이다. 여러 사업과 작업을 한 앱에서 보고, AI 세션을 지휘하고, 결과 증거를 확인한다.
The UI layer running inside the Tauri WebView.
브라우저처럼 생긴 화면 레이어다. 버튼, 카드, 터미널 화면, 그래프 화면을 그린다.
The native desktop wrapper connecting UI to local OS capabilities.
웹 UI가 macOS의 파일, 프로세스, 알림, 업데이트 같은 기능을 안전하게 쓰게 해주는 껍데기다.
Owns PTY, tmux, graph capture, memory, vault, mission scanning, and local commands.
무거운 로컬 일을 하는 엔진이다. 터미널을 띄우고, 로그를 모으고, 기억을 저장하고, 위험한 경계를 지킨다.
The pane/process layer where Claude Code, Codex, shells, and commands actually run.
AI가 실제 명령을 치고 파일을 바꾸는 작업장이다. Dalkkak은 이 작업장을 한 화면에 여러 개 만든다.
Turns scattered work into a durable graph of facts, actions, evidence, and edges.
일이 끝나고 사라지지 않게 만드는 기억층이다. 커밋, 에이전트 요약, 액션 결과를 노드와 엣지로 남긴다.
Represents work as WorkItem -> action -> artifact -> edge -> receipt -> follow-up.
버튼을 눌렀을 때 무엇을 했고, 어떤 산출물이 생겼고, 다음 일이 무엇인지 남기는 업무 척추다.
Exposes Dalkkak memory/workflow tools to BYO AI clients without giving broad mutation power.
Claude/Codex가 Dalkkak의 기억을 조회할 수 있게 하는 표준 도구 서버다. 우선 읽기 중심이어야 안전하다.
Handles workspace sync, RBAC, web views, tickets, presence, and team-facing surfaces.
로컬 앱만으로 안 되는 동기화와 팀/웹 기능을 맡는다. Supabase RLS가 접근권한의 핵심이다.
Prevents AI from silently overclaiming, leaking secrets, or performing risky actions.
AI를 믿는 게 아니라 증거, 승인, 검증, 방어 규칙으로 통제하는 층이다. 제품의 신뢰 핵심이다.
제품을 이해하려면 static 구조보다 request/data flow를 먼저 봐야 한다.
사용자가 새 터미널을 열면 UI는 Rust에게 PTY 생성을 요청하고, Rust는 shell/tmux/Claude/Codex 프로세스를 띄운 뒤 출력 이벤트를 UI로 흘려보낸다.
A terminal pane is a local process wrapped by a PTY. The renderer asks Rust to spawn it, and Rust streams output back as events.
built / partial / missing을 구분해야 제품을 제대로 이해한다.
Tauri desktop, React renderer, Rust PTY/session pieces, panes, zones, and many UI surfaces exist.
The UI is broad and technical; product coherence depends on WorkItem/memory/mission surfaces becoming simpler.
Next: Explain every visible surface through one model: workspace -> WorkItem -> action -> receipt -> memory.
The product does not primarily call AI itself; it wraps and augments user-owned AI sessions.
People may mistake it for a managed chatbot/codegen product.
Next: Keep saying: Dalkkak is the control plane, not the model.
GraphStore/JSONL, WorkItem memory spine, graph nodes/edges, and local MCP read surfaces exist.
Semantic retrieval, embeddings, deletion/governance, and full citation discipline are incomplete.
Next: Harden retrieval, citation, provenance UI, and memory lifecycle.
Action contracts, receipts, approval metadata, and mock/dry-run boundaries exist.
Real Gmail/Stripe/Instagram style mutation connectors are not fully wired.
Next: Ship one real connector vertical with injection defense, approval, receipt, retry, and rollback.
Docs, scanner/model/UI sections, merge queue, verification evidence, and many tests exist.
Full dispatch/monitor/reissue/integration workflow is not fully productized.
Next: Turn manual parallel-agent chaos into a guided run from split planner to final gate.
Supabase schema, forced RLS, web workspace, tickets, widget sync, and presence pieces exist.
Desktop/cloud/web product boundaries and API contracts are still evolving.
Next: Clarify what lives local, what syncs, and what web can safely do.
Traditional tests exist, but fixed AI quality evals are not yet strong.
You cannot know whether AI-generated drafts/actions are good at scale.
Next: Build eval fixtures for support, billing, release, and coding assistant outputs.
The docs identify it as critical, but full defense is not built.
Untrusted email/web/customer text can hijack agent behavior.
Next: Add untrusted-content boundaries, policy checks, and adversarial fixtures before mutation connectors.
Some idempotent memory design exists, but action retry/timeout/fallback/replay is not complete.
Real external actions could double-run, hang, or fail invisibly.
Next: Define action state machine with timeout, retry cap, idempotency key, and recovery receipt.
Release docs, gates, signing/updater concepts, and claim cleanup are present.
Release claims can drift from actual verified behavior.
Next: Keep release readiness gate tied to command evidence and smoke checks.
모르는 단어를 누르면 뜻, Dalkkak 위치, 말하는 문장, 함정까지 열린다.
이 페이지가 어떤 Dalkkak 문서/코드에서 왔는지 기억해라.
Mission, layers, reality checkpoint, product boundaries
AI concepts, current status, trust gaps
GraphStore, provenance, JSONL, agent push
WorkItem -> action -> artifact -> receipt -> follow-up
ParallelRun, AgentTask, result inbox, merge queue
No fake done, evidence-first parallel-agent protocol
React UI, panes, zones, WorkItem, Mission Control
PTY, graph capture, memory, vault, mission scanner
Tool gateway for BYO AI memory access
Supabase workspace, tickets, sync, Hono API