Folder Bot 설치 가이드 — Mac mini(호스트) · 원격 맥(클라이언트) · 폰

v0.3.0 · 2026-09-12. 짧은 요약: 미니와 맥북에 같은 앱을 설치한다. 미니에서는 「이 맥에서 호스트 실행」, 맥북에서는 미니 주소를 넣고 6자리 코드로 연결. 폰은 브라우저로 같은 주소.

┌────────────── Mac mini (항상 켜 둠) ──────────────┐
│ Folder Bot.app  ─ 호스트 모드 ─ Claude Code 워커들 │
│   └ 루트 = Dropbox/PARA  (봇 = 폴더 하나 + 에이전트) │
└──────────────┬────── Tailscale ──────────┬────────┘
        맥북 Folder Bot.app            iPhone/Android 브라우저
        (미니 주소 + 페어링 코드)         (같은 주소 + 코드 · 홈 화면 추가)

0. 준비물 (미니)

1. Mac mini — 호스트 설치 (앱, 터미널 없음)

1. 릴리스에서 Folder Bot-<버전>-arm64.dmg 를 받아 /Applications 로 끌어 놓습니다.
   • https://github.com/dave-jin/folderbot/releases (최신 desktop-v*)
2. ad-hoc 서명이라 처음엔 Gatekeeper 가 막습니다. DMG 안의 「처음 설치 후 읽어주세요.txt」 대로 터미널에 한 줄을 붙여 넣으면 됩니다:

   xattr -dr com.apple.quarantine "/Applications/Folder Bot.app"
   

   자동 업데이트로 받은 빌드는 앱이 알아서 뗍니다.
3. 앱은 ad-hoc 서명입니다(빌드가 codesign --sign - 로 서명). 서명이 있어야 macOS 알림 센터에 등록되어 알림이 옵니다 — 설정 › 알림 목록에 Folder Bot 이 보이면 정상입니다.
4. 처음 열면 권한 화면이 먼저 뜹니다 — 호스트 맥이면 전체 디스크 접근(Dropbox·문서·데스크탑 폴더를 읽고 저장), 어느 맥이든 알림(확인 요청·완료를 알려 줌). [시스템 설정 열기] 로 해당 설정을 열어 Folder Bot 을 켜고 이 창으로 돌아오면 자동으로 확인합니다. 알림은 [테스트 알림 보내기] → 보였으면 [보였어요]. 필수가 다 켜져야 [계속] 이 열립니다. ⚠ 업데이트로 앱 서명이 바뀌면 전체 디스크 접근이 풀리므로 그때 이 화면이 다시 뜹니다(알림은 유지). 설정 › macOS 권한 › [권한 다시 확인] 으로 언제든 다시 볼 수 있습니다.
5. 첫 화면 아래 「이 맥에서 호스트 실행」 › [루트 폴더 고르고 시작] → PARA 루트 선택.
   • 루트 CLAUDE.md 에 ## 폴더 규칙 절이 덧붙고(있는 내용은 안 건드림) 호스트가 뜹니다.
   • 로그인 항목이 자동으로 켜집니다. 재부팅 뒤 사람이 로그인만 하면 다시 뜹니다(자동 로그인을 켜 두면 전원만).
6. 메뉴바 폴더봇 아이콘 우클릭 → 페어링 코드 복사 · 폰에서 열 주소 복사.

왜 앱이어야 하나: Claude CLI 는 사람이 GUI 로 로그인한 세션 안에서만 키체인을 읽습니다. SSH·launchd·스크립트로 띄우면 Not logged in · Please run /login 이 됩니다. 앱은 로그인 항목이라 그 세션 안에서 뜹니다.

1′. 대안 — 터미널(CLI) 설치

curl -fsSL https://raw.githubusercontent.com/dave-jin/rondo-releases/main/folderbot/install.sh | bash
folderbot init "$HOME/Library/CloudStorage/Dropbox/PARA"
folderbot start        # Jump Desktop 으로 들어가 GUI 에서 새로 연 Terminal 에서. tmux 로 띄우면 창을 닫아도 살아요

2. 원격 맥(맥북) — 클라이언트 설치

