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 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)
- The AI Mesh — 4 specialized fleets orchestrated by Nexus Prime with adversarial review
- 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 — Model Context Protocol integration for AI agent interoperability
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 Engine ["🧠 AI Engine — FastAPI :8000"]
LangGraph["⭐ Nexus Prime\nLangGraph Engine"]
Fleets["🛡️ 4 Agent Fleets\n26+ Agents"]
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
REST <-->|HTTP Proxy| LangGraph
Supervisor --> LangGraph
LangGraph --> Fleets
Fleets --> Providers
Discovery --> Providers
REST --> DB
REST --> FS
LangGraph --> 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 LangGraph fill:#1a1a2e,stroke:#fbbf24,stroke-width:3px,color:#fbbf24
style Fleets fill:#0f172a,stroke:#f43f5e,stroke-width:2px,color:#fda4af
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
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 →
TheNexus/ # Flat monorepo
├── server/ # Node.js Express backend
│ ├── server.js # Main API server
│ ├── scanner.js # Project discovery engine
│ ├── mcp.js # MCP Server (stdio)
│ ├── 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
│ │ ├── langgraph-supervisor.js # LangGraph task supervisor
│ │ └── ... # 10+ more services
│ └── tools/ # Agent tool definitions
├── dashboard/ # Next.js 16 frontend
│ └── src/
│ ├── app/ # App Router pages
│ ├── components/ # UI components
│ └── lib/nexus.ts # Centralized API client
├── nexus-builder/ # Python LangGraph engine (Nexus Prime)
│ ├── main.py # FastAPI entry point
│ ├── graph_engine.py # LangGraph workflow engine
│ ├── architect/ # Architect agent (planning)
│ ├── builder/ # Builder agent (implementation)
│ ├── auditor/ # Auditor agent (adversarial review)
│ ├── supervisor/ # Supervisor agent (orchestration)
│ └── researcher/ # Research agent
├── cortex/ # Python AI Brain (Pipeline orchestrator)
├── sandbox/ # Secure code execution sandbox
├── 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
- Node.js 18+ / Python 3.10+ / npm / git
- API keys for AI providers (at least one)
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 TheNexusinstall-windows.batchmod +x install-mac.sh
./install-mac.shThe 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 / LinuxDouble-click Start The Nexus.bat in Explorer, or run from terminal:
"Start The Nexus.bat"Double-click Start The Nexus.command in Finder, or run from terminal:
open "Start The Nexus.command"./start-local.shOpens 3 terminal windows:
- LangGraph Engine — Python (port 8000)
- Node.js Backend — Express API (port 4000)
- Next.js Dashboard — Frontend (port 3000)
| Endpoint | URL |
|---|---|
| Dashboard | http://localhost:3000 |
| Node.js API | http://localhost:4000 |
| LangGraph API | http://localhost:8000 |
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:8000On 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.
Nexus Prime — the CEO — delegates to 4 specialized fleets. Each fleet is a team of AI agents with distinct roles, quality gates, and rejection loops. See it live →
graph TD
Task["🎯 Project Task\nRequiring Code"] --> Prime
Prime{"⭐ NEXUS PRIME\nSupervisor — The CEO & Router"}
Prime -->|"1. Research"| RF["📚 RESEARCH FLEET\nPhase 0 — Gemini Mesh"]
Prime -->|"2. Planning"| AF["📐 ARCHITECT FLEET\nPhase 1 — Gemini Mesh"]
Prime -->|"3. Build"| BF["🔨 BUILDER FLEET\nPhase 2 — Implementation"]
Prime -->|"4. Audit"| AuF["🛡️ AUDITOR FLEET\nPhase 3 — Adversarial Mesh"]
RF --> D1["📄 DOSSIER.md"]
AF --> D2["📄 BLUEPRINT"]
BF --> D3["📄 SOURCE ARTIFACTS"]
AuF --> D4["📄 AUDIT REPORT"]
D4 -->|"✓ APPROVED"| Deploy["🚀 DEPLOY"]
D4 -->|"✗ REJECTED"| Prime
style Prime fill:#1a1a2e,stroke:#fbbf24,stroke-width:3px,color:#fbbf24
style Deploy fill:#14532d,stroke:#22c55e,stroke-width:2px,color:#22c55e
style RF fill:#0f172a,stroke:#3b82f6,stroke-width:2px,color:#93c5fd
style AF fill:#0f172a,stroke:#8b5cf6,stroke-width:2px,color:#c4b5fd
style BF fill:#0f172a,stroke:#f59e0b,stroke-width:2px,color:#fcd34d
style AuF fill:#0f172a,stroke:#f43f5e,stroke-width:2px,color:#fda4af
| Phase | Fleet | Agents | Output |
|---|---|---|---|
| 0 | Research (Gemini Mesh) | Scoper → Professor → Executor → Synthesizer | DOSSIER.md |
| 1 | Architect (Gemini Mesh) | Cartographer → Drafter → Grounder | BLUEPRINT (SPEC + MANIFEST + DDB) |
| 2 | Builder (Implementation) | ⚙Loader → Scout → Builder → ⚙Syntax Check | Source artifacts + DIFF.patch |
| 3 | Auditor (Adversarial) | ⚙Blast Calc → Sentinel → Interrogator | Audit Report (Pass/Fail + Security Score) |
Each fleet has internal quality gates — the Council Review uses a "Society of Minds" pattern where Critic, Safety, and Efficiency voters score plans. Auditor rejections cycle back to Nexus Prime for retry with critique.
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.
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
Three workflow levels cascade: Dashboard Initiatives (cross-project) → Project Workflows (multi-stage templates) → Feature Tasks (individual implementation). See .context/dashboard-workflow-map.md and .context/project-workflow-map.md for detailed sequence diagrams.
| 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 (/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 |
| 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 |
- Create tool definition in
server/tools/with Zod schema - Export from
server/tools/index.js - Tools are automatically available to agents and MCP server
Add a pattern to MODEL_FAMILIES in server/services/model-discovery.js — the service auto-detects the latest version at next startup.
Detailed architectural docs live in:
.context/— API reference, workflow maps, pipeline architecture, node reference, tech stackdocs/— System architecture, data flow diagrams- The Codex — Interactive visualizations at
/codexin the dashboard
The Nexus stands on the shoulders of outstanding open-source projects:
- LangGraph — Multi-agent workflow orchestration powering Nexus Prime and the 4 fleet system
- LangChain — Foundation for AI provider integrations and tool-calling agents
- FastAPI — High-performance async Python API serving the LangGraph engine
- 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
- 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
This project is licensed under the MIT License.
