Monomind
An open-source MCP server that extends Claude Code with a codebase knowledge graph, persistent memory, and multi-agent coordination.
MIT licensed · Fully local · No data leaves your machine
π’ Orgs Β·
π Quickstart Β·
β‘ Mastermind Β·
π Commands Β·
ποΈ Architecture
---
## What is Monomind?
Monomind is an **open-source CLI and MCP server** that plugs into Claude Code via the standard [Model Context Protocol](https://modelcontextprotocol.io/). It adds capabilities that Claude Code doesn'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.
- **Reusable slash commands** β 30+ development workflows (build, review, debug, TDD, architecture) available as `/mastermind:*` commands inside Claude Code.
```bash
npm install -g monomind # MIT licensed, runs entirely on your machine
cd your-project && monomind init
claude mcp add monomind -- npx -y monomind@latest mcp start
```
### Trust & Security
| Concern | Answer |
|---|---|
| **License** | [MIT](LICENSE) β use it however you want |
| **Data privacy** | Everything runs locally β your code and memory store never leave your machine. The one exception: crash reporting is on by default (`monomind crash-reporting disable` to opt out) β a hard crash in monomind/mono-agent/monotask/mono-clip files a GitHub issue on that tool's own repo via the GitHub API. That's the only network call Monomind itself makes; it never phones a monoes-controlled server. |
| **Dependencies** | Standard npm packages (tree-sitter, better-sqlite3, sql.js, zod). tree-sitter and better-sqlite3 are native (prebuilt) Node addons, not pure JS/WASM β sql.js is WASM. No post-install scripts that download code. |
| **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](https://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.
```mermaid
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
```bash
# .monomind/orgs/.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
monomind org stop content-team # request a graceful stop
monomind org list # every org + status
```
### 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
```bash
monomind org run [--task "..."] [--cross-process] # start a daemon
monomind org stop # 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 # remove an org
```
> **Note:** the older `/mastermind:createorg` + `/mastermind:runorg` prompt-orchestrated flow is deprecated β it has no delivery guarantees or ground-truth event stream. It still runs for orgs not yet migrated, but new orgs should use `monomind org run` directly against a hand-authored `.monomind/orgs/.json`.
---
## β‘ The Autonomous Build Loop
For code, `/mastermind:autodev` is the equivalent of Orgs β a loop that researches, builds, and reviews your codebase without stopping.
```mermaid
flowchart LR
R["Research\nParallel scan:\ngit log, files\nTODOs, graph\nmemory"] --> S
S["Select\nFeasibility x\nblast-radius x\nfocus"] --> B
B["Build\nArchitect\nCoder\nTester\nReviewer"] --> V
V["Review Loop\nCode + Security\n+ Reality\nmax 5 iterations"] --> L
L["Log + Loop\nStore to memory\n--tillend:\nschedule next"]
L -->|"more to do"| R
style R fill:#00D2AA22,stroke:#00D2AA
style B fill:#8B5CF622,stroke:#8B5CF6
style V fill:#F59E0B22,stroke:#F59E0B
style L fill:#10B98122,stroke:#10B981
```
```bash
/mastermind:autodev --tillend # loop until nothing left
/mastermind:autodev --tillend --focus security # bias toward security fixes
/mastermind:autodev 3 # exactly 3 improvements
```
### Universal loop flags
| Flag | Purpose |
|---|---|
| `--tillend` | Repeat until empty round (zero findings, zero actions) |
| `--repeat ` | Repeat exactly N times |
| `--focus ` | Bias toward: `security` Β· `dx` Β· `performance` |
| `--auto` | No confirmation prompts |
| `--maxruns ` | Safety cap (default 50) |
---
## π Quickstart
```bash
# 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
```
Open Claude Code. You now have 49 `/mastermind:*` workflows available:
```bash
/mastermind:autodev --tillend # start autonomous code loop
monomind org run my-team # run your first AI org (see .monomind/orgs/sample-team.json)
/mastermind:help # show all commands
```
---
## π§ Memory That Persists
Every session, every agent, every org writes to a persistent memory store β a JSON pattern store with episodic recall that survives across sessions. The next time you run anything, Monomind already knows what was built, what failed, and which patterns work.
```mermaid
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
```
```bash
monomind memory store "key insight" --namespace my-project
monomind memory search "auth implementation" # BM25 + semantic hybrid
```
---
## πΊοΈ 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.
```bash
/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 29 hook subcommands into Claude Code across edit, task, command, and session lifecycle events β logging patterns, routing agents, and feeding the intelligence system.
```mermaid
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\nlearn\nbuild-agents"]
H --> T["teammate-idle\ntask-completed"]
I --> DB[("patterns.json\nmemory store")]
DB -->|next session| CE
```
**15 background workers** run at session start (staleness-gated, refreshed when older than 6 hours): `security` Β· `health` Β· `swarm` Β· `learning` Β· `patterns` Β· `git` Β· `performance` and more.
---
## π‘οΈ 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.
```typescript
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
```
---
## π 49 Mastermind Commands
Everything runs from inside Claude Code via slash commands. Here's the highlight reel:
### Development
| Command | What it does |
|---|---|
| `/mastermind:autodev` | Autonomous research β build β review loop |
| `/mastermind:build` | Build a feature from a brief |
| `/mastermind:review` | Iterative review until zero findings |
| `/mastermind:debug` | Systematic root-cause debugging |
| `/mastermind:tdd` | Red β Green β Refactor |
| `/mastermind:architect` | Architecture review + file structure |
| `/mastermind:plan` | Comprehensive implementation plan |
| `/mastermind:worktree` | Feature work in isolated git worktree |
### Organizations
| Command | What it does |
|---|---|
| `monomind org run ` | Start an org as a real SDK-backed daemon |
| `monomind org status` / `list` | Runtime state for one or all orgs |
| `monomind org stop ` | Request a graceful stop |
| `/mastermind:approve` | Action 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 (49 commands)](https://monoes.github.io/monomind/#slash)**
---
## π¦ Packages
| Package | npm | Purpose |
|---|---|---|
| `monomind` | [](https://www.npmjs.com/package/monomind) | Umbrella β **install this one** |
| `@monoes/monomindcli` | [](https://www.npmjs.com/package/@monoes/monomindcli) | CLI engine (31 commands) |
| `monofence-ai` | [](https://www.npmjs.com/package/monofence-ai) | AI manipulation defence |
| `@monoes/monograph` | [](https://www.npmjs.com/package/@monoes/monograph) | Code knowledge graph |
---
## ποΈ How It's Built
```mermaid
graph TD
CC["Claude Code"]
MCP["MCP Server\nmonomind mcp start"]
D["Background Workers\n(@monomind/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\n29 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.** Your data never leaves your machine.
---
## Resources
- π [Full Documentation](https://monoes.github.io/monomind/)
- π’ [Autonomous Orgs](https://monoes.github.io/monomind/#orgs)
- β‘ [Mastermind Reference](https://monoes.github.io/monomind/#mastermind)
- π [All Slash Commands](https://monoes.github.io/monomind/#slash)
- π [Issues](https://github.com/monoes/monomind/issues)
- π¬ [Discussions](https://github.com/monoes/monomind/discussions)
---
Built with β₯ by monoes Β· MIT License