mcp server

nucleus

Nucleus Brain — the AI operating system for your business. 7 AI pillar agents, bead-chain audit trail, human-in-the-loop governance. Self-hostable.

nucleusbrain/nucleuscommunitylistedunreviewed

Use tool

Set up

Runs on your computer. Pick your agent and operating system.

This project does not publish an install method we can turn into a config. Follow the README instead.

README

synced Oct 21, 2026

Nucleus Brain

The AI operating system that runs your business.

Nucleus deploys an AI CEO that orchestrates 7 pillar agents -- Engineering, Product, Data, Revenue, Customer Success, Operations, and People -- to scale your company from a small team to enterprise-level output.

You stay above the AI. You approve or reject decisions. Over time, the system learns your judgment and becomes more autonomous.

Every action is recorded as a bead -- a hash-linked, immutable audit entry. Beads form chains, chains form blocks, and blocks go to you for approval. Full transparency, full control.

Quick Start

# Install (one command)
curl -sSL https://nucleusbrain.com/setup.sh | bash

# Wire your project
cd ~/Code/my-app
nucleus init --api http://localhost:8100

# Start the AI CEO
claude --agent nucleus

The installer asks 3 questions (name, API key, optional integrations) and starts. Nucleus handles the real onboarding in conversation.

What It Does

Nucleus receives founder intent and decomposes it across 7 business pillars:

Pillar	What It Does
Engineering	Writes code, manages CI/CD, deploys, fixes bugs
Product	Creates roadmaps, writes specs, prioritizes features
Data	Builds pipelines, manages the knowledge graph, runs analytics
Revenue	Handles pricing, sales strategy, market intelligence
Customer Success	Manages onboarding, documentation, support, retention
Operations	Controls finances, compliance, cost optimization, security
People	Evaluates AI agents, designs org structure, manages safety

Architecture

YOUR MACHINE
  Docker Compose
    k3s container (lightweight Kubernetes)
      inst-<your-id> namespace
        nucleus-0 StatefulSet
          dolt         (bead database)
          orchestrator (API + dashboard + bot)
          neo4j        (knowledge graph)
        CronJobs (intake, forage, health, proposals...)
        Agent Jobs (spawned on demand)

  Your Project Repo (~/Code/my-app/)
    .claude/agents/      (AI agent definitions -- from this repo)
    .nucleus/config.json (connection config)
    .beads/              (local task tracking)
    CLAUDE.md            (project instructions)

Layer 1 (infrastructure) runs inside Docker. Pre-built images, no compilation needed. Layer 2 (agent files) lives in your project repo. Plain text files that Claude Code reads.

They connect over HTTP at localhost:8100.

What's in This Repo

This is the open-source toolkit -- everything needed to deploy and operate Nucleus:

nucleus/
  README.md               This file
  LICENSE                  MIT
  VERSION                  Current release
  CHANGELOG.md             Release history
  CONTRIBUTING.md          How to contribute
  SECURITY.md              Security policy

  agents/                  8 AI agent definitions
    nucleus.md               AI CEO orchestrator
    engineering.md           Code, CI/CD, deploys
    product.md               Roadmap, specs, prioritization
    data.md                  Analytics, ML, pipelines
    revenue.md               Sales, pricing, market intel
    customer-success.md      Onboarding, support, retention
    operations.md            Finance, compliance, security
    people.md                Team, hiring, agent evaluation

  bin/                     CLI tools
    nucleus                  Main CLI (start, stop, init, update)
    nucleus-init.sh          Project bootstrapper
    nucleus-config.sh        Config helper
    setup-wizard.py          Interactive setup wizard

  scripts/                 Operational scripts
    bd-guard.sh              Bead workflow enforcement
    bd-lock.sh               Directory locking for parallel work
    brain.sh                 Brain query tool
    deploy-sessions.sh       Launch parallel agent sessions
    cleanup-sessions.sh      Merge agent worktrees
    check-secrets.sh         Secret leak scanner
    notify.sh                Notification helper
    onboard.sh               User onboarding

  packs/                   MCP tool packs (modular capabilities)
    NucleusBrain/            Knowledge store + intake + analysis
    NucleusBeads/            Task tracking with dependency graphs
    NucleusIntake/           Continuous knowledge intake

  docker-compose.yml       Infrastructure definition
  .env.example             Environment variable template
  docs/
    USER-MANUAL.md           Complete user guide
    ARCHITECTURE.md          System architecture deep-dive

