@monoes/monomindcli

Monomind

An open-source MCP server that extends Claude Code with a codebase knowledge graph, persistent memory, and multi-agent coordination.
Apache 2.0 licensed · Monomind keeps its own state on your machine; the AI tools it drives send prompts and code to their model providers — see [Trust & Security](#trust--security)

🏢 Orgs  ·  🚀 Quickstart  ·  ⚡ Mastermind  ·  🧩 Agents & Skills  ·  📋 Commands  ·  🏗️ Architecture

What is Monomind?

Monomind is an open-source CLI and MCP server that plugs into Claude Code, OpenCode, Antigravity, Kimi Code, and Codex via the standard Model Context Protocol. It adds capabilities these assistants don't ship with out of the box:

• Codebase knowledge graph — tree-sitter parses your code into a SQLite-backed graph of files, functions, classes, and their relationships. Query imports, callers, and blast radius before making changes.
• Persistent memory — a JSON pattern store with episodic recall that survives across sessions. Agents and orgs share context without re-prompting.
• Multi-agent coordination — in-session, spawn ad-hoc agent teams via Claude Code's Task tool; for persistent background work, monomind org run starts a real SDK-backed daemon with policy-gated role agents and a live dashboard.
• Agents, skills and picking — ships 84 pickable agents, 83 skills and 376 Org skills, and you add your own as Markdown files. One index of all of them ranks the best fit for each task; the prompt hook puts it in Claude's context as a [PICK] line, and monomind pick or the pick MCP tool return it on request. See Agents & Skills and Routing.
• Reusable slash commands — 42 workflows (plan, execute, review, debug, release, research, worktree) available as /mastermind:* commands inside Claude Code.

npm install -g monomind        # Apache 2.0 licensed; runs locally and keeps its state locally
cd your-project && monomind init
claude mcp add monomind -- npx -y monomind@latest mcp start

monomind init installs the core pack: the everyday /mastermind:* workflows (plan, execute, review, debug, do, …), 20 core agents and the memory, GitHub and browser toolkits, small enough that Claude Code shows every description. Everything else ships as opt-in packs (orgs, org-admin, swarm, github, testing, specialists, business, extras): pick them with monomind init --packs orgs,github or --all-packs, or add one later with monomind packs add <pack>. monomind packs list shows each pack and how much of the listing it uses.

monomind init sets up only the coding systems installed on your machine: Claude Code, Antigravity, OpenCode, Kimi Code and Codex each count when their CLI is on your PATH or their config directory is in your home, and Claude Code is the default when none is found. A re-run also keeps every system the project already has. It prints what it detected; --platforms claude,codex names the systems yourself and --all-platforms writes all five. It never runs npm install or edits your package.json: the code graph uses the @monoes/monograph copy bundled with the CLI.

monomind init itself writes .mcp.json (and the configs of the other coding systems it sets up) pinned to the installed version, so a start reuses the npx cache instead of re-resolving @latest; --pin latest keeps the floating monomind@latest, and monomind init --force re-pins after an upgrade.

Using Antigravity (agy)?

Nothing extra to do when Antigravity is installed (agy/gemini on PATH or ~/.gemini): monomind init then writes GEMINI.md, .gemini/rules/, and a live status bar wired through .gemini/settings.json. The MCP server config is shared with Claude Code (.mcp.json). See Antigravity guide →.

Using opencode instead?

monomind init --target opencode # initialize only OpenCode

monomind init sets up the coding systems it detects on your machine (CLI on PATH or config directory in your home), OpenCode included when it is installed. --target opencode initializes only OpenCode; the legacy --opencode flag remains an alias. You get the same MCP tools, agent roster, commands, skills, and security gates, plus a /monomind-status command. See OpenCode guide →.

Using Kimi Code instead?

monomind init --target kimicode # initialize only Kimi Code

monomind init includes Kimi Code when it is installed (kimi on PATH or ~/.kimi). --target kimicode initializes only Kimi Code; the legacy --kimicode flag remains an alias. You get the same MCP tools, agent roster, skills, and commands (as project-level flow skills). Install the generated plugin once for /monomind:* slash commands and security gates: /plugins install ./.kimi-code/plugin. See Kimi Code guide →.

Using Codex?

codex login
monomind init --codex

This emits a project-scoped .codex/config.toml that registers Monomind's MCP server, plus AGENTS.md with Codex-specific guidance. Codex must trust the project before it loads project-scoped configuration. To run persistent Monomind organizations through Codex, set "runtime": "codex" in the org definition.

Plain monomind init sets up only the coding systems installed on your machine (Codex when codex is on PATH or ~/.codex exists), and Claude Code when it finds none; --all-platforms sets up all five and --platforms claude,codex names them. Init never runs npm install in your project. Use monomind init --target codex (or --codex) to initialize only Codex. See Codex guide →.

Trust & Security

Concern	Answer
License	Apache 2.0 — use it however you want
Data privacy	Monomind runs locally and stores its state locally: memory, code graph, document index and org state, embedded by a local model. The AI tools it drives (Claude Code, Codex, OpenCode, Kimi Code, Antigravity, and org roles, whose model calls monomind makes itself when a role uses an AI-SDK provider) send your prompts and code to their model providers, including the memory and Second Brain excerpts injected into those prompts. Monomind itself also makes a few outbound calls: the one-time embedding model download, the first-use installs of the Claude SDK and (without an installed browser) Chrome, the npm update check, and opt-in features; launching it through npx monomind@latest adds an npm registry lookup on every start, and opening the dashboard loads its scripts and fonts from public CDNs. See doc/privacy.md for the complete list of what's sent, when, and how to opt out of each.
Dependencies	Standard npm packages. A fresh npm install monomind (Linux x64) adds 263 packages and 938 MB of node_modules, most of it onnxruntime-node (548 MB, local embeddings) and onnxruntime-web (141 MB). Four packages run install scripts, and two of them download binaries: onnxruntime-node (CUDA libraries from NuGet on Linux x64; ONNXRUNTIME_NODE_INSTALL=skip skips them) and better-sqlite3 (a prebuilt addon from GitHub). Two heavy pieces are installed on first use instead, once, into ~/.monomind/deps and never into your project: the Claude Agent SDK with its Claude binary (about 300 MB, on the first Claude org role or agent exec --runtime claude), and Chrome for monomind browse (about 400 MB, only when no Chrome, Chromium or Edge is installed). MONOMIND_NO_AUTO_INSTALL=1 turns that off and prints the install command instead. Native addons: better-sqlite3 and onnxruntime-node; tree-sitter (web-tree-sitter) and sql.js are WASM. Full breakdown: doc/privacy.md.
Permissions	Registers as an MCP server — Claude Code controls what tools are available and prompts you before executing anything sensitive.
Source	Fully open. Read every line at github.com/monoes/monomind.
Maintenance	Active development, regular releases on npm.

🏢 Autonomous Organizations

This is the headline feature. monomind org run starts a persistent, SDK-backed daemon that runs an autonomous agent organization — roles, hierarchy, policy-gated tool access, a live dashboard — until you stop it.

The idea

Every business function needs a team. Define the org once as a JSON file — goal, roles, who reports to whom, per-role tool/file/budget policy — then run it as a real background daemon backed by the Claude Agent SDK. It persists across sessions, streams live into the dashboard Claude Code auto-starts for the project, and can discover and message other Monomind orgs running on the same machine.

flowchart TD
    U(["You"])
    DEF["org.json\nGoal + roles + policy"]
    RUN["monomind org run\nStart SDK daemon"]
    BOSS["Boss Agent\nAgent SDK session"]
    W["Writer"]
    S["SEO Specialist"]
    R["Reviewer"]
    DASH[("Dashboard\n:4242\nauto-started by\nClaude Code hook")]
    XORG[("Other orgs\ncross-process")]

    U --> DEF --> RUN --> BOSS
    BOSS -->|spawns| W
    BOSS -->|spawns| S
    BOSS -->|spawns| R
    RUN -->|forwards events| DASH
    RUN <-.->|--cross-process| XORG

    style BOSS fill:#00D2AA22,stroke:#00D2AA
    style DASH fill:#F59E0B22,stroke:#F59E0B
    style XORG fill:#8B5CF622,stroke:#8B5CF6

Run one

# .monomind/orgs/<name>.json defines the org: goal, roles, policy.
# See .monomind/orgs/sample-team.json in a fresh `monomind init` for a working example.
# Open the project in Claude Code first — a SessionStart hook auto-launches
# the dashboard at http://localhost:4242 if it isn't already running.

monomind org run content-team --task "Build and publish 3 blog posts per week"

# ✓ Boss agent (Claude Agent SDK session) spawns, reads the org goal,
#   assigns work to role agents, coordinates until the task completes
#   or you stop it. Every event streams into the dashboard above.

monomind org status content-team    # runtime state (detects crashed daemons)
monomind org stop content-team      # request a graceful stop
monomind org list                   # every org + roles, schedule, status

Observe, steer, and carry context between runs

monomind org logs content-team --follow      # live event stream in the terminal
monomind org report content-team             # outcome, per-role tokens vs budget, assets
monomind org questions content-team          # what agents asked via ask_human
monomind org answer content-team q-123 "yes" # answer live or queued — no dashboard needed
monomind org create blog --template content-team --goal "3 posts/week"   # scaffold from a template
monomind org validate blog                   # schema + structural checks before running
monomind org run blog --dry-run              # preview each role's exact briefing

Orgs carry context between runs: the coordinator records every run's outcome (org_complete), the next run is briefed on it, and all agents can query accumulated cross-run memory with org_recall — a scheduled org starts each cycle with what earlier cycles recorded instead of starting cold. Crashed agent sessions restart automatically with backoff.

What runs under the hood

What	How
OrgDaemon	Hosts one or more orgs in a single process; real Claude Agent SDK sessions per role, not simulated
PolicyEngine	Per-role gates on tool access, file read/write scope, web access, token budget — enforced, with a full audit trail
Dashboard	org run forwards every event to the control server on :4242 (found via .monomind/control.json) — that server is auto-launched by a Claude Code SessionStart hook, not by any CLI command; there's no separate per-org dashboard process
Cross-process comms	--cross-process (default on) lets orgs on different monomind processes/projects discover and message each other
Scheduling	monomind org serve hosts orgs whose definition has a schedule field, running them on interval

Org management commands

monomind org run <name> [--task "..."] [--cross-process]  # start a daemon
monomind org stop <name>            # request a running org to stop
monomind org status [name]          # runtime state for one or all orgs
monomind org list                   # list every org + status
monomind org serve [--cross-process]  # host-only mode, runs scheduled orgs
monomind org delete <name>          # remove an org
monomind org memory <name>          # cross-run KG memory: stats (default) | search <q> | rules | rollback <run-ref>

org has 39 subcommands total (skills, run, stop, pause, resume, reload, status, serve, supervisor, test-loop, logs, events, watch, report, memory, costs, inbox, flow, questions, approvals, answer, approve, deny, gates, gate-approve, gate-reject, replay, resume-from, branch, decisions, create, validate, migrate, list, delete, mark-complete, role, sign, approve-paths).

Note: /mastermind:runorg delegates directly to the Org Runtime daemon (the same path as monomind org run) — there is no boss agent, no monotask board, and no manual curl calls in this path. /mastermind:runorg converts legacy-format org config files with monomind org migrate before starting the daemon. New orgs should use monomind org run (or /mastermind:runorg) against a hand-authored .monomind/orgs/<name>.json.

⚡ Looping Workflows

For code, the /mastermind:* workflows can loop instead of running once. Add --tillend to /mastermind:review, /mastermind:improve, /mastermind:debug and most other workflows (/mastermind:help lists them) to repeat until a round finds nothing left to do.

/mastermind:review --tillend                     # review → fix → verify until a round finds nothing
/mastermind:improve --repeat 3 the auth flow     # exactly 3 improvement passes
/mastermind:plan add rate limiting               # then /mastermind:execute the plan

Loop flags

Flag	Purpose
--tillend	Repeat until an empty round (zero findings, zero actions)
--repeat <N>	Repeat exactly N times
--maxruns <N>	Safety cap for --tillend (default 50)
--wait <seconds>	Pause between runs

🚀 Quickstart

# 1. Install
npm install -g monomind

# 2. Initialize in your project
cd your-project
monomind init

# 3. Wire into Claude Code as an MCP server
claude mcp add monomind -- npx -y monomind@latest mcp start

# 4. Health check
monomind doctor --fix

Semantic routing (opt-in download): embedding-based task routing needs a local model (~88 MB, Snowflake/snowflake-arctic-embed-xs via transformers.js). monomind init asks interactively whether to download it — the default is No, and non-interactive/CI installs never download it silently. Declining is fine: agent picking (monomind pick, the [PICK] hook line, hooks route) never needs the model; only route semantic, hooks_route_semantic and agent spawn --task use it, after the picker, and fall back to keyword and hash matching without it. Fetch it any time with monomind download-embeddings (or node scripts/download-embedding-model.mjs on a source checkout).

Native module install blocked? If doctor reports a missing better-sqlite3 binding (Could not locate the bindings file, or npm logs an install script that was "blocked because it is not covered by allowScripts"), your npm's allowScripts policy blocked its native build — this isn't a Monomind bug. Run npm install-scripts approve better-sqlite3 && npm rebuild better-sqlite3, then re-run monomind doctor --fix.

Open Claude Code. The core /mastermind:* workflows are available (all 42 come with monomind packs add or init --all-packs):

/mastermind:review --tillend      # review and fix until nothing is left
monomind org run sample-team      # run your first AI org (init writes a runnable sample-team.json — edit it, or run it as-is)
/mastermind:help                  # show all commands

📚 Second Brain — Your Documents, Retrieved by Meaning

Drop documents (Markdown, TXT, PDF, DOCX) anywhere in your project and run monomind init — the Second Brain activates itself. No flags, no configuration, no accounts. Indexing and search run on your machine: a local embedding model (Alibaba-NLP/gte-modernbert-base, 768-dim, via transformers.js) and a local SQLite vector store. Your notes are indexed and stored locally — but the excerpts search returns are injected into your AI tool's prompts, and go to its model provider with the rest of the prompt.

From then on, every substantive prompt you type in Claude Code is automatically answered with your own knowledge in context — a hook retrieves the most relevant excerpts semantically (the always-on dashboard keeps the model warm, ~60ms per lookup) and injects them before Claude starts thinking. Ask "when do new parents get time off" and the parental-leave section of your handbook is already on the table, even though you never used the word "leave".

monomind doc ingest ./notes        # index documents (init + session-start do this automatically)
monomind doc search -q "pricing psychology in checkout"   # semantic search, by meaning not keywords
monomind doc list                  # what's indexed
monomind doc export                # portable OKF bundle — move your brain between machines

Optional spreadsheet support: monomind init never downloads SheetJS. To extract .xlsx, .xls, or .ods files, install it only when you need it: run pnpm add xlsx in a project using a local/npx Monomind install, or npm install -g xlsx when Monomind is installed globally. Until then, spreadsheet files are skipped while the rest of document ingestion continues.

And it follows you across projects. Ingest a path from outside the current project (monomind doc ingest ~/notes, or add --global) and it lands in your personal global brain at ~/.monomind/global-brain (override with MONOMIND_GLOBAL_BRAIN_DIR) — kept as a sibling of ~/.monomind/projects specifically so monomind cleanup --data can never prune it — searchable from every project on the machine. All retrieval (CLI search, per-prompt injection, the dashboard) merges both stores automatically, with project knowledge winning ties and global hits labeled [global]. doc export --global moves your whole brain between machines as an OKF bundle — a file you move yourself, with no cloud service involved.

Retrieval quality is a tested invariant, not a hope: a golden-set eval (paraphrase queries against notes written in different vocabulary) runs in CI with an 80% recall bar.

Privacy note: the embedding model (~90MB) is fetched once from HuggingFace's CDN when your first document is indexed, then cached locally forever. That download is the only outbound request the Second Brain's indexing and search make — your documents and queries are processed locally. Excerpts injected into a prompt are a different matter: they go to your AI tool's model provider with that prompt. Offline at first index? Search degrades gracefully to keyword matching and monomind doctor tells you how to warm up later.

Which model where? Monomind uses two local embedding models. Snowflake/snowflake-arctic-embed-xs (~88MB) serves semantic task routing only. Everything the memory bridge embeds — both the Second Brain document index and the persistent memory store, which share that one bridge — uses Alibaba-NLP/gte-modernbert-base (768-dim, ~90MB); there is no separate document model. See Embeddings for the per-subsystem detail.

🧠 Memory That Persists

Every session, every agent, every org writes to a persistent memory store that survives across sessions — text plus embedding vectors in local SQLite (better-sqlite3, pure-WASM fallback), embedded by a local model. No cloud vector database and no API keys; the store itself uploads nothing. Entries recalled into a prompt go to your AI tool's model provider with that prompt. The next time you run anything, the store holds what earlier sessions recorded about what was built, what failed, and which patterns worked.

graph TD
    L0["L0 - In-flight\nCurrent session drawers\nephemeral"]
    L1["L1 - Working\nCross-session memory\nBM25 K1=1.5, B=0.75"]
    L2["L2 - Long-term\nEpisodic store\nSemantic recall"]
    L3["L3 - Shared\nCross-agent namespace\nFederated swarm reads"]

    L0 -->|promoted| L1 --> L2 --> L3

    style L0 fill:#00D2AA11,stroke:#00D2AA
    style L1 fill:#F59E0B11,stroke:#F59E0B
    style L2 fill:#8B5CF611,stroke:#8B5CF6
    style L3 fill:#EF444411,stroke:#EF4444

monomind memory store --key "key insight" --value "…" --namespace my-project
monomind memory search "auth implementation"     # semantic (local embeddings) with keyword fallback

🗺️ Monograph — Your Codebase, as a Graph

Before touching any file, Monomind queries Monograph — a SQLite-backed knowledge graph of your entire codebase. Nodes are files, classes, and functions. Edges are imports, calls, and dependencies.

/mastermind:understand          # build the graph
/mastermind:graph-status        # nodes · edges · freshness

# Inside Claude Code, Monograph runs automatically:
# → "what files does auth.ts import?"
# → "what breaks if I change UserService?"
# → "find all callers of validateToken()"

19 default MCP tools (+27 advanced via MONOGRAPH_MCP_ADVANCED=1). Impact analysis. Community detection. Zero grep.

🎣 Hooks & Workers

Monomind wires 28 hook subcommands into Claude Code across edit, task, command, and session lifecycle events — logging edits and outcomes to local pattern files and picking agents.

flowchart LR
    CE["Claude Code\nEvent"] --> H["Hook Router"]
    H --> P["pre-edit\npre-task\npre-command"]
    H --> SS["session-start\nsession-end\nnotify"]
    H --> I["route\nlog outcomes"]
    H --> T["teammate-idle\ntask-completed"]

    I --> DB[("patterns.json\nmemory store")]
    DB -->|next session| CE

9 on-demand workers run at session start (staleness-gated, refreshed when older than 6 hours): health · ddd · security · cache · progress · map · audit · consolidate · reflexion.

🛡️ MonoFence AI — Security Layer

Every agent boundary is defended by monofence-ai — real-time detection of prompt injection, jailbreaks, homoglyphs, base64 evasion, multi-turn escalation, and PII leakage.

import { isSafe, createMonoDefence } from 'monofence-ai';

isSafe('Ignore all previous instructions');  // → false (~0.04ms)

const fence = createMonoDefence({ enableContextTracking: true });
const result = await fence.detect(userInput);
// result.safe · result.threats · result.overallRisk

In Claude Code, the live pre-bash/pre-write gate is wired up via its own lazy-loaded integration in .claude/helpers/handlers/gates-handler.cjs (MONOMIND_MONOFENCE_GATE=off to disable) — not via monofence-ai's registerSecurityHooks() API, which is a separate integration point consumed only by @monoes/hooks' in-process HookExecutor.

📋 42 Mastermind Commands

Everything runs from inside Claude Code via slash commands. Here's the highlight reel:

Development

Command	What it does
/mastermind:plan	Comprehensive implementation plan
/mastermind:execute	Execute a written plan step by step, then hand off to review
/mastermind:review	Iterative review until zero findings
/mastermind:debug	Systematic root-cause debugging
/mastermind:improve	Analyze a component and write improvement tasks
/mastermind:release	Versioning, changelog, deployment coordination
/mastermind:worktree	Feature work in isolated git worktree

Organizations

Command	What it does
monomind org run <name>	Start an org as a real SDK-backed daemon
monomind org status / list	Runtime state for one or all orgs
monomind org stop <name>	Request a graceful stop
monomind org approve <name> / deny	Act on pending approval requests

Business Domains

Command	What it does
/mastermind:marketing	Campaigns, copy, SEO, social
/mastermind:content	Blog posts, threads, newsletters
/mastermind:sales	Outreach, proposals, pipeline
/mastermind:finance	Budgets, invoicing, modeling
/mastermind:ops	Operations and workflow automation

→ Full reference (42 commands)

📦 Packages

Package	npm	Purpose
monomind		Umbrella shim — install this one
@monoes/monomindcli		CLI engine (39 commands, MCP server)
@monoes/monograph		Code knowledge graph (tree-sitter + SQLite)
@monoes/memory		Persistent memory backends (SQLite + vectors)
@monoes/hooks		Hook registry + 9 on-demand workers
@monoes/mcp		MCP server framework (stdio/HTTP/WebSocket)
@monoes/routing		Semantic task-to-agent routing
@monoes/monobrowse		Browser automation via CDP
@monoes/monodesign		Frontend design intelligence
monofence-ai		AI manipulation defence

See CLI Reference for the full 39-command index.

🏗️ How It's Built

graph TD
    CC["Claude Code"]
    MCP["MCP Server\nmonomind mcp start"]
    D["Background Workers\n(@monoes/hooks, in-process)"]
    ORG["OrgDaemon\nmonomind org run\nreal SDK sessions"]

    CC <-->|"MCP tools: monograph, memory"| MCP
    MCP <--> D

    D --> ADB[("Memory store\npatterns + episodes")]
    D --> MG[("Monograph\ncode graph")]
    D --> HK["Hooks\n28 subcommands"]

    CC -->|"Task tool - spawns agents"| AG["In-session agents\narchitect, coder\ntester, reviewer\nsecurity, perf"]
    AG <-->|reads and writes| ADB
    ORG -->|"spawns, policy-gated"| RA["Role agents"]
    ORG <-->|reads and writes| ADB

    style CC fill:#00D2AA22,stroke:#00D2AA
    style AG fill:#8B5CF622,stroke:#8B5CF6
    style ADB fill:#F59E0B22,stroke:#F59E0B
    style ORG fill:#F59E0B22,stroke:#F59E0B

Claude Code's Task tool drives in-session multi-agent work; monomind org run drives persistent background orgs. Monomind keeps its own state on your machine; the AI tools it drives send prompts and code to their model providers — see Trust & Security.

Resources

• 📖 Full Documentation
• 🖥️ CLI Command Reference
• 🏢 Org Runtime Architecture
• 🏢 Autonomous Orgs
• ⚡ Mastermind Reference
• 📋 All Slash Commands
• 🐛 Issues
• 💬 Discussions

_{Built with ♥ by monoes · Apache 2.0 License}