The Nexus 🌐

Personal Agentic Workspace — Turns your ideas into real, manageable projects on your computer. 26+ specialized AI agents handle everything from research to code to security — you manage the vision, not the syntax.

🌐 Website | 🎥 Watch the Announcement Video | ☕ Support on Patreon

⚠️ Disclaimer: This project was entirely vibecoded by a single person. It is a personal experiment in AI-assisted development and is not intended for production use. Expect rough edges, unconventional patterns, and the occasional "it works on my machine" moment. Use at your own risk — and have fun with it.

---

📸 The Command Center

---

Overview

The Nexus bridges your local filesystem with an intelligent web dashboard, turning your laptop into a connected development fortress. Every decision passes through a human-in-the-loop review gate, so you manage the project, not the code.

• No-Code Design — The system writes, reviews, and audits code for you
• 26+ Specialized Agents — Researchers, architects, builders, auditors, critics, and more
• AI Terminal — Multi-provider chat interface (Gemini, Claude, OpenAI, Grok)
• Historical AI Mesh archive — former fleet orchestration was archived out of the tree on 2026-09-03 (see /Volumes/Projects/Backup/TheNexus-dead-weight-2026-09-03)
• The Pipeline — 8-node orchestrator that turns ideas into organized projects with tasks
• Task Manager — Full lifecycle: Idea → Research → Plan → Build → Audit → Complete
• SOTA Model Discovery — Automatic detection of the latest AI models at startup
• The Codex — Interactive architecture visualizations and documentation hub
• MCP Server — praxis-mind (services/praxis-mind-mcp/), the Model Context Protocol surface AI agents use to read and govern the board

---

Architecture

graph TD
    User["👤 You"] -->|natural language| Terminal

    subgraph Frontend ["🖥️ Dashboard — Next.js :3000"]
        Terminal["💬 AI Terminal"]
        Tasks["📋 Task Manager"]
        Agents["🤖 Agent Manager"]
        Monitor["📊 System Monitor"]
        Codex["📖 The Codex"]
    end

    subgraph Backend ["⚡ Node.js API — Express :4000"]
        REST["REST API\n105 endpoints"]
        Discovery["🔍 SOTA Model\nDiscovery"]
        Critic["🔬 Code Critic"]
        Supervisor["👔 Supervisors"]
    end

    subgraph Persistence ["💾 Data"]
        DB[("SQLite\nnexus.db")]
        FS[("Local\nFilesystem")]
    end

    subgraph Providers ["☁️ AI Providers"]
        Gemini["Google Gemini"]
        Claude["Anthropic Claude"]
        GPT["OpenAI GPT"]
        Grok["xAI Grok"]
    end

    Terminal --> REST
    Tasks --> REST
    REST --> Supervisor
    Discovery --> Providers
    Supervisor --> Providers
    REST --> DB
    REST --> FS
    Critic -.->|review before write| FS

    style User fill:#0f172a,stroke:#06b6d4,stroke-width:2px,color:#06b6d4
    style Terminal fill:#0f172a,stroke:#06b6d4,stroke-width:2px,color:#67e8f9
    style Discovery fill:#0f172a,stroke:#10b981,stroke-width:2px,color:#6ee7b7
    style Critic fill:#0f172a,stroke:#8b5cf6,stroke-width:2px,color:#c4b5fd
    style DB fill:#1e293b,stroke:#64748b,stroke-width:2px,color:#94a3b8

The Pipeline — End-to-End Data Flow

From your idea to deployed code — the 8-node Project Plan Generator orchestrates every step. Infrastructure includes the Blackboard (shared memory) and Glass Box Broadcasting (WebSocket artifacts for real-time visibility). See it live →

Directory Structure

TheNexus/                           # Flat monorepo
├── server/                         # Node.js Express backend
│   ├── server.js                   # Main API server
│   ├── scanner.js                  # Project discovery engine
│   ├── agent/                      # Multi-provider AI agent
│   ├── routes/                     # Modular route handlers
│   ├── services/                   # Business logic services
│   │   ├── model-discovery.js      # SOTA model auto-detection
│   │   ├── critic.js               # Code review service
│   │   └── ...                     # 10+ services
│   └── tools/                      # Agent tool definitions
├── dashboard/                      # Next.js 16 frontend
│   └── src/
│       ├── app/                    # App Router pages
│       ├── components/             # UI components
│       └── lib/nexus.ts            # Centralized API client
├── cortex/                         # Python AI Brain (Pipeline orchestrator)
├── config/                         # Centralized configuration
│   ├── model_registry.yaml         # LLM model configs
│   └── prompts.yaml                # System prompts
├── db/                             # SQLite schema & migrations
├── .context/                       # Project context docs (for AI agents)
└── Start The Nexus.example.bat     # Windows startup template (double-click)
└── Start The Nexus.example.command # macOS startup template (double-click)
└── start-local.example.sh          # Linux startup template