1. 같은 DMG 를 받아 /Applications 로. 처음엔 우클릭 → 열기.
2. 첫 화면에 미니 주소를 넣습니다: http://<미니 Tailscale IP>:7373 (메뉴바 › 폰에서 열 주소 복사) 또는 HTTPS 를 붙였다면 https://mac-mini.<tailnet>.ts.net.
3. 미니에서 복사한 6자리 페어링 코드를 넣으면 연결. 기기별 토큰이 저장되어 다음부턴 바로 열립니다(설정 › 기기 › 끊기).
4. 메뉴바에 폴더봇 아이콘 — 확인 대기 수가 배지로, 클릭하면 창, 우클릭 메뉴에 로그인 시 자동 실행. 알림은 macOS 알림 센터로 오고 누르면 그 대화로 갑니다.

맥북에는 호스트가 없습니다. 미니가 꺼져 있으면 「Mac mini 와 다시 연결하는 중…」 이 뜨고 저장된 대화만 보입니다.

3. 폰 (iPhone · Android)

1. Tailscale 앱 켜기 → Safari/Chrome 에서 미니 주소 → 6자리 코드.
2. 홈 화면에 추가 하면 앱처럼 뜹니다. 탭바는 없고 홈(카드 4 + 봇 목록) → 대화 → 폴더 → 문서를 밀어 넣는 식입니다. 왼쪽 위 둥근 버튼이 뒤로, 대화 오른쪽 위 폴더 버튼이 「이 폴더에서」. 화면은 확대되지 않고(입력 16px) 상태바·홈 인디케이터 뒤까지 꽉 찹니다.
3. 푸시 알림은 HTTPS 에서만 동작합니다. 미니에서 한 번:

   tailscale serve --bg 7373
   

   → https://mac-mini.<tailnet>.ts.net 으로 열고 홈 화면에 추가 → 설정 › 이 기기 푸시 켜기.

• 홈화면 앱에서 상태바는 시스템이 그립니다(불투명·앱 배경색). 화면은 그 아래에서 시작하고, 아래는 홈 인디케이터 위에 바짝 붙습니다. 키보드가 뜨면 화면이 그만큼 줄어 입력칸이 키보드 바로 위에 옵니다.

4. 자동 업데이트 — 앱이 스스로 받아 재시작

• 앱이 부팅 15초 뒤 + 30분마다, 그리고 창을 띄울 때(10분에 한 번) 이 리포의 릴리스(desktop-v*, 공개)를 보고 조용히 받아 둡니다. 토큰·시크릿 필요 없음. 안 되는 것 같으면 ~/Library/Application Support/Folder Bot/updates/log.txt 에 이유가 적혀 있어요.
• 왼쪽 아래 버전 칩(v0.2.x) 을 누르면 바로 확인하고 결과(최신 · 받는 중 · 준비됨 · 실패 이유)를 화면 안 토스트로 알려 줍니다. 브라우저·폰 화면에서 누르면 «호스트가 스스로 받는다» 안내만 뜹니다.
• 맥북(클라이언트): 다 받으면 확인창 하나 — [지금 재시작해서 적용] / [나중에]. 화면 왼쪽 아래 버전 칩(v0.2.8 재시작해서 적용)이나 메뉴바 › 업데이트 적용으로도 됩니다. 칩을 누르면 수동 확인.
• 미니(호스트): 진행 중 세션이 있으면 전부 유휴가 되는 순간 자동 적용(세션을 죽이지 않음). 칩에 「세션 N개 끝나면 적용」이 보입니다. 없으면 바로 재시작.
• 교체는 앱이 완전히 종료된 뒤 분리된 스크립트가 zip 을 풀어 /Applications/Folder Bot.app 을 갈아 끼우고 다시 엽니다(ditto --noqtn — 검역 딱지를 떼므로 Gatekeeper 가 다시 묻지 않음). /Applications 밖에 있으면 자동 교체 대신 받아 둔 zip 을 열어 줍니다.
• ⚠ desktop-v7 이하는 옛 주소(비공개 리포)를 보고 있어 스스로 못 받습니다. v8 을 한 번만 DMG 로 설치하면 그다음부터는 자동입니다.

5. 로그인이 안 될 때 (Not logged in · OAuth session expired)

6. 화면 — 네 열

목록 │ 대화 │ 문서 │ 이 폴더에서(세션 · 할 일 · 파일 · 루틴)

• 모든 경계가 핸들: 열 사이 3곳, 패널 섹션 사이 2곳을 드래그. 더블클릭 = 기본값. 창이 좁으면 목록·패널이 44px 아이콘 열로 접힙니다(겹치는 창 없음).

