MindGeniusAI

Name: MindGeniusAI
Author: xianjianlf2

Issues

An AI agent that reads your PDFs and draws editable mind maps — visible tool-calling loop, built-in RAG, bring-your-own-key, multi-provider (OpenAI / Claude / DeepSeek / Kimi). Self-hostable.

278stars

59forks

TypeScript

Installation

# Add to your Claude Code skills
git clone https://github.com/xianjianlf2/MindGeniusAI

Getting Started

Guides for using ai agents skills like MindGeniusAI.

Caveman: Cut Claude Token Use by 65%
How agent-side prompt compression works, when to use it, and when not to.
What is an AI Skills Marketplace?
Definitions, how marketplaces work, and how to choose between them in 2026.
Getting Started with AI Skills

Security ReportIssues

Last scanned: 6/11/2026

{
  "issues": [
    {
      "type": "npm-audit",
      "message": "@typescript-eslint/eslint-plugin: Vulnerability found",
      "severity": "high"
    },
    {
      "type": "npm-audit",
      "message": "@typescript-eslint/parser: Vulnerability found",
      "severity": "high"
    },
    {
      "type": "npm-audit",
      "message": "@typescript-eslint/type-utils: Vulnerability found",
      "severity": "high"
    },
    {
      "type": "npm-audit",
      "message": "@typescript-eslint/typescript-estree: Vulnerability found",
      "severity": "high"
    },
    {
      "type": "npm-audit",
      "message": "@typescript-eslint/utils: Vulnerability found",
      "severity": "high"
    },
    {
      "type": "npm-audit",
      "message": "esbuild: esbuild enables any website to send any requests to the development server and read the response",
      "severity": "medium"
    },
    {
      "type": "npm-audit",
      "message": "lint-staged: Vulnerability found",
      "severity": "medium"
    },
    {
      "type": "npm-audit",
      "message": "micromatch: Regular Expression Denial of Service (ReDoS) in micromatch",
      "severity": "medium"
    },
    {
      "type": "npm-audit",
      "message": "minimatch: minimatch has a ReDoS via repeated wildcards with non-matching literal in pattern",
      "severity": "high"
    },
    {
      "type": "npm-audit",
      "message": "vite: Vite Vulnerable to Path Traversal in Optimized Deps `.map` Handling",
      "severity": "medium"
    },
    {
      "type": "npm-audit",
      "message": "vite-node: Vulnerability found",
      "severity": "medium"
    },
    {
      "type": "npm-audit",
      "message": "vitest: When Vitest UI server is listening, arbitrary file can be read and executed",
      "severity": "critical"
    },
    {
      "type": "npm-audit",
      "message": "yaml: yaml is vulnerable to Stack Overflow via deeply nested YAML collections",
      "severity": "medium"
    }
  ],
  "status": "FAILED",
  "scannedAt": "2026-06-11T08:49:18.528Z",
  "npmAuditRan": true,
  "pipAuditRan": true,
  "promptInjectionRan": true
}

README.md

Frequently Asked Questions

What is MindGeniusAI?

MindGeniusAI is an open-source ai agents skill for AI coding assistants such as Claude Code, Codex CLI, and ChatGPT, built by xianjianlf2. An AI agent that reads your PDFs and draws editable mind maps — visible tool-calling loop, built-in RAG, bring-your-own-key, multi-provider (OpenAI / Claude / DeepSeek / Kimi). Self-hostable. It has 278 GitHub stars.

Is MindGeniusAI safe to use?

MindGeniusAI failed SkillsLLM's automated security scan, which flagged one or more high-severity issues. Review the Security Report section carefully before using it.

How do I install MindGeniusAI?

Clone the repository with "git clone https://github.com/xianjianlf2/MindGeniusAI" and add it to your Claude Code skills directory (see the Installation section above).

What programming language is MindGeniusAI written in?

MindGeniusAI is primarily written in TypeScript. It is open-source under xianjianlf2 on GitHub, so you can review or fork the full source.

Are there alternatives to MindGeniusAI?

Yes. SkillsLLM lists many other AI Agents skills you can browse and compare side by side. Open the AI Agents category from the badge at the top of this page, or use the Related Skills and comparison links further down to weigh MindGeniusAI against similar tools.

Agentic AI for Beginners

Build your first AI agent from scratch - tool use, ReAct pattern, memory, deployment

41 minBeginner

Comments (0)

to leave a comment.

No comments yet. Be the first to share your thoughts!

Related Skills

superpowers

by obra

An agentic skills framework & software development methodology that works.

234,966

simp-skill metorial-index

MindGenius AI

A self-hostable AI agent that turns your documents into editable mind maps — your files and API keys never leave your machine.

English · 简体中文

Chat with Hermas, an AI agent that plans, reads your PDFs, and draws editable mind maps live — every tool call visible as it works.

Most AI mind-map tools are cloud SaaS — your documents get uploaded to their servers and your model key lives in their backend. MindGenius runs entirely on infrastructure you control: one Docker image, bring-your-own-key, nothing stored server-side. Built for privacy-conscious knowledge workers, self-hosters, and teams with sensitive documents (legal, research, internal specs) that can't be pasted into a third-party cloud.

🔗 Try the live demo → · bring your own API key (stays in your browser). First load may take ~30s to wake. · ⭐ Star it if it's useful — it helps others find it.