Archived on 2026-09-03 (no longer in the tree): _retired/nexus-builder/, sandbox/, tests/cortex/, antigravity-extension/ — moved to /Volumes/Projects/Backup/TheNexus-dead-weight-2026-09-03.

---

Quick Start

Prerequisites

• Node.js 18+ / Python 3.10+ / npm / git
• API keys for AI providers (at least one)

Installation

Start by right clicking on your main "Projects" folder and click "Open in Terminal", then copy and paste the following commands one by one. Your main Projects folder should not be nested inside Documents, Downloads, or any other system folders.

git clone https://github.com/VIbeShiftAI/TheNexus.git
cd TheNexus

Windows

install-windows.bat

macOS / Linux

chmod +x install-mac.sh
./install-mac.sh

The installer handles everything: Node.js dependencies, Dashboard build dependencies, Python virtual environment, and configuration file scaffolding.

After installation, configure your API keys. Note, I can't guarantee you can get full functionality without both a Google and Anthropic API key, as those were the 2 I started development with:

Option A — Dashboard Settings (recommended) Once The Nexus is running, click the ⚙️ Settings gear icon in the top-right of the dashboard. The settings panel lets you edit your PROJECT_ROOT and all API keys — changes are saved to both .env files automatically.

Option B — Command Line

setup-env.bat          # Windows
./setup-env.sh         # macOS / Linux

Running

Windows

Double-click Start The Nexus.bat in Explorer, or run from terminal:

"Start The Nexus.bat"

macOS

Double-click Start The Nexus.command in Finder, or run from terminal:

open "Start The Nexus.command"

Linux

./start-local.sh

Opens 2 terminal windows:

1. Node.js Backend — Express API (port 4000)
2. Next.js Dashboard — Frontend (port 3000)

Endpoint	URL
Dashboard	http://localhost:3000
Node.js API	http://localhost:4000

---

Configuration

Configure via the ⚙️ Settings page in the dashboard, or edit .env directly:

# Required
PROJECT_ROOT=/path/to/your/projects

# AI Providers (at least one)
GOOGLE_API_KEY=your-key
ANTHROPIC_API_KEY=your-key
OPENAI_API_KEY=your-key
XAI_API_KEY=your-key

# Frontend
NEXT_PUBLIC_API_URL=http://localhost:4000
NEXT_PUBLIC_CORTEX_URL=http://localhost:8100

---

SOTA Model Discovery

On startup, the Model Discovery Service (server/services/model-discovery.js) queries the model listing APIs of all 4 providers in parallel, matches models against known families (Gemini Pro, Claude Opus, GPT, Grok), and selects the highest version per family — zero-config model upgrades.

---

Retired Workflow Orchestration

The former Python workflow orchestration service was decommissioned on 2026-07-02 and moved to _retired/nexus-builder/, which was itself archived out of the repository on 2026-09-03 to /Volumes/Projects/Backup/TheNexus-dead-weight-2026-09-03. See docs/decommission/langgraph-2026-07-02.md for the decision record. It is preserved for recovery only and is not part of the live startup path.

---

Task Manager

graph LR
    Idea["💡 Idea"] -->|"Gemini Deep Research"| Researching["🔬 Researching"]
    Researching -->|"Background Polling\n4hr max"| Researched["📋 Researched"]
    Researched -->|"👤 Approve"| Planning["📐 Planning"]
    Researched -.->|"👤 Reject"| Idea
    Planning -->|"Architect Agent"| Planned["✅ Planned"]
    Planned -->|"👤 Approve"| Implementing["🔨 Implementing"]
    Planned -.->|"👤 Reject"| Idea
    Implementing -->|"Builder Agent\nwith Tools"| Testing["🧪 Testing"]
    Testing -->|"👤 Approve"| Complete["🚀 Complete"]
    Testing -.->|"👤 Reject"| Planned
    Testing -.->|"👤 Cancel"| Cancelled["🗑️ Cancelled"]

    style Idea fill:#334155,stroke:#94a3b8,color:#e2e8f0
    style Complete fill:#14532d,stroke:#22c55e,color:#22c55e
    style Cancelled fill:#450a0a,stroke:#ef4444,color:#ef4444

Each stage has human-in-the-loop gates. Research runs asynchronously with automatic resume on server restart.