• 문서 열: 오른쪽 파일 트리를 클릭하면 미리보기 탭(기울임), 더블클릭·편집이면 고정. 폴더 안 ↑↓ 로 이전·다음 파일. 본문 더블클릭 = 편집(자동 저장). 봇이 파일을 쓰면 한 줄 배너.

• 진행: 대화 맨 아래 한 줄 — 펄스 점 · 지금 하는 일 · 경과 · 중단. 실행 중에 보내면 대기열에 들어가 턴이 끝나면 순서대로.

• 서브에이전트: ↳ 이름 · 실행 중 · 도구 N회 한 줄 → 꺾쇠로 마지막 도구 몇 줄 → 「열기」로 안으로.

• 입력창 아래 한 줄: 왼쪽 「자동 ▾」(모드 · 1~4키) · ＋(첨부) / 오른쪽 모델 · 노력 · 컨텍스트 링 · 보내기. 세션마다 바꿀 수 있고, 바꾸면 그 세션을 이어서 재시작해요(턴 중이면 끝난 뒤). / 를 치면 이 폴더의 스킬·명령이, @ 를 치면 파일이 자동완성됩니다.

• 파일 넣기: @이름 · 오른쪽 트리에서 끌어다 놓기(폴더째도) · Finder 에서 끌어다 놓기(첨부/ 에 복사) · 우클릭 「첨부로 보내기」「@ 로 언급하기」「폴더째 첨부」 · ＋ 메뉴 「열린 문서 첨부」 · 스크린샷 ⌘V. 어디서 오든 입력창 위 칩 줄로 모여요.

• 떠 있는 것만 유리: 헤더 · 직전 질문(위로 사라지면 헤더 아래 고정) · ↓ 최근으로 · 입력창. 시스템 「투명도 줄이기」를 켜면 불투명.

• 폴더 선택: PARA 트리를 접었다 펴서 아무 폴더나 고릅니다(Resources·Archive 포함). 트리에서 폴더 우클릭 → 「여기서 에이전트 시작」. 봇이 있는 폴더는 「봇 열기」.

• 메인 · 원격: 왼쪽 아래(폰은 홈 제목 아래) 배지가 호스트 맥 자체의 창이면 「메인」, 다른 기기면 「원격 · 기기이름」. 이름은 설정 › 이름에서 바꿉니다(기본값은 컴퓨터 이름·페어링 때 고른 기기 종류).

• 할 일: 제목을 누르면 그 자리에서 편집(⏎ 저장), 삭제는 5초 안에 되돌릴 수 있고, 눈 아이콘으로 완료 항목을 봅니다.

• 단축키: ⌘B 목록 · ⌘⇧B 패널 · ⌘⇧D 문서 열 · ⌘W 탭 닫기 · ⎋ 편집 끝.

• 레일 호버 카드 — 봇 행에 마우스를 올리면 경로·상태·세션(모델·컨텍스트)·할 일·마지막 말이 카드로 뜹니다. 접힌 스트립의 작은 플라이아웃과 같은 정보입니다.

• 할 일 행 — 글이 오른쪽 끝까지 쓰이고, 연필·맡기기·삭제는 마우스를 올리면 글 위 오른쪽에 뜹니다(폰은 항상). 긴 항목은 2줄에서 «…더», 누르면 그 행만 펼쳐집니다.

• 긴 이름 — 폴더·파일 이름은 Finder 처럼 앞뒤를 남기고 가운데를 … 로 줄입니다.

• 테마 — 설정 › 화면에서 시스템·라이트·다크를 고릅니다. 기본은 시스템을 따릅니다.

• 폰에서 할 일 — 행을 좌우로 쓸어 처리합니다. 오른쪽으로 조금=편집, 길게=완료, 왼쪽으로 조금=메뉴, 길게=삭제. 설정 › 할 일에서 네 자리를 바꿀 수 있습니다.

7. 기본 모델 · 생각 레벨

설정 › 모델 · 생각 레벨은 새 세션의 기본값입니다(기본 Fable 5.1 + 높음). 열려 있는 세션은 입력창 아래 줄에서 따로 바꿉니다 — 모델 · 노력 · 모드 어느 것이든 바꾸면 그 세션의 워커를 내리고 같은 대화를 이어서 새 값으로 띄워요.

8. 데이터 위치

9. 자주 겪는 것