receptron/mulmoclaude

MulmoClaude – a locally‑run AI‑native personal assistant platform

What it is – MulmoClaude is an open‑source application that lets you run a Claude‑powered AI assistant on your own computer. The assistant lives in a workspace (plain files on disk) where it stores a personal wiki, data collections, automations and tiny custom apps that Claude can generate for you on demand. All the AI‑driven logic runs locally (or inside a Docker sandbox) and never leaves your machine.

Why it matters – The value of a personal assistant is the knowledge it accumulates about you, not just the language model. MulmoClaude gives you a self‑hosted, file‑based store for that knowledge and a UI that lets Claude compose across plugins (wiki, accounting, feeds, image generation, etc.) while you interact via a web chat or any of dozens of messaging bridges.

---

Quick start (one‑liner)

npx mulmoclaude@latest   # launches the server and opens http://localhost:3001

Keep the terminal open, or create a desktop shortcut with npx mulmoclaude@latest create-shortcut.

Core components

Component	Role
Server	Node.js 20+ process that hosts the UI, REST API and socket.io bridge.
Claude Code CLI	Backend LLM; provides tool‑calling, Bash access and skill execution.
Docker sandbox (optional)	Runs Claude inside a container, exposing only the workspace and Claude config.
Plugins / Registry	Built‑in capabilities such as a personal wiki, accounting system, SEC‑filings reader, data feeds, etc.
Roles	Pre‑defined personas (General, Office, Guide & Planner, Artist, Tutor, Storyteller) that swap tool palettes for faster, focused responses.
Bridges	Separate npm packages (@mulmobridge/*) that connect the server to Telegram, Slack, Discord, WhatsApp, email, SMS, etc., via socket.io.
Skills	Re‑usable Claude Code skill folders (~/.claude/skills/…) that can be listed and run from the UI with a single click.

What you can do (example prompts)

• “Write a project proposal” → rich markdown document.
• “Chart last quarter’s revenue” → interactive ECharts chart.
• “Create a trip plan for Kyoto” → illustrated guide with images.
• “Set up a todo list” → kanban board backed by a schema‑driven collection.
• “Ingest this article: ” → wiki page with permanent [[links]].
• “Generate an image of a sunset” → Gemini 3.1 Flash image generation (requires a Gemini API key).
• “Subscribe to this RSS feed” → data feed stored under /feeds and refreshed on schedule.

All of these are accessible through dedicated pages (/wiki, /feeds, /collections, /automations, /files, …) each with its own chat composer that automatically provides the relevant context.

Installation & prerequisites

Requirement	How to obtain
Node.js 20+	Download from nodejs.org.
Claude Code CLI	npm i -g @anthropic/claude-code (or follow the link in the README) and run claude once to complete OAuth.
ffmpeg (optional, for video generation)	brew install ffmpeg / apt install ffmpeg / winget install Gyan.FFmpeg.
Docker Desktop (recommended)	Install from docker.com – enables sandbox mode automatically.
Gemini API key (optional, for image generation)	Create at Google AI Studio and add GEMINI_API_KEY=… to .env.
whisper.cpp (macOS only, optional)	Install for local voice input.

After installing the prerequisites, run the one‑liner above or clone the repo for development:

git clone https://github.com/receptron/mulmoclaude.git
cd mulmoclaude && yarn install
cp .env.example .env   # add GEMINI_API_KEY if you want images
yarn dev               # UI at http://localhost:5173

Security model

• Claude Code has full Bash access; without Docker it can read/write any file your user can reach (including SSH keys). Use the Docker sandbox to restrict it to the workspace and ~/.claude config only.
• Bearer‑token auth protects all /api/* endpoints; the token is generated at server start and injected into the browser via a <meta> tag.
• Credential forwarding is opt‑in via SANDBOX_SSH_AGENT_FORWARD and SANDBOX_MOUNT_CONFIGS.
• File logging – human‑readable console logs plus JSON logs rotated daily under server/system/logs/.

Ecosystem & extensibility

• Bridge packages (@mulmobridge/*) let you expose the assistant to any chat platform you use. They run as child processes and reconnect automatically after server restarts.
• Skills – any folder under ~/.claude/skills/ containing a SKILL.md can be discovered, listed and executed from the UI. Project‑scoped skills live inside the workspace and override user‑scoped ones with the same name.
• Plugins – the platform’s registry can be extended with additional native plugins (e.g., more accounting tools, custom data parsers) by following the developer docs.

License & community

• License: MIT (see LICENSE).
• Updates & announcements – posted on X (formerly Twitter) by the project owner Satoshi Nakajima and the “Singularity Society” account (Japanese). The repo includes CI badges, stars, and a MANIFEST.md that explains the underlying “AI‑native application” philosophy.

---

In a nutshell: MulmoClaude gives you a self‑hosted, extensible AI assistant that stores all its memories as ordinary files, can be spoken to via a web UI or any messenger you prefer, and keeps your data under your control through optional Docker sandboxing. It’s a full‑stack platform rather than a single‑purpose chatbot, aimed at users who want a personal, privacy‑first AI companion that can also generate tiny custom apps on the fly.