---

Multi-Level Workflow System

graph TD
    subgraph Dashboard ["Dashboard Level"]
        Init["📋 Dashboard Initiative\nSecurity Sweep, Dependency Audit, etc."]
    end

    subgraph Projects ["Project Level"]
        PA["Project A"]
        PB["Project B"]
        PC["Project C"]
    end

    subgraph Features ["Feature Level"]
        FA1["Task 1\nResearch → Plan → Build"]
        FA2["Task 2\nResearch → Plan → Build"]
        FB1["Task 1\nResearch → Plan → Build"]
    end

    Init --> PA
    Init --> PB
    Init --> PC
    PA --> FA1
    PA --> FA2
    PB --> FB1

    style Init fill:#422006,stroke:#f59e0b,stroke-width:2px,color:#fbbf24
    style PA fill:#1e1b4b,stroke:#8b5cf6,color:#c4b5fd
    style PB fill:#1e1b4b,stroke:#8b5cf6,color:#c4b5fd
    style PC fill:#1e1b4b,stroke:#8b5cf6,color:#c4b5fd

Current dashboard work flows through the Node.js API and task board. Historical project workflow diagrams remain in the docs for reference but should not be treated as live startup or routing guidance.

---

Agent Tools

Tool	Description
read_file	Read file contents with offset/range support
write_file	Create or overwrite file (with Critic review)
patch_file	Replace specific text in file
append_file	Append content to end of file
apply_diff	Apply unified diff for targeted edits
edit_lines	Edit specific lines by line number
list_directory	List directory contents
run_command	Execute shell command in project directory
check_ports	List active listening ports
kill_process	Terminate a process by PID or port
checkpoint_memory	Save checkpoint context for long-running tasks

---

The Codex

The Codex (/codex) is the documentation hub with interactive visualizations:

Section	Description
End-to-End Data Flow	SVG diagram of the full 8-node pipeline
Vibecoding Workflow	Interactive diagram of all 4 fleets with sub-agents
Initiative Hierarchy	Dashboard → Projects → Tasks cascade
Interface Overview	Annotated screenshots of Dashboard and Project views
Agent Registry	Live browsable registry of all agents and fleets

---

Dashboard Components

Component	Description
ai-terminal.tsx	Multi-provider AI chat interface
task-manager.tsx	Task management with status pipeline
task-detail-modal.tsx	Full task workflow UI
agent-manager.tsx	Configure AI agents
resource-monitor.tsx	System monitor (CPU/memory/ports)
activity-feed.tsx	Recent commits across projects
dashboard-initiatives.tsx	Cross-project initiative management
project-card.tsx	Project tile with git status
project-context-manager.tsx	Project context document editor
project-workflows.tsx	Project-level workflow management

---

Development

Adding Agent Tools

1. Create tool definition in server/tools/ with Zod schema
2. Export from server/tools/index.js
3. Tools are automatically available to agents and MCP server

Adding AI Model Families

Add a pattern to MODEL_FAMILIES in server/services/model-discovery.js — the service auto-detects the latest version at next startup.

Further Documentation

Detailed architectural docs live in:

• .context/ — API reference, workflow maps, pipeline architecture, node reference, tech stack
• docs/ — System architecture, data flow diagrams
• docs/verification-protocol.md — How TheNexus work is briefed, verified, and reviewed (the protocol on file)
• The Codex — Interactive visualizations at /codex in the dashboard

---

Built With

The Nexus stands on the shoulders of outstanding open-source projects:

Backend (Node.js)

• Express — REST API backbone (105+ endpoints)
• Better-SQLite3 — Synchronous SQLite driver for persistence
• Socket.IO — Real-time WebSocket streaming for Glass Box Broadcasting
• Zod — Schema validation for agent tool definitions
• simple-git — Git integration for project discovery and commit tracking
• Helmet — HTTP security headers
• @modelcontextprotocol/sdk — MCP server integration

Frontend (Next.js)

• Next.js — React framework powering the dashboard (App Router)
• React — UI component library
• Tailwind CSS — Utility-first styling
• Framer Motion — Animations and transitions
• Lucide React — Icon system
• React Flow (@xyflow/react) — Interactive node-based visualizations in The Codex
• Monaco Editor — Code editing component
• Recharts — Dashboard charts and system monitoring graphs
• react-markdown — Markdown rendering with GFM support

AI Providers

• Google Gemini · Anthropic Claude · OpenAI · xAI Grok

---

License

This project is licensed under the MIT License.

---

GitHub: https://github.com/VIbeShiftAI/TheNexus