The orchestrator engine, brain, dashboard, and knowledge graph are pre-built Docker images pulled automatically during setup.

Prerequisites

Requirement	Minimum	Check	Install
Docker	20.10+	`docker --version`	docs.docker.com
Docker Compose	v2+	`docker compose version`	Included with Docker Desktop
Python	3.10+	`python3 --version`	python.org
Git	2.30+	`git --version`	git-scm.com
Claude Code	Latest	`claude --version`	`npm install -g @anthropic-ai/claude-code`
Anthropic API Key	--	--	console.anthropic.com

Optional: bd (beads CLI) for task tracking -- npm install -g beads

The `nucleus` CLI

After installation, the nucleus command is available:

nucleus help        # All commands
nucleus status      # Check if Nucleus is running
nucleus start       # Start infrastructure
nucleus stop        # Stop infrastructure (data preserved)
nucleus restart     # Restart infrastructure
nucleus logs -f     # Follow container logs
nucleus init        # Bootstrap Nucleus into current project
nucleus update      # Pull latest toolkit updates
nucleus upgrade     # Pull latest platform images
nucleus version     # Show installed versions
nucleus doctor      # Full compatibility check
nucleus wizard      # Re-run the setup wizard

Connecting Your Project

Single Repo

cd ~/Code/my-app
nucleus init --api http://localhost:8100

Auto-detects your stack (Node/Python/Rust/Go/Ruby), creates agent definitions, initializes task tracking, and verifies the API connection.

Multiple Repos (Org Mode)

cd ~/Code/myorg     # contains frontend/, backend/, mobile/
nucleus init --api http://localhost:8100

Auto-detected when the current directory is not a git repo but contains subdirectories that are. Creates shared agents at the org root and wires each sub-repo.

Using the AI Agents

claude --agent nucleus           # AI CEO -- orchestrates across all pillars
claude --agent engineering       # Writes code, manages CI/CD
claude --agent product           # Specs, roadmap, prioritization
claude --agent data              # Analytics, ML, pipelines
claude --agent revenue           # Pricing, sales strategy
claude --agent customer-success  # Onboarding, support
claude --agent operations        # Finance, compliance, security
claude --agent people            # Team structure, agent evaluation

Dashboard

Access at http://localhost:8100/admin -- brain visualization, bead chains, cluster state, recommendations, and more.

How It Grows

The toolkit is designed to evolve with your project:

Local edits -- customize agents for your domain, stack, conventions
Decision log -- the system tracks decisions and learns from your approval/rejection patterns
Phone home (optional) -- connect to a Nucleus Brain instance to share and receive learnings across the network

Versioning

Two things version independently:

Layer	What	Updated By
Toolkit	Agents, CLI, wizard, compose	`nucleus update` (git pull)
Platform	Docker images (orchestrator, brain, dashboard)	`nucleus upgrade` (docker pull)

nucleus version     # See both versions
nucleus update      # Update toolkit
nucleus upgrade     # Upgrade platform
nucleus doctor      # Check compatibility

Packs (Modular Capabilities)

Packs are standalone capabilities you can install one at a time. Each pack is self-contained -- your AI reads the INSTALL.md and sets everything up.

Pack	What It Does	Tier
NucleusBrain	Knowledge store + intake + analysis	Free
NucleusBeads	Task tracking with dependency graphs	Free
NucleusIntake	Continuous knowledge intake	Free

See packs/README.md for the full list including Pro and Enterprise packs.

Documentation

User Manual -- complete guide from install to daily operations
Architecture -- system design deep-dive
Contributing -- how to contribute
Security -- security policy and reporting

License

MIT -- see LICENSE.