바이브코더(코드를 직접 읽지 않고 AI 에이전트에게 일을 시키는 사람)를 위한 도슨트(작품을 만지지 않고 설명하는 안내자). 작업 기록을 읽고 AI의 질문, 결과, 계획을 쉬운 한국어로 풀어 준다. 웹앱, 모바일 PWA, 터미널, macOS 앱이 같은 로컬 설명 서버를 사용한다. 제품 도슨트는 코드를 수정하거나 실행하지 않는다.
Vibecoder Docent explains coding-agent sessions in plain Korean without changing code. It shows important questions, results, and plans, then lets you ask about each item. Your session files stay on your computers; the app runs locally and uses your installed omp to answer.
화면 안내 · 설치 · 다른 컴퓨터 · 데이터와 개인정보 · 개발
세션에서 AI의 질문·작업 결과·계획만 골라 보여 준다. 궁금한 카드를 누르면 그 내용에 관한 대화가 열리고, “왜 이렇게 했어?”, “이 선택지는 뭐야?”처럼 이어 물을 수 있다. 확인된 원문은 별도로 열어 볼 수 있다. 화면 예시는 가짜 작업 기록으로 만들었으며 실제 사용자 세션을 담지 않는다.
- Node.js 22.19 이상
- omp 설치 및 로그인. 도슨트가 로컬 omp를 호출해 학습 맥락을 분류하고 설명을 만든다.
- Claude Code·Codex CLI·Gemini CLI·pi 세션은 선택 사항이다. 읽을 수 있는 세션이 있으면 omp 세션과 함께 목록에 나온다. 설명하는 모델은 omp에 로그인한 공급자(Anthropic, OpenAI Codex, GLM(zai) 등) 중에서 설정에서 고른다.
- 새 질문·결과·계획의 자동 선별은 선택 사항인
TYPESAFE_API_KEY가 있을 때 Jev를 사용한다. 키가 없으면 구조화된 질문만 라이브 카드로 보여 주며, 수동 질문은 계속 사용할 수 있다.
쓰고 있는 코딩 에이전트(Claude Code 터미널이나 Claude 앱, Codex CLI나 Codex 앱, omp 등)에게 아래 한 줄만 보내면 에이전트가 확인과 설치를 하면서 필요한 것만 선택지로 묻는다. 질문은 각 에이전트에 내장된 질문 기능(Claude Code의 선택 화면, Codex의 질문 등)으로 나온다. 사용자는 고르기만 하고, 직접 할 일은 omp 로그인뿐이다 (ADR 0041·0042).
https://github.com/singandmong/vibecoder-docent/blob/main/INSTALL-AGENT.md 를 읽고 바이브코더 도슨트를 설치해줘
Codex CLI는 기본 설정에서 질문을 글로 보여 주므로 번호나 이름으로 답한다. 선택 화면으로 고르려면 codex --enable default_mode_request_user_input으로 실행한다(Codex의 개발 중 기능).
설치 상태는 언제든 docent doctor로 점검한다. --probe를 붙이면 모델을 한 번 불러 omp 로그인까지 확인하고, --json은 기계가 읽는 형식이다 (ADR 0041).
Node.js 22.19 이상이 필요하다. macOS·Linux·Windows 모두 같은 명령으로 설치한다.
# 공개 GitHub Release 패키지
npm install -g https://github.com/singandmong/vibecoder-docent/releases/latest/download/vibecoder-docent.tgz
# 저장소에서 바로 설치해도 같다
npm install -g github:singandmong/vibecoder-docent설치 없이 바로 실행할 수도 있다.
npx github:singandmong/vibecoder-docent # npm
bunx github:singandmong/vibecoder-docent # bunWindows에서는 PowerShell이나 명령 프롬프트에서 docent를 실행하면 기본 브라우저로 열린다. PowerShell의 스크립트 실행이 막혀 있으면(UnauthorizedAccess) docent.cmd, docent-tui.cmd처럼 .cmd를 붙여 실행한다.
새 버전은 GitHub 릴리스에서 받는다. 어느 화면에서 해도 서버가 파일을 내려받아 sha256을 확인하고, 지금 설치된 위치에 설치한 뒤 새 파일로 다시 켜진다 (ADR 0072).
- 웹·PWA: 설정 > 연결 > 업데이트에서 "새 버전 확인", "설치하고 다시 시작". 서버가 화면보다 새 버전이 되면 왼쪽 아래에 "새 버전 적용" 버튼이 생긴다(누르면 새로고침).
- 터미널:
/업데이트(/update)는 설치 뒤 이 터미널도 같은 세션으로 새 버전을 다시 연다. 서버가 먼저 바뀌었으면/재시작(/restart). - CLI:
docent update(확인만은docent update --check).
설치는 서버를 켠 컴퓨터에서 127.0.0.1로 연 화면이나 명령에서만 된다. 다른 기기(테일스케일로 연 휴대폰 등)는 새 버전 알림만 보인다. npm install -g로 설치한 도슨트만 이렇게 올릴 수 있고, 저장소 실행은 git pull, macOS 앱은 앱을 다시 설치한다. omp 확장이 바뀐 릴리스는 CHANGELOG에 적힌 대로 docent install-omp를 다시 실행한다.
docent기본 주소는 http://127.0.0.1:4747이다. 이미 켜져 있으면 새 서버를 띄우지 않고 브라우저만 연다. 종료하려면 실행한 터미널에서 중단한다.
터미널을 붙잡아 두지 않으려면 백그라운드로 켠다. 터미널을 닫거나 에이전트의 명령 실행이 끝나도 서버가 남는다. 출력은 ~/.docent/server.log에 쌓인다.
docent start # 백그라운드로 켜고 응답할 때까지 기다림. 이미 켜져 있으면 그대로 둠
docent stop # 백그라운드로 켠 서버를 끔docent start도 아래 옵션(--port, --host, --peer)을 받는다. Windows에 SSH로 접속해 docent start를 실행해도 SSH 연결을 끊은 뒤 서버가 남는다. Windows에서는 서버를 WMI로 만들어 SSH 세션이 끝날 때 함께 정리되지 않게 한다. 끌 때는 docent stop (ADR 0058).
| 옵션 | 용도 |
|---|---|
--no-open |
브라우저를 자동으로 열지 않는다. |
--port N |
웹앱의 포트를 지정한다. |
--host tailscale |
로컬 주소에 더해 이 컴퓨터의 Tailscale 주소에도 연다. |
--peer 이름=URL |
다른 컴퓨터의 도슨트 세션을 목록에 추가한다. 반복 지정 가능하다. |
--version, --help |
버전 또는 사용법을 표시한다. |
휴대폰에서는 컴퓨터의 도슨트에 연결한다. 휴대폰 자체에서 omp를 실행하지 않으므로 컴퓨터가 켜져 있어야 한다. 같은 서버 주소와 프로필을 사용하면 웹앱의 문답을 그대로 이어 본다.
# 컴퓨터: 먼저 도슨트를 켠다
docent --no-open
# 다른 터미널: 사설 HTTPS 연결 상태 확인
docent-mobile
# 공유를 켜기로 했을 때만 실행
docent-mobile --enable컴퓨터와 휴대폰에 Tailscale을 설치하고 같은 신뢰된 사설망에 연결한다. 명령이 안내하는 HTTPS 주소를 iPhone Safari나 Android Chrome에서 연 뒤, 공유 메뉴의 홈 화면에 추가 또는 브라우저의 앱 설치를 선택한다. Tailscale의 HTTPS 인증서 사용 승인이 처음에 필요할 수 있다. CLI 위치가 기본 PATH에 없으면 TAILSCALE_BIN에 실행 파일 경로를 지정한다. 다른 포트는 --port N을 사용한다.
docent-mobile은 기본적으로 상태만 읽는다.--enable에서만 Tailscale Serve를 설정한다. 다른 서비스가 쓰는 HTTPS 443 설정은 덮어쓰지 않으며 공개 Funnel이 켜져 있으면 거부한다.- 공유 해제는
tailscale serve --https=443 off다. 기존 웹앱의 Tailscale 주소에도 열기 스위치는 HTTP IPv4 대기 설정이며, Serve의 HTTPS 공유를 켜거나 끄지 않는다. - 600px 이하에서는 세션 / 작업 내용 / 대화 / 설정으로 이동한다. 모바일 입력창의 Enter는 줄바꿈이고, 보내기 버튼으로 질문한다.
- 연결이 끊기면 안내 화면을 표시한다. 서비스 워커는 오프라인 안내만 저장하며 전사와 문답은 캐시하지 않는다. 입력 중인 초안은 기존 웹앱처럼 기기의 localStorage에 남는다.
- 모바일 설치는 HTTPS가 필요하다. 공개 인터넷에 노출하지 않는다. 프로필은 로그인이 아니며 사설망의 접근 권한도 신뢰하는 기기로 제한해야 한다.
# 서버가 없다면 별도 터미널에서
docent --no-open
# Herdr 분할 창, Ghostty 또는 Kaku에서 같은 클라이언트를 실행
docent-tui
# 다른 도슨트 서버에 연결
docent-tui --url https://내-컴퓨터.내-사설망.ts.net저장소에서는 npm run terminal -- --url http://127.0.0.1:4747로 실행한다. Markdown 표시는 Pi 터미널 라이브러리(@earendil-works/pi-tui)의 렌더러를 사용하므로 Node 22.19 이상이 필요하다. 클라이언트를 종료해도 서버는 계속 실행된다. 원문의 제어 문자는 렌더링 전에 제거하고, 링크는 터미널 하이퍼링크가 아닌 일반 글자로 표시한다.
Bun에서도 실행된다(Bun 1.4 기준, bun bin/docent-tui.mjs). 기본과 지원 기준은 Node이고, CI가 Bun에서 테스트를 파일별로 돌려 호환을 확인한다. 시작이 Node보다 약 45ms 빠른 정도라 체감은 거의 없다. 서버는 Node로 실행해도 클라이언트만 Bun으로 쓸 수 있다.
화면은 Pi와 같은 구조다. 맨 위는 바이브코더 도슨트와 단축키, 가운데는 대화, 아래는 전체 너비 가로선 사이의 입력창, 맨 아래는 두 줄의 상태줄이다. 설명이 진행 중이면 입력창 바로 위에 회전 표시와 단계가 나온다. 질문은 파란 배경 메시지, 도슨트 설명은 터미널 기본 배경의 Markdown, AI 원문은 회색 배경 블록으로 구분한다. 색은 OMP titanium-prompt-focus 테마의 역할별 값(강조 #00b4ff, 질문 #243B53, 인라인 코드 #00ff88, 원문 블록 #2a3038)을 따른다. 지원 터미널에서는 RGB 색을 쓰며, 256색과 기본 ANSI 색도 지원한다. NO_COLOR=1 docent-tui는 색 없이 표시한다. 글자 q, i, !는 명령이 아니라 질문에 그대로 입력된다 (ADR 0038).
상태줄은 OMP처럼 항목마다 아이콘과 색이 다르다. 첫 줄은 진행 상태(설명 중일 때), 📁 작업 폴더, 🆔 세션, 📄 현재 대화, 스크롤 위치다. 둘째 줄은 ⬢ 모델과 추론 수준(◔ low, ◑ med), 🎯 설명 깊이, 💬 문답 수(현재 대화/세션 전체), ⏱ 학습 시간, 💾 저장된 대화 수, 📌 즐겨찾기 수, 👤 프로필이다. 학습 시간은 이 세션에서 직접 물어본 문답의 설명 시간 합계이며 미리 설명은 빠진다. 화면이 좁으면 덜 중요한 항목부터 빠진다. 항목, 아이콘, 색, 순서의 규칙은 docs/terminal-status-line.md에 있다. 아이콘이 깨지는 터미널에서는 DOCENT_SYMBOLS=ascii docent-tui로 ASCII 아이콘을 쓴다 (ADR 0040).
세션을 고르면 이어서 그 세션의 대화 선택창이 열린다. 목록은 웹의 작업 내용 카드와 같은 순서(세션 전체 대화, 새 카드가 위, 카드에 없는 저장 대화)이고, 카드마다 [질문], [작업 결과], [계획] 분류, 제목, 요약(답이 있으면 웹처럼 답에서, 없으면 AI가 한 말의 앞부분이나 선택지), NEW, 설명 중이나 미리 설명 중 표시, 문답 수, 즐겨찾기 ★, 시각이 붙는다. 처음에는 설명 중인 대화나 가장 새 카드가 골라져 있고, 고른 항목의 내용(카드의 AI 출력, 최근 문답)이 목록 아래에 미리 보인다. Enter로 열면 그 카드의 AI 출력과 문답이 웹처럼 보이고, Esc를 누르면 대화 선택창으로 돌아간다. 입력창에 기호를 쓰면 /는 바로 아래에 명령 목록이, @, #, $는 OMP 선택창처럼 맨 위에 검색창이 있는 선택창이 열린다 (ADR 0039, 0068).
세션 목록은 세션마다 세 줄 카드다. 첫 줄은 📦 저장소, 🔖 Herdr 작업 공간 이름(Herdr에 열린 세션일 때), 🌿 브랜치, 🌳 워크트리(연결된 워크트리일 때), 지금 세션 ✓, 흐린 글자로 제공자와 상대 시각. 둘째 줄은 세션 제목, 셋째 줄은 🕘 최근 작업 한 줄(에이전트 마지막 답의 첫 문장, 없으면 마지막 요청)이다. 브랜치는 세션 당시가 아니라 지금 그 폴더의 브랜치다 (ADR 0045).
Herdr에 열려 있는 세션은 목록 맨 위에 Herdr 사이드바의 작업 공간 순서대로, 같은 작업 공간에서는 창 번호 순으로 모이고, 나머지는 최근 활동 순이다. 웹과 터미널 카드에 Herdr에서 붙인 작업 공간 이름이 보이고, Herdr에서 이름을 바꾸면 다음 목록 새로고침에 바뀐다. 검색과 @ 목록에서 그 이름으로도 찾는다. Herdr가 없거나 응답하지 않으면 최근 활동 순 그대로다 (ADR 0060). Codex 창은 첫 질문을 보낸 뒤에 잡힌다. Codex 설정에 shell_environment_policy.inherit = "core"가 있으면 Herdr 연동 훅이 HERDR_* 변수를 받지 못해 잡히지 않으니, inherit = "all"과 include_only(core 변수, "HERDR_*", set에 둔 변수 이름)를 쓰고 Codex를 다시 시작한다 (ADR 0064).
| 입력 | 열리는 것 |
|---|---|
/ |
명령 목록(입력창 아래): 세션(session), 대화(thread), 저장 답변(answers), 자세히(details), 근거(evidence), 복습(review), 즐겨찾기(favorite), 설정(settings), 새로고침(refresh), 마우스(mouse), 종료(exit). 설명 중에는 바로잡기(steer)와 중단(stop), 대기(queue)가 추가된다. 한글과 영문 이름 모두로 고를 수 있다(/종료, /exit). Esc로 닫으면 / 글자가 질문에 남는다 |
@ |
세션 선택창. 이어서 결제, chart-v3처럼 치면 제목, 저장소, 워크트리, 브랜치, 폴더, 최근 작업, 제공자, Herdr 작업 공간 이름으로 거름. 지금 폴더의 세션이 먼저 골라져 있고 고른 세션의 폴더와 처음 요청이 아래에 미리 보임 |
# |
대화 선택창. 위의 대화 선택창과 같음 |
$ |
설정 선택창: 기본 설명 깊이(EASY, NORMAL, HARD), 미리 설명 켜기와 끄기, 설명 모델, 프로필 바꾸기. 깊이, 미리 설명, 모델은 고른 뒤에도 창이 남아 이어서 바꿀 수 있음 |
선택창은 입력창 자리까지 쓰고, 맨 위 검색창에 치는 글자(한글 포함)로 거른다. 위아래 방향키로 한 항목씩(끝에서는 반대편으로), PgUp, PgDn으로 한 화면씩 움직이고 Enter나 Tab으로 고른다. 지금 쓰는 항목에는 체크 표시가 붙고 오른쪽 아래에 고른 순번/전체가 보인다. 첫 Esc는 검색어를 지우고, 비어 있으면 선택창을 닫는다. 선택창과 입력창은 서로의 초안을 건드리지 않는다. 입력창의 첫 글자로 @, #, $를 치면 글자는 입력되지 않고 선택창이 열리므로, 그 기호로 시작하는 질문은 앞에 공백을 하나 두고 쓴다.
한글 입력: 화면의 입력 위치(입력창과 선택창의 검색창)에 진짜 터미널 커서를 두고 보이게 한다. 한글을 조합하는 글자와 후보 창이 그 자리에 붙는다. OMP의 showHardwareCursor와 같은 방식이다. 입력 위치에는 반전된 칸도 함께 그린다. 커서가 거슬리면 DOCENT_HARDWARE_CURSOR=0 docent-tui로 끄면 커서는 숨긴 채 입력 위치에만 둔다 (ADR 0068).
터미널 답변은 웹앱처럼 결론과 핵심 설명을 먼저 보여 주고 세부 내용은 접어 둔다. /자세히로 펼치고, /근거로 답변이 인용한 원문을 검색해 현재 원문과 저장 발췌를 구분해 본다. /복습(/review)은 웹앱의 배운 내용 다시보기와 같은 용어 사전이며, 용어를 검색하면 뜻과 관련 문답을 보여 준다.
마우스: 시작할 때 마우스 보고를 켠다. 방식은 OMP 전체 화면 모드와 Herdr를 따른다. 휠은 대화를 한 칸에 3줄(Herdr 기본값) 스크롤하고 맨 아래에 닿으면 새 글을 다시 따라가며, 선택창과 / 명령 목록에서는 한 칸에 항목 하나씩 옮긴다(끝에서 멈춤). 왼쪽 클릭은 선택창에서 누르면 그 항목이 골라지고 끌지 않고 떼면 열리며(OMP 목록과 같음), 입력창에서는 누른 글자 앞으로 커서를 옮긴다. 끌기는 누른 칸부터 끈 칸까지의 글자를 반전해 보이고 놓으면 복사한다. 두 번 누르기는 낱말(경로와 kebab-case 포함)을 골라 복사한다. 복사는 터미널 클립보드 코드(OSC 52, SSH 너머에서도 동작)와 이 컴퓨터의 macOS pbcopy로 하고, 복사하면 제목 줄 오른쪽에 N자 복사함이 잠깐 보인다. 키를 누르면 고른 글자가 풀리고 고른 글자가 있을 때 Ctrl+C는 복사만 한다. 오른쪽 클릭은 터미널(Herdr 메뉴)에 맡긴다. 마우스 보고를 켜면 터미널과 Herdr의 글자 끌기 선택이 이 창에서는 꺼지므로, 그쪽이 필요하면 /마우스(/mouse)로 끄고 다시 켠다. 처음부터 끄려면 DOCENT_MOUSE=0 docent-tui (ADR 0070).
같은 기능을 단축키로도 쓸 수 있다.
| 키 | 동작 |
|---|---|
| Ctrl+P | 세션 선택 |
| Ctrl+T | 대화 선택. 세션 전체 대화, 사건 카드, 이전에 저장한 대화 |
| Ctrl+O | 현재 대화의 저장된 답변 선택. 원래 질문과 답을 보여 주며 모델을 호출하지 않음 |
| Ctrl+G | 프로필 선택 |
| Esc | 대화를 읽거나 질문을 쓰는 중이면 대화 선택창을 연다(지금 대화가 골라져 있음). 선택창에서는 검색어 지우기, 닫기 |
| Ctrl+F | 지금 대화(선택창에서는 고른 대화)를 즐겨찾기에 넣거나 뺌. 웹과 같은 즐겨찾기 |
| Enter, Ctrl+J | 질문 보내기, 입력 중 줄바꿈. 여러 줄 붙여넣기도 지원. 설명 중 Enter는 대기 질문이 되어 지금 설명이 끝나면 차례대로 보냄. /대기 (queue)로 마지막 대기 질문을 입력창에 돌려놓아 고치거나 지움 |
| Ctrl+S | 진행 중인 설명의 바로잡기 입력으로 전환. 다시 누르면 질문 입력으로 돌아감 |
| Ctrl+C | 진행 중인 설명 중단. 설명이 없으면 초안을 유지 |
| Ctrl+R | 새로고침. 끊긴 설명은 같은 요청에 재연결 |
| PgUp, PgDn | 긴 원문과 답 스크롤 |
| Ctrl+D | 터미널 클라이언트 종료. 서버는 유지 |
프로필 만들기와 분야별 설명 깊이는 같은 서버의 웹앱 설정에서 한다. 터미널이 종료되어도 이미 보낸 설명 요청은 서버에 남으며, 다시 연결하면 진행 중인 설명에 붙고 그 설명의 대화로 간다. 다른 세션이나 프로필로 가면 그 설명은 서버에서 계속되고, 돌아오면 다시 붙는다. 미리 설명은 질문 입력을 막지 않는다. 대화와 프로필을 바꿀 때 초안과 커서 위치를 각각 보관하며, 선택 목록을 닫아도 초안이 사라지지 않는다. 초안은 실행 중 메모리에만 있으므로 클라이언트를 종료하면 사라진다. 중단한 질문과 보내지 못한 대기 질문은 그 대화의 입력창이 비어 있으면 돌아오고, 이미 다음 질문을 쓰고 있었다면 새 초안을 유지한다. Ctrl+R은 끊긴 요청에만 다시 붙으며, 이미 연결된 설명의 스트림이나 모델 호출을 중복으로 만들지 않는다.
Herdr 창에서 실행하면 Herdr의 agents 창에 docent로 나타난다. 직접 물은 설명이 진행 중이면 작업 중, 설명 연결이 끊기면 막힘, 끝나면 대기로 바뀌고, 종료하면 목록에서 사라진다. 서버가 미리 설명하는 것은 표시하지 않는다. Herdr 밖에서는 아무것도 알리지 않는다 (ADR 0043).
터미널에서 docent herdr를 치면 지금 그 창에서 바로 도슨트 터미널이 열린다. Herdr가 없어도 되고, 지금 작업 폴더의 가장 최근 세션이 열리며, 서버가 꺼져 있으면 백그라운드로 켠다. 도슨트를 닫으면 원래 셸로 돌아온다. Herdr 창 오른쪽에 따로 띄우려면 docent herdr --split을 쓴다. 같은 작업 공간에 도슨트 창이 이미 있으면 새로 만들지 않고 그 창으로 이동한다. omp를 쓰면 docent install-omp로 서브에이전트 정의와 /docent 명령을 설치해 omp 입력창에서 /docent로 지금 omp 세션을 오른쪽 창에 연다(--split과 같다). /docent는 Herdr 창 안에서만 동작하고, Herdr 밖(Windows 포함)에서는 다른 터미널 창의 docent-tui를 쓴다. 특정 세션은 docent-tui --session <세션 id>로 열 수 있다 (ADR 0044, 0059).
릴리스마다 GitHub Release에 앱이 함께 올라간다. Apple Silicon은 Vibecoder-Docent-<버전>-macos-arm64.zip, Intel Mac은 …-macos-x64.zip을 받아 풀고 Vibecoder Docent.app을 Applications 폴더로 옮긴다.
앱은 임시(ad-hoc) 서명만 되어 있고 Apple 공증을 받지 않았다. 처음 한 번은 Finder에서 앱을 우클릭해 "열기"를 고르거나, 터미널에서 다음을 실행한다.
xattr -dr com.apple.quarantine "/Applications/Vibecoder Docent.app"앱은 화면에서 업데이트하지 않는다. 새 버전은 릴리스의 zip을 다시 받아 바꾼다. 이 컴퓨터에 docent 서버가 이미 켜져 있으면 앱은 그 서버를 쓰므로, 서버를 docent update로 올리면 앱 화면도 새 버전이 된다 (ADR 0072, 0073).
직접 만들 수도 있다.
저장소에서 현재 Mac의 CPU 아키텍처에 맞는 앱을 만든다.
npm ci
npm run build:macos
open "dist/Vibecoder Docent.app"생성된 .app을 Applications 폴더로 옮겨 앱 아이콘으로 실행할 수 있다. 개발 중에는 npm run desktop을 쓴다. 앱에는 Electron의 Node 런타임과 표시 자산이 포함되며, omp 설치와 로그인은 여전히 필요하다.
- 정상 도슨트 서버가 같은 로컬 포트에 있으면 재사용한다. 없으면 앱이 서버를 시작한다.
- 앱을 종료할 때 자신이 시작한 서버와 그 서버의 모델 프로세스만 끈다. 기존 서버는 끄지 않는다. 창만 닫으면 macOS 메뉴와 서버는 유지되고, ⌘Q로 앱을 종료한다.
- 앱이 시작한 서버로 모바일을 연결했다면 앱이 실행 중이어야 한다. 독립적으로 실행한 서버를 재사용하면 앱 종료와 관계없이 모바일 연결이 유지된다.
DOCENT_HOME,DOCENT_PORT,OMP_BIN을 지원한다. Finder 실행에서도 일반적인 사용자 설치 경로와 Homebrew 경로에서 omp를 찾는다.- 로컬 빌드는 서명되지 않은 앱이다. Apple Developer ID 서명과 공증, 외부 배포는 별도 절차이며 이 빌드 명령이 자동으로 수행하지 않는다.
| 영역 | 하는 일 |
|---|---|
| 세션 | omp·Claude Code·Codex CLI·Gemini CLI·pi의 작업 세션을 고른다. 제목 아래에 최근 작업 한 줄, 그 아래에 저장소, 워크트리, 브랜치, 제공자, 컴퓨터, 시각이 보인다. 제목, 저장소, 브랜치, 최근 작업으로 검색하거나 최근 10개 다음 목록을 더 볼 수 있다. 오른쪽 경계를 끌어 너비를 바꿀 수 있다 (ADR 0048). |
| 작업 내용 | AI의 질문·결과·계획을 최신 순서로 보여 준다. 준비된 설명의 제목·요약을 보고 카드를 누른다. 오른쪽 경계를 끌어 너비를 바꿀 수 있다. |
| 카드별 대화 | 선택한 카드에 관해 이어 묻는다. 대화의 첫 메시지로 그 카드의 AI 출력 내용이 모두 보인다. 앞 문답을 기억하는 이어지는 대화이고, 질문이 다른 카드를 가리키면 그 카드 대화로 옮기기를 제안한다. 카드와 무관한 질문은 세션 전체 대화에 남긴다. 세션 전체 대화에서 설명 방식을 골라 다시 설명한 답도 세션 전체 대화에 남는다. 카드가 작업 내용에서 빠진 대화는 세션 전체 대화 맨 위 바로가기로 연다. 답은 나오는 대로 보이고, 결론부터 보여 주며 자세한 설명은 접어 둔다. |
| 입력창 | Enter는 보내기, Shift+Enter는 줄바꿈. 줄 맨 앞 - 는 불릿, 1. 은 번호 문단이 되고 Shift+Enter로 다음 항목을 이어 쓴다. |
| 설명 중 조작 | Esc나 멈춤 버튼은 설명을 멈추고 보낸 문장을 입력창에 돌려준다. Enter는 다음 질문으로 대기시키고(고치기·지우기 가능), ⌘Enter나 지금 바로잡기는 쓰던 설명을 멈추고 보정해 다시 설명한다. |
| 바로 질문 | 설명 방식을 고르면 입력창에 질문이 채워진다. 전송은 직접 눌러야 하며, 10초 설명은 생성 시간이 아닌 읽는 분량을 뜻한다. |
| 즐겨찾기 | 카드나 대화의 별을 눌러 저장하고 작업 내용에서 즐겨찾기만 볼 수 있다. |
| 배운 내용 다시보기 | 문답에서 모은 핵심 단어의 한 줄 뜻과 관련 대화를 검색·정렬한다. 옛 문답은 원할 때 용어 정리를 누른다. |
| 설정 | 프로필별 도슨트 모델, 기본·영역별 설명 모드, 미리 설명, 다른 기기에서 열기(Tailscale 공유), 밝음·어둠·자동 테마를 고른다. |
새 중요 사건의 쉬운 설명을 미리 준비하는 기능(미리 설명)은 새로 설치하거나 새로 만든 프로필에서 꺼져 있다. 웹 설정의 "새 주요 내용 자동 설명"이나 터미널 $ 설정의 "미리 설명 켜기"로 켠다. 이미 쓰던 프로필은 켜거나 끈 설정이 그대로 남는다 (ADR 0063). 켜 두면 세션을 한 번 열었을 때 docent가 12시간 동안 그 세션을 지켜보며 탭을 닫아도 준비한다. 프로필마다 한 번에 하나씩, 10분에 최대 5개이며, 직접 한 질문이 먼저다. 모델 호출에 시간과 비용이 들며 이전 사건은 미리 설명하지 않는다. docent가 부르는 omp는 사용자의 기억·확장 설정을 쓰지 않는다. 표시된 입력·출력 단가는 omp 카탈로그의 참고값이지 실제 청구액이 아니다.
도슨트 모델은 프로필마다 고른다. **기본은 "세션의 모델"**이다. 모델을 고르지 않으면 설명과 학습 분류가 설명 대상 세션이 마지막으로 쓴 모델(작업 기록의 모델 표기: omp, Claude Code, Codex)로 돌아간다. 기록에 모델이 없거나 omp 카탈로그에서 정확히 하나로 찾지 못하면 omp 기본 모델로 설명하고, 답의 메타 줄과 설정 화면에 그렇게 보인다. 모델을 고르면 그 모델이 세션의 모델보다 우선하고, 실행에 실패해도 다른 모델로 바꾸지 않는다. 원래 작업 세션의 모델은 바꾸지 않으며, 새 설명 요청에만 적용된다 (ADR 0016, 0069).
모델 범위는 프로필마다 정하는 선택 후보 범위다. 범위를 정하면 모델 선택 목록(웹 설정의 모델 탭, 터미널 $ 설정)에 범위 안의 모델과 지금 고른 모델만 보인다. 웹은 모델 탭의 "모델 범위"에서 체크하고 "범위 저장", 터미널은 $에서 "범위 정하기"를 고른 뒤 모델을 Enter로 담고 맨 위 "범위 저장"을 고른다. "범위 해제"를 하거나 비워서 저장하면 모든 모델이 보인다. 범위는 후보 목록만 좁히고 설명에 쓰이는 모델은 바꾸지 않는다.
원문 보기는 답이 인용한 기록을 확인할 수 있을 때만 열린다. 원격 컴퓨터가 꺼졌거나 원문이 바뀌었다면 당시 저장한 발췌임을 구분해 보여 준다. 도슨트는 알 수 없는 이유를 사실처럼 말하지 않아야 하고, 담당 에이전트에게 보낼 요청 문장은 사용자가 원할 때만 만든다.
**작은 창(PiP)**은 본문 화면의 미니 버전이다. 위쪽에는 작업 내용 카드 목록, 아래쪽에는 선택한 카드의 대화와 입력창이 있으며, 창을 넓히면 각각 왼쪽과 오른쪽에 놓인다. 작업 내용과 대화의 비중은 약 35:65다. 카드를 누르면 그 카드의 대화가 열리고 작은 창에서 보낸 질문도 본문과 같은 대화에 남는다. 별도 라이브 연결이나 모델 호출은 만들지 않는다. 원문 보기와 배운 내용 다시보기는 본문 창에서 연다. 데스크톱 Chromium의 Document Picture-in-Picture와 localhost 같은 보안 컨텍스트가 필요하며, 본문 탭을 닫으면 작은 창도 닫힌다.
양쪽 컴퓨터에서 도슨트를 실행하고 Tailscale 사설망으로 연결한다. 세션을 보여 주는 컴퓨터:
docent --host tailscale내 컴퓨터에서 그 주소를 등록한다:
docent --peer laptop=http://my-laptop:4747매번 옵션을 쓰지 않으려면 내 컴퓨터의 ~/.docent/config.json에 설정한다:
{"peers":{"laptop":"http://my-laptop:4747"}}보여 주는 컴퓨터에는 {"host":"tailscale"}로 설정할 수도 있다. 웹앱 설정창의 다른 기기에서 열기를 켜면 서버를 다시 시작하지 않고도 같은 대기를 열고 닫을 수 있고, 켜고 끈 상태는 config.json의 tailscale에 저장된다. 원격 세션의 전사와 라이브를 읽고 내 컴퓨터의 omp로 답을 만든다. 원격 문답 기록은 프로필이 같은 사람인지 확인할 수 없어 자동으로 합치지 않는다. 양쪽 도슨트 버전을 맞추는 편이 안전하다.
다른 컴퓨터 세션의 세션 정보에는 "SSH 접속" 줄(예: ssh book)이 보인다. 내 컴퓨터의 ~/.ssh/config에서 그 peer 주소와 같은 컴퓨터를 가리키는 Host 별칭을 찾는다. 주소는 이름이 같거나 같은 IP로 풀리면 같은 컴퓨터로 본다. 별칭 이름만 보이고 사용자 이름, 키, 포트는 싣지 않는다. 맞는 별칭이 없거나 ssh가 없으면 줄이 없고, 찾은 결과는 10분 동안 기억한다 (ADR 0067).
- 원본 세션은 해당 컴퓨터의
~/.omp·~/.claude에서 읽는다. 새 문답·학습 기억·즐겨찾기는 기본적으로 내 컴퓨터의~/.docent/learning.json에 저장한다. 이전questions.jsonl은 기본 프로필의 과거 문답으로 읽기만 한다. 프로필은 로그인이 아니다. - 앱은 기본적으로
127.0.0.1에만 열린다. 인증이 없으므로--host tailscale은 신뢰하는 사설망에서만 사용하고 Tailscale Funnel 등으로 공개하지 않는다. 원격 세션을 보면 전사 내용이 두 컴퓨터 사이로 전달된다. DOCENT_HOME으로 도슨트 데이터 폴더를 바꿀 수 있다.DOCENT_PORT,DOCENT_HOST,DOCENT_PEERS로 포트·호스트·동료 설정을 지정할 수 있고,OMP_BIN으로 omp 실행 파일을 지정할 수 있다.OMP_BIN이.js,.mjs,.cjs파일이면 지금 쓰는 Node로 실행한다(npm으로 설치한 omp의 JS 진입점, ADR 0062).TYPESAFE_API_KEY는 Jev 판정을 위한 선택적 환경변수다. 비밀값은 설정 파일에 쓰지 않는다.- 같은 데이터 폴더를 여러 서버에서 동시에 수정하지 않는다. 이 앱의 프로필 선택은 접근 제어가 아니며, 외부에 열기 위한 인증 기능도 없다.
자세한 보안 모델과 취약점 제보 방법은 SECURITY.md를 참고한다.
npm ci
npm run build
npm start
node --test tests/*.test.mjs빌드는 React·Streamdown 표시 자산을 로컬에 만든다. 배포 패키지에도 자산이 포함되어 실행 중 CDN이 필요하지 않다. 코어 설명 규칙은 prompt/docent.md, 설계는 docs/architecture.md, 결정 과정은 docs/decisions/에 있다. 기여 방법은 CONTRIBUTING.md를 참고한다.
코드는 MIT (Copyright (c) 2026 foxion37). 포함된 Pretendard 글꼴은 SIL Open Font License 1.1이며 THIRD_PARTY_NOTICES.md에 고지한다.