mulmoclaude

MulmoClaude

English · 日本語 · 简体中文 · 한국어 · Español · Português (BR) · Français · Deutsch

📖 사용자 가이드: https://receptron.github.io/mulmoclaude/

🛠️ Mac용 설정 가이드 (일본어): https://receptron.github.io/mulmoclaude/setup/

당신에 대해 모든 것을 알고 24시간 내내 당신을 지원하는 AI 어시스턴트는 어디에서도 팔지 않습니다. 살 수는 없고, 키울 수만 있습니다. MulmoClaude는 자신만의 AI 어시스턴트를 자신의 컴퓨터에서 키우기 위한 도구입니다.

어시스턴트의 본질은 AI 모델이 아닙니다. 모델은 그저 엔진일 뿐입니다. 어시스턴트를 가치 있게 만드는 것은 그것이 당신에 대해 얼마나 많이 아는가입니다. 당신의 대화, 캘린더, 노트, 데이터, 그리고 당신이 사용하는 앱들 말입니다. 그렇게 중요한 것을 특정 서비스 제공자 한 곳에 맡겨서는 안 됩니다. 오래 사용할수록 떠나기가 더 어려워지기 때문입니다. MulmoClaude는 오픈 소스이며 로컬에서 실행되므로, 어시스턴트가 축적하는 모든 것—기억, 데이터, 앱—이 당신의 워크스페이스 안에 있는 평범한 파일로 당신의 손에 남습니다.

키우려면 환경이 필요하고, MulmoClaude가 그 환경을 제공합니다. 기억을 축적하는 곳(Claude가 스스로 구축하고 유지하는 개인 위키), 데이터를 보관하는 곳(스키마 기반 컬렉션, 피드, 평범한 파일), 그리고 당신만을 위한 앱을 만드는 곳—프로그래밍 지식이 필요 없습니다. "이런 게 있으면 좋겠어"라고 일상적인 말로 말하면, Claude가 당신에게 필요한 작은 앱을 만들어 줍니다. 맛집 목록, 인보이스 추적기, 어휘 연습—한 사람만을 위한 소프트웨어입니다. 설치 직후 정원은 비어 있습니다. 씨앗을 심고 흙을 가꾸며, 오직 당신만의 어시스턴트를 키우세요.

그리고 어시스턴트는 당신의 책상에 묶여 있지 않습니다. 휴대폰에서—혹은 이미 사용 중인 메시징 앱에서—로그인하면, 당신의 컴퓨터에 살고 있는 같은 어시스턴트에 닿을 수 있습니다. 릴레이 서버는 메시지를 전달만 합니다. 당신의 기억, 데이터, 앱은 절대 당신의 컴퓨터를 떠나지 않습니다.

내부적으로 MulmoClaude는 AI 네이티브 애플리케이션 플랫폼입니다. 기능은 단일 레지스트리의 플러그인이고(현재: 실제 서버 측 부기 로직을 갖춘 완전한 회계 시스템, 개인 위키, SEC 공시 문서 리더 등), Claude는 이들을 넘나들며 조합하는 범용 컨트롤러 역할을 하며, 채팅은 각 작업에 맞는 GUI—마크다운, 차트, 폼, 위키, 스프레드시트, 또는 3D 장면—를 불러냅니다.

AI 네이티브 애플리케이션은 어떻게 만들어져야 하는가 — MulmoClaude 뒤에 있는 아키텍처, UX, 프로토콜 논지.

📣 업데이트
새 릴리스와 기능은 X에서 일본어로 공지됩니다.

Singularity Society (@SingularitySoci) — 릴리스 및 기능 공지
Satoshi Nakajima (@snakajima) — MulmoClaude 소유자

빠른 시작
npx mulmoclaude@latest
런처가 서버를 부팅하고 브라우저에서 http://localhost:3001을 엽니다. 그게 전부입니다—채팅을 시작하세요.

계속 실행하기 : 터미널을 닫으면 서버가 중지됩니다. 백그라운드에서 실행하려면 tmux / screen(macOS/Linux) 안에서 실행하거나 시작 작업(Windows 작업 스케줄러)으로 실행하세요.

아이콘에서 실행하기 (macOS / Windows)
터미널을 열지 않고 실행하려면 앱 번들을 한 번 생성하세요:

npx mulmoclaude@latest create-shortcut
이 명령은 /Applications에 MulMoClaude.app을 작성합니다(쓸 수 없는 경우 ~/Applications—경로를 선택하려면 --dir <path>, 프롬프트를 건너뛰려면 --yes 전달). 더블클릭하면 필수 요건을 확인하고, 서버가 시작되는 동안 진행 페이지를 보여주며, 준비되면 앱을 엽니다. 서버가 이미 실행 중이면 두 번째 서버를 시작하지 않고 브라우저만 엽니다.

무언가 빠져 있을 때—Node.js, npx, 또는 Claude Code—시스템 언어로 무엇이 빠졌고 무엇을 실행해야 하는지 알려줍니다. 로그는 ~/Library/Logs/MulmoClaude/launcher.log에 있습니다.

.env 위치 : 터미널 실행은 실행한 디렉터리에서 .env를 읽습니다. 아이콘에는 그런 디렉터리가 없습니다—macOS는 앱을 /에서 시작하고, Windows는 바로 가기가 가리키는 곳에서 시작합니다—따라서 아이콘 실행은 홈 디렉터리의 ~/.env를 읽습니다.

Windows에서는 같은 명령이 대신 시작 메뉴에 바로 가기를 작성하며(--dir로 다른 곳, 예를 들어 바탕 화면에 둘 수 있음), 런처 자체 파일은 %LOCALAPPDATA%\MulmoClaude 아래에 둡니다. 콘솔 창을 열지 않습니다. 그 외의 모든 것은 동일하게 동작합니다.

업그레이드 후 명령을 다시 실행하세요: 바로 가기는 런처의 자체 사본을 담고 있습니다.

필수 요건

Node.js 22.22.2+ / 24.15+ / 26+ — 런타임
Claude Code CLI — 설치 및 인증 완료. OAuth를 완료하려면 claude를 한 번 실행하세요
ffmpeg — 영화 생성에 필요. 동영상을 생성하지 않는다면 건너뛰세요

macOS: brew install ffmpeg
Linux: apt install ffmpeg
Windows: winget install Gyan.FFmpeg

Docker Desktop (선택 사항이지만 권장) — 샌드박스 모드를 활성화합니다. 아래 Docker Desktop 설치하기 참조
whisper.cpp (선택 사항, macOS 전용) — 로컬 음성 입력(채팅 메시지 받아쓰기)을 활성화합니다. 아래 선택 사항: 로컬 음성 입력 참조

UI 언어 : 8개 로케일을 지원합니다(영어, 일본어, 중국어 간체, 한국어, 스페인어, 브라질 포르투갈어, 프랑스어, 독일어). 기본값은 브라우저 / OS 언어에서 자동 감지됩니다. 명시적으로 설정하려면 .env에 VITE_LOCALE=ja(또는 zh / ko / es / pt-BR / fr / de)를 넣으세요. 로케일은 빌드/개발 시점에 선택됩니다. 변경 후 yarn dev를 재시작하세요. 문자열 추가 방법은 docs/developer.md를 참조하세요.

소스에서 실행하기 (개발자용)
단순히 실행하는 대신 코드를 수정하려면:

git clone [email protected]:receptron/mulmoclaude.git
cd mulmoclaude && yarn install
cp .env.example .env # 선택 사항 — 이미지 생성을 위해 GEMINI_API_KEY 추가
yarn dev
http://localhost:5173을 여세요. 아키텍처와 스크립트는 docs/developer.md를 참조하세요.

