# MindOS > MindOS is a Human-AI Collaborative Mind System, where human thinks and agents act. Globally sync your mind for all agents: transparent, controllable, and evolving symbiotically. - **Type:** MCP server - **Install:** `agentstack add mcp-geminilight-mindos` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [GeminiLight](https://agentstack.voostack.com/s/geminilight) - **Installs:** 0 - **Category:** [Integrations](https://agentstack.voostack.com/c/integrations) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [GeminiLight](https://github.com/GeminiLight) - **Source:** https://github.com/GeminiLight/MindOS - **Website:** https://mindos.you ## Install ```sh agentstack add mcp-geminilight-mindos ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About MindOS Human Thinks Here, Agents Act There. English | 中文 MindOS is where you think, and where your AI agents act — a local-first knowledge base shared between you and every AI you use. **Share your brain with every AI — every thought grows.** --- Home — Knowledge base overview AI Agent — Proactively understand intent and execute tasks from your knowledge Agents — Manage all connected AI agents Echo — Reflect and distill cognitive growth > [!IMPORTANT] > **⭐ One-click install:** Send this to your Agent (Claude Code, Cursor, etc.) to set up everything automatically: > ``` > Help me install MindOS from https://github.com/GeminiLight/MindOS with MCP and Skills. Use English template. > ``` > > **✨ Try it now:** After installation, give these a try: > ``` > Here's my resume, read it and organize my info into MindOS. > ``` > ``` > Help me distill the experience from this conversation into MindOS as a reusable SOP. > ``` > ``` > Help me execute the XXX SOP from MindOS. > ``` ## 📢 What's New | Date | Update | |------|--------| | 2026-04 | **Protocol runtimes internalized** — ACP and MCP source now live under `packages/mindos/src/protocols/*`; the published package ships self-contained `dist/protocols/*` bundles instead of nested protocol packages. | | 2026-04 | **Product main package** — MindOS now follows an OpenCode-style core package: `packages/mindos` (`@geminilight/mindos`) is the product runtime facade and CLI kernel boundary; Web/CLI adapt around it. | | 2026-04 | **OpenCode-style workspace flattening** — all source workspaces now live under `packages/`: `packages/web`, `packages/desktop`, `packages/mobile`, `packages/mindos`, and optional `packages/retrieval/*` adapters. npm tarball, CLI, MCP, Web standalone, Desktop, and Mobile checks have passed. | | 2026-04 | **Clean publish package** — legacy top-level `app/`, `mcp/`, `desktop/`, and `mobile/` source roots are removed; publish entries exclude tests, caches, and nested `node_modules`. | | 2026-04 | **Web Clipper** — Browser extension to clip any web page to your MindOS Inbox with one click. [Get it →](packages/browser-extension/) | | 2026-04 | **PDF & Image Import** — Drag PDFs and images into MindOS, auto-converted to searchable Markdown. | ## 🧠 Human-AI Shared Mind > You shape AI through thinking, AI empowers you through execution. Human and AI, growing together in one shared brain. **1. Global Sync — Breaking Memory Silos** Switch tools or start a new chat and you're re-transporting context, scattering knowledge. **With a built-in MCP server, MindOS connects all Agents to your core knowledge base with zero config. Record profile and project memory once to empower all AI tools.** **2. Transparent & Controllable — No Black Boxes** Agent memory locked in black boxes makes reasoning unauditable, erasing trust as hallucinations compound. **MindOS saves every retrieval, reflection & action as local plain text. You hold absolute mind-correction rights with a full GUI to recalibrate Agents anytime.** **3. Symbiotic Evolution — Experience Flows Back As Instructions** You express preferences but the next chat starts from zero, leaving your thinking useless for AI. **MindOS auto-distills every thought into your knowledge base. Clarify your standards through interaction and sharpen your cognition with each iteration — AI will never repeat the same mistake.** > **Foundation:** Local-first by default — all data stays in local plain text for privacy, ownership, and speed. --- ## 🚀 Getting Started > [!IMPORTANT] > **Quick Start with Agent:** Paste this prompt into any MCP-capable Agent (Claude Code, Cursor, etc.) to install automatically, then skip to [Step 3](#3-inject-your-personal-mind-with-mindos-agent): > ``` > Help me install MindOS from https://github.com/GeminiLight/MindOS with MCP and Skills. Use English template. > ``` > Already have a knowledge base? Skip to [Step 4](#4-make-any-agent-ready-mcp--skills) to configure MCP + Skills. ### 1. Install **Option A: Desktop App (macOS / Windows / Linux)** Download from the [official website](https://tianfuwang.tech/MindOS/#quickstart) or [GitHub Releases](https://github.com/GeminiLight/MindOS/releases/latest) — double-click to install, no terminal needed. **Option B: npm** ```bash npm install -g @geminilight/mindos@latest ``` **Option C: Clone from source** ```bash git clone https://github.com/GeminiLight/MindOS cd MindOS pnpm install pnpm --filter @geminilight/mindos build cd packages/mindos pnpm link --global # registers the `mindos` command globally ``` The npm package intentionally installs both the CLI and the prebuilt local Web runtime. `mindos` is the command entrypoint, while `_standalone/` provides the browser UI used by `mindos start` / `mindos open`; Web source (`packages/web`), tests, wiki, legacy source roots, and dev caches are excluded from the tarball. ### 2. Interactive Setup ```bash mindos onboard ``` The setup wizard guides you through knowledge base path, template, ports, auth, AI provider, and start mode — all with sensible defaults. Config is saved to `~/.mindos/config.json`. See **[docs/en/configuration.md](docs/en/configuration.md)** for all fields. > [!TIP] > On macOS/Linux, choose "Background service" during onboard for auto-start on boot. On Windows CLI installs, use foreground mode; Windows auto-start is handled by the Desktop app. Run `mindos update` anytime to upgrade. Open the Web UI in your browser: ```bash mindos open ``` ### 3. Inject Your Personal Mind with MindOS Agent 1. Open the built-in MindOS Agent chat panel in the GUI. 2. Upload your resume or any personal/project material. 3. Send this prompt: `Help me sync this information into my MindOS knowledge base.` ### 4. Make Any Agent Ready (MCP + Skills) **MCP** (connection) — one command to auto-install: ```bash mindos mcp install # interactive mindos mcp install -g -y # one-shot, global scope ``` **Skills** (workflow) — install one based on your language: ```bash npx skills add https://github.com/GeminiLight/MindOS --skill mindos -g -y # English npx skills add https://github.com/GeminiLight/MindOS --skill mindos-zh -g -y # Chinese ``` > For remote access, manual JSON config, and common pitfalls, see **[docs/en/supported-agents.md](docs/en/supported-agents.md)**. ### 5. Capture from Anywhere MindOS knowledge doesn't have to start from scratch — bring in what you already have: - **Drag & Drop**: drop files (PDF, images, Markdown, CSV) into the MindOS GUI — AI auto-organizes them into the right folders. - **Web Clipper**: install the [browser extension](packages/browser-extension/) to save any web page to your Inbox with one click. Ctrl+Shift+M or right-click → "Save to MindOS". - **Agent Import**: tell any connected Agent to read a document and sync it into your knowledge base. ## ✨ Features **For Humans** - **GUI Workbench**: browse, edit, search notes with unified search + AI entry (`⌘K` / `⌘/`), designed for human-AI co-creation. - **Built-in Agent Assistant**: converse with the knowledge base in context; edits seamlessly capture human-curated knowledge. - **One-Click Import**: drag-and-drop files with Inline AI Organize — auto-analyzes, categorizes, and writes into the knowledge base with progress tracking and undo support. - **Guided Onboarding**: step-by-step first-run experience that helps new users set up their knowledge base and connect their first Agent. - **Plugin Extensions**: multiple built-in renderer plugins — TODO Board, CSV Views, Wiki Graph, Timeline, Workflow Editor, Agent Inspector, and more. - **Web Clipper**: browser extension to clip any web page as clean Markdown — one click, saves to Inbox for later AI-powered organizing. [Install →](packages/browser-extension/) **For Agents** - **MCP Server + Skills**: stdio + HTTP dual transport, full-lineup Agent compatible (Claude Code, Cursor, Gemini CLI, etc.). Zero-config access. - **ACP / A2A Protocols**: Agent communication protocols for discovery, delegation, and orchestration. Phase 1 is live with Agent Card discovery + JSON-RPC messaging. - **Workflow Orchestration**: YAML-based workflow editor with step execution engine — define, edit, and run multi-step agent workflows visually. - **Structured Templates**: pre-set directory structures for Profiles, Workflows, Configurations, etc., to jumpstart personal context. - **Agent-Ready Docs**: everyday notes naturally double as high-quality executable Agent commands — no format conversion needed, write and dispatch. **Infrastructure** - **Security**: Bearer Token auth, path sandboxing, INSTRUCTION.md write-protection, atomic writes. - **Knowledge Graph**: dynamically parses and visualizes inter-file references and dependencies. - **Backlinks View**: displays all files that reference the current file, helping you understand how a note fits into the knowledge network. - **Agent Inspector**: renders Agent operation logs as a filterable timeline to audit every tool call in detail. - **Git Time Machine**: Git auto-sync (commit/push/pull), records every edit by both humans and Agents. One-click rollback, cross-device sync. - **Desktop App**: native macOS/Windows/Linux app with system tray, auto-start, and local process management. Coming Soon - [ ] Deep RAG integration: retrieval-augmented generation grounded in your knowledge base for more accurate, context-aware AI responses - [ ] ACP / A2A Phase 2: deep multi-agent collaboration with task delegation, shared context, and workflow chaining - [ ] Experience Compiler: auto-extract corrections and preferences from agent interactions into reusable Skills/SOPs - [ ] Knowledge Health Dashboard: visualize cognitive compound metrics — rules accumulated, agent reuse count, knowledge freshness ## ⚙️ How It Works ```mermaid graph LR H["👤 Humanthinks · reviews · evolves"] M[("📚 MindOS")] A["🤖 Agentexecutes · retrospects · extracts SOPs"] EXT["🌐 All Agents"] H -- "ideas & feedback" --> M M -- "context & insights" --> H M -- "instructions & context" --> A A -- "results & SOPs" --> M M -. "via MCP" .-> EXT style H fill:#f59e0b,stroke:#d97706,color:#fff,stroke-width:2px style M fill:#10b981,stroke:#059669,color:#fff,stroke-width:2px style A fill:#6366f1,stroke:#4f46e5,color:#fff,stroke-width:2px style EXT fill:#64748b,stroke:#475569,color:#fff,stroke-dasharray:5 5 ``` > **Both sides evolve.** Humans gain new insights from accumulated knowledge; Agents extract SOPs and get smarter. MindOS sits at the center — the shared second brain that grows with every interaction. --- ## 🤝 Supported Agents > The current registry supports 26 Agents. Full list with MCP config paths and manual setup: **[docs/en/supported-agents.md](docs/en/supported-agents.md)** | Agent | MCP | Skills | |:------|:---:|:------:| | OpenClaw | ✅ | ✅ | | Claude Code | ✅ | ✅ | | Cursor | ✅ | ✅ | | Codex | ✅ | ✅ | | Gemini CLI | ✅ | ✅ | | GitHub Copilot | ✅ | ✅ | | Trae | ✅ | ✅ | | CodeBuddy | ✅ | ✅ | | Qoder | ✅ | ✅ | | Cline | ✅ | ✅ | | Windsurf | ✅ | ✅ | | Hermes | ✅ | - | --- ## 📁 Project Structure ```bash MindOS/ ├── packages/web/ # Next.js 16 frontend — browse, edit, and interact with AI ├── packages/desktop/ # Electron desktop client ├── packages/mobile/ # Expo mobile app ├── packages/browser-extension/ # Web Clipper browser extension ├── packages/desktop-tauri/ # Tauri desktop spike ├── packages/mindos/ # Published product package: runtime facade, protocols, foundation/knowledge internals, CLI kernel ├── packages/retrieval/ # Optional retrieval stack: search, vector, indexer, API ├── skills/ # MindOS Skills (`mindos`, `mindos-zh`) — workflow guides for Agents ├── templates/ # Preset templates (`en/`, `zh/`, `empty/`) — copied to knowledge base on onboard ├── scripts/ # Setup wizard and helper scripts └── README.md ~/.mindos/ # User data directory (outside project, never committed) ├── config.json # All configuration (AI keys, port, auth token, sync settings) ├── sync-state.json # Sync state (last sync time, conflicts) └── mind/ # Your private knowledge base (default path, customizable on onboard) ``` > In v1, top-level `app/`, `apps/`, `mcp/`, `desktop/`, `mobile/`, `browser-extension/`, `desktop-tauri/`, and root `bin/` are no longer source roots. The repo root is a private monorepo orchestrator. `packages/mindos` is the OpenCode-style published product package (`@geminilight/mindos`): its repo CLI entry is `packages/mindos/bin/cli.js`, installed npm users still receive the package-relative `bin/cli.js`, and the prebuilt local Web runtime is published as `_standalone/`. `packages/web` remains the only Web source tree and is not copied into the npm tarball. During `npm pack` / publish, `packages/mindos/_standalone`, `packages/mindos/packages`, `packages/mindos/scripts`, `packages/mindos/assets`, `packages/mindos/skills`, and `packages/mindos/templates` may be generated as staging output; they are ignored, excluded from pnpm workspace discovery, and cleaned by `pnpm run clean:product-stage` or product `postpack`. ## ⌨️ CLI Commands > Full command reference: **[docs/en/cli-commands.md](docs/en/cli-commands.md)** | Command | Description | | :--- | :--- | | **Core** | | | `mindos onboard` | Interactive setup (config, template, start mode) | | `mindos start` | Start Web + MCP services | | `mindos start --daemon` | Start as background OS service (macOS/Linux only) | | `mindos stop` / `restart` | Stop or restart running processes | | `mindos dev` | Start in dev mode | | `mindos build` | Build for production | | `mindos status` | Show service status overview | | `mindos open` | Open Web UI in browser | | **Knowledge** | | | `mindos file ` | File operations (list, read, create, delete, search) | | `mindos space ` | Space management (list, create, info) | | `mindos search ""` | Search knowledge base | | `mindos` | Open the MindOS AI Agent REPL | | `mindos ""` / `mindos -p ""` | Run the MindOS AI Agent with your knowledge base | | `mindos agent ` | Explicit agent command and management (list, info) | | `mindos channel` / `mindos feishu-ws` | IM channel config and Feishu long connection | | `mindos api ` | Raw API passthrough for developers/agents | | **MCP & Config** | | | `mindos mcp install` | Auto-install MCP config into your Agent | | `mindos token` | Show auth token and MCP config | | `mindos config ` | View/update config (show, set, validate) | | `mindos sync` | Show sync status (init, now, conflicts, on/off) | | `mindos gateway ` | Manage background service on macOS/Linux (install, start, stop) | | `mindos doctor` | Health check | | `mindos update` | Update to latest version | **Main keyboard shortcuts:** `⌘K` Search · `⌘/` AI Assistant · `E` Edit · `⌘S` Save · `Esc` Close. --- ## 💬 Community Join our WeChat group for early access, feedback, and AI workflow discussions: > Scan the QR code or add WeChat **wtfly2018** to be invited. --- ## 👥 Contributors ### 🙏 Acknowledgements This project has been published on the [LINUX DO community](https://linux.do), and we deeply appreciate the community's support and feedback. --- ## 📄 License MIT © GeminiLight ## Source & license This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [GeminiLight](https://github.com/GeminiLight) - **Source:** [GeminiLight/MindOS](https://github.com/GeminiLight/MindOS) - **License:** MIT - **Homepage:** https://mindos.you Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-geminilight-mindos - Seller: https://agentstack.voostack.com/s/geminilight - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.