MindGenius AI — Hermas plans, then draws an editable mind map live

🔒 Why MindGenius

	MindGenius	Typical cloud AI mind-map tools
Runs on your own machine	✅ one Docker image	❌ their cloud only
Your documents stay local	✅ never leave your box	❌ uploaded to their servers
Model API key	✅ in your browser only	❌ held in their backend
Bring your own model	✅ OpenAI · Claude · DeepSeek · Kimi · any compatible endpoint	❌ locked to their pick
Real multi-step agent	✅ visible tool calls (plan → retrieve → draw → edit)	❌ one-shot prompt → static tree
Edits the existing map	✅ surgical, by node id	❌ regenerates the whole thing
Source-available & hackable	✅ BSL 1.1, RAG in ~100 lines	❌ closed SaaS

⚡️ Quick Start

pnpm install
pnpm setup     # pick a provider, paste a key → writes apps/server/.env
pnpm dev       # web on :5173, api on :3000

No key at setup? Skip it and paste one later in the app's Settings (top-right) — it stays in your browser only.

✨ Features

🔒 Self-hosted & private — ships as one Docker image you run anywhere; your PDFs are chunked/embedded in memory and your key lives in the browser. Nothing is written to the server's disk, no telemetry on your content.
🤖 Real agent, not a prompt wrapper — multi-step tool loop (Vercel AI SDK v5) that decides when to search docs, generate the map, and expand branches, each shown as a live tool card.
✏️ Surgical edits — "rename the pricing branch" patches exact nodes by id, so your manual tweaks survive (no full re-render).
🤝 Two-way canvas — edit nodes by hand (rename, add, drag, delete) and Hermas sees exactly what you changed on your next message, then builds on it like a collaborator — not just the latest snapshot.
📄 Reads your PDFs — attach one or more PDFs (📎): chunk → embed → in-memory retrieval (~100 lines, no LangChain). rag_query searches across all attached docs at once.
⌨️ Keyboard-first canvas — Tab child · Enter sibling · F2 rename · Del delete · ⌘Z undo · drag a node onto another to re-parent it.
⌘ Command palette (⌘K) — Cursor-style overlay to fuzzy-search your saved maps + uploaded docs; ↵ opens a map or attaches a doc.
🔁 Import / export — import Markdown / OPML, export PNG · SVG · Markdown · OPML · Mermaid.
🔑 Bring your own key — OpenAI / Claude / DeepSeek / Kimi, or any OpenAI-compatible endpoint. Keys never touch the server's disk.
🎨 One focused workbench — chat + canvas + doc drawer; persists across refresh; bilingual (EN / 中文); dark, dependency-free UI.

🔧 Configure

pnpm setup writes apps/server/.env for you. To edit by hand, copy apps/server/.env.example → apps/server/.env.

Provider	Embeddings (RAG)
OpenAI · Claude	✅ full RAG
DeepSeek · Kimi	⚠️ no embeddings — RAG auto-degrades; set `EMBEDDING_API_KEY` to any OpenAI-compatible endpoint to keep it on

🚀 Docker

The whole app ships as one image (server serves the web bundle + API):

docker run -p 3000:3000 -e OPENAI_API_KEY=sk-... ghcr.io/xianjianlf2/mindgeniusai
# open http://localhost:3000

Or build locally: cp apps/server/.env.example apps/server/.env && docker compose up --build.

Omit the key to let each visitor bring their own from Settings. To run a public demo, set a server key and DEMO_DAILY_LIMIT=5 — visitors get a few free runs per day (per IP) before being nudged to add their own key; BYO-key users are never limited.

— free on Hugging Face Spaces (Docker). Keep sdk: docker / app_port: 3000; set OPENAI_API_KEY as a secret or leave it empty.

🗂 Scripts

Command	What it does
`pnpm setup`	first-run config wizard
`pnpm dev`	web + server in parallel
`pnpm build`	typecheck & build all packages
`pnpm test`	run vitest workspace
`pnpm lint`	eslint

🏗 Architecture

apps/web/      React 18 + Vite + Zustand + AntV X6 (custom design system)
apps/server/   Hono + Vercel AI SDK v5 (Hermas agent, RAG, SSE streaming)
packages/shared/  SSE / agent-event protocol shared by both ends

Agent loop — streamText + stopWhen: stepCountIs(8), four zod-typed tools (mindmap_generate / node_expand / rag_query / mindmap_edit).
Live edits — mindmap_edit returns add/update/remove ops applied to the tree by node id.
Two-way sync — your manual canvas ops share that same op model; they're buffered (coalesced) and sent as recentEdits so the agent knows what you changed since its last turn, not just the current outline.
RAG — pdf-parse → overlap chunking → embedMany → cosine retrieval, in-process.
Multi-provider — resolved per request from request headers; keys never stored server-side.

Full design: docs/REFACTOR_PLAN.md.

Analytics (optional)

Cookieless, count-only (page views + an agent_run event) via Umami / GoatCounter / Cloudflare. Never sends chat, PDFs, or keys. See apps/web/.env.example.

License

Business Source License 1.1. Free for personal, academic, research, and non-profit use. Commercial use requires a license — contact mark-xian@foxmail.com. Each version converts to Apache-2.0 four years after release (Change Date: 2030-06-29).