UI가 깨져 보이거나 스타일이 적용되지 않나요? 아이콘이 단어로 표시되거나, dist/* 404, 재시작 후 401 — docs/troubleshooting.md를 참조하세요.

무엇을 할 수 있나요?

Claude에게 요청...
얻는 것

"프로젝트 제안서 작성해 줘"
캔버스의 리치 마크다운 문서

"지난 분기 매출 차트로 보여 줘"
인터랙티브 ECharts 시각화

"교토 여행 계획 만들어 줘"
이미지가 포함된 일러스트 가이드

"할 일 목록 만들어 줘"
칸반 보드가 있는 스키마 기반 컬렉션

"이 글 수집해 줘: URL"
장기 기억을 위한 [[링크]]가 있는 위키 페이지

"매일 뉴스 다이제스트 예약해 줘"
자동으로 실행되는 반복 작업

"노을 이미지 생성해 줘"
AI 생성 이미지 (Gemini)

"이 RSS 피드 구독해 줘"
/feeds의 데이터 피드, 일정에 따라 가져옴

"내 피드에 새 소식 있어?"
/feeds에 수집된 피드 항목

직접 방문할 수 있는 페이지 : /wiki(탐색 + 린트), /feeds(데이터 피드), /collections(데이터 앱), /automations(반복 작업), /files, /skills, /roles. 각 페이지에는 페이지 컨텍스트를 이미 알고 있는 새 채팅을 생성하는 자체 범위 지정 채팅 작성기가 있습니다.

MulmoClaude를 해킹하고 있나요? 환경 변수, 스크립트, 아키텍처는 docs/developer.md를 참조하세요.

메시징 브리지
MulmoClaude는 브리지 프로세스를 통해 메시징 앱에서 접근할 수 있습니다. 브리지는 별도의 자식 프로세스로 실행되며 socket.io를 통해 서버에 연결합니다.

# 대화형 CLI 브리지 (같은 머신)
yarn cli

# Telegram 봇 브리지 (.env에 TELEGRAM_BOT_TOKEN 필요)
yarn telegram
브리지는 독립형 npm 패키지로도 사용할 수 있습니다:

# 채팅 플랫폼
npx @mulmobridge/cli@latest # CLI 브리지
npx @mulmobridge/telegram@latest # Telegram 브리지
npx @mulmobridge/slack@latest # Slack 브리지
npx @mulmobridge/discord@latest # Discord 브리지
npx @mulmobridge/line@latest # LINE 브리지
npx @mulmobridge/whatsapp@latest # WhatsApp 브리지
npx @mulmobridge/matrix@latest # Matrix 브리지
npx @mulmobridge/irc@latest # IRC 브리지
npx @mulmobridge/mattermost@latest # Mattermost 브리지
npx @mulmobridge/zulip@latest # Zulip 브리지
npx @mulmobridge/messenger@latest # Facebook Messenger 브리지
npx @mulmobridge/google-chat@latest # Google Chat 브리지
npx @mulmobridge/mastodon@latest # Mastodon 브리지
npx @mulmobridge/bluesky@latest # Bluesky 브리지
npx @mulmobridge/chatwork@latest # Chatwork 브리지 (일본 비즈니스 채팅)
npx @mulmobridge/xmpp@latest # XMPP / Jabber 브리지
npx @mulmobridge/rocketchat@latest # Rocket.Chat 브리지
npx @mulmobridge/signal@latest # Signal 브리지 (signal-cli-rest-api 경유)
npx @mulmobridge/teams@latest # Microsoft Teams 브리지 (Bot Framework)
npx @mulmobridge/line-works@latest # LINE Works 브리지 (엔터프라이즈 LINE)
npx @mulmobridge/nostr@latest # Nostr 암호화 DM 브리지
npx @mulmobridge/viber@latest # Viber 브리지

# 범용 / 글루
npx @mulmobridge/webhook@latest # 범용 HTTP 웹훅 (개발 글루)
npx @mulmobridge/twilio-sms@latest # Twilio를 통한 SMS
npx @mulmobridge/email@latest # 이메일 브리지 (IMAP + SMTP)
모든 브리지는 실시간 텍스트 스트리밍(에이전트가 작성하는 동안 타이핑 업데이트)을 지원합니다. CLI와 Telegram은 파일 첨부(이미지, PDF, DOCX, XLSX, PPTX)도 지원합니다. 전체 플랫폼 목록과 설정 방법은 docs/mulmobridge-guide.md를 참조하세요.

장시간 실행되는 브리지의 인증 토큰 지속성
MulmoClaude 서버는 시작할 때마다 새 베어러 토큰을 재생성하여 <workspace>/.session-token($MULMOCLAUDE_WORKSPACE_PATH, 설정되지 않은 경우 ~/mulmoclaude)에, 그리고 바인딩한 포트를 .server-port에 작성합니다.

브리지는 재시작을 스스로 따라갑니다. 연결이 실패하면 두 파일을 다시 읽고, 서버가 새 세대—새 토큰, 새 포트, 또는 둘 다—를 게시하면 소켓을 다시 구축합니다(#3078). 브리지를 재시작할 필요가 없습니다.

브리지가 서버와 다른 머신에서 실행되어 워크스페이스를 전혀 읽을 수 없을 때는 토큰을 고정하는 것이 여전히 유용합니다. 양쪽에 동일한 긴 임의 값으로 MULMOCLAUDE_AUTH_TOKEN을 설정하세요. 그러면 서버는 재생성하는 대신 그 값을 그대로 사용합니다.

# 서버 (일회성 설정 — 재시작 간 동일한 값)
MULMOCLAUDE_AUTH_TOKEN=long-random-string yarn dev

# 브리지 (별도 프로세스 / 머신 — 동일한 값)
MULMOCLAUDE_AUTH_TOKEN=long-random-string \
TELEGRAM_BOT_TOKEN=... \
npx @mulmobridge/telegram@latest
권장: 최소 32자의 임의 데이터(더 짧은 값은 서버가 시작 시 경고를 기록합니다).

Gemini API 키가 왜 필요한가요?
MulmoClaude는 이미지 생성 및 편집에 Google의 Gemini 3.1 Flash Image(nano banana 2) 모델을 사용합니다. 이것이 다음을 지원합니다:

generateImage — 텍스트 설명으로 이미지 생성
editImage — 기존 이미지를 변환하거나 수정 (예: "지브리 스타일로 변환")
문서에 삽입되는 인라인 이미지 (레시피 가이드, 여행 플래너 등)

Gemini API 키가 없으면 이미지 생성을 사용하는 역할이 UI에서 비활성화됩니다.

Gemini API 키 받기

Google AI Studio로 이동
Google 계정으로 로그인
Create API key 클릭
키를 복사하여 .env 파일에 GEMINI_API_KEY=...로 붙여넣기

Gemini API에는 개인 사용에 충분한 무료 티어가 있습니다.

보안
MulmoClaude는 AI 백엔드로 Claude Code를 사용하며, 여기에는 Bash를 비롯한 도구에 대한 접근 권한이 있습니다—즉, 당신의 머신에서 파일을 읽고 쓸 수 있습니다.

Docker가 없으면 Claude는 당신의 사용자 계정이 접근할 수 있는 모든 파일에 접근할 수 있으며, 워크스페이스 외부에 저장된 SSH 키와 자격 증명도 포함됩니다. 이는 개인 로컬 사용에는 허용되지만, 이해해 둘 가치가 있습니다.

Docker Desktop이 설치되어 있으면 MulmoClaude는 자동으로 샌드박스 컨테이너 안에서 Claude를 실행합니다. 당신의 워크스페이스와 Claude 자체 설정(~/.claude)만 마운트되며, 나머지 파일 시스템은 Claude에게 보이지 않습니다. 구성이 필요 없습니다: 앱이 시작 시 Docker를 감지하고 샌드박스를 자동으로 활성화합니다.

베어러 토큰 인증 : 모든 /api/* 엔드포인트는 Authorization: Bearer <token> 헤더를 요구합니다. 토큰은 서버 시작 시 자동 생성되어 <meta> 태그를 통해 브라우저에 주입됩니다—수동 설정이 없습니다. 유일한 HTTP 예외는 /api/files/*이며(렌더링된 문서의 <img> 태그는 헤더를 첨부할 수 없으므로 면제), /ws/pubsub socket.io 핸드셰이크는 동일한 토큰을 auth.token으로 제시합니다. 자세한 내용은 docs/developer.md를 참조하세요.

샌드박스 자격 증명 전달 (선택): 기본적으로 샌드박스는 호스트 자격 증명에 접근할 수 없습니다. 두 개의 환경 변수로 git / gh에 필요한 것만 선택적으로 노출할 수 있습니다:

SANDBOX_SSH_AGENT_FORWARD=1 — 호스트의 SSH 에이전트 소켓을 전달합니다. 개인 키는 호스트에 남습니다.
SANDBOX_MOUNT_CONFIGS=gh,gitconfig — ~/.config/gh와 ~/.gitconfig를 읽기 전용으로 마운트합니다.

전체 계약 및 보안 노트: docs/sandbox…