Nucleus

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- 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:

1. Local edits -- customize agents for your domain, stack, conventions
2. Decision log -- the system tracks decisions and learns from your approval/rejection patterns
3. 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](packs/README.md) for the full list including Pro and Enterprise packs.

Documentation

• [User Manual](docs/USER-MANUAL.md) -- complete guide from install to daily operations
• [Architecture](docs/ARCHITECTURE.md) -- system design deep-dive
• [Contributing](CONTRIBUTING.md) -- how to contribute
• [Security](SECURITY.md) -- security policy and reporting

Links

• Website: nucleusbrain.com
• Dashboard: http://localhost:8100/admin (after install)
• API docs: http://localhost:8100/docs (after install)

License

MIT -- see [LICENSE](LICENSE).

Copyright (c) 2026 AGFarms Inc.

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: nucleusbrain
• Source: nucleusbrain/nucleus
• License: MIT

Install and usage instructions live in the source repository linked above.