MDMAtk/TormentNexus

At long last. Contribute to MDMAtk/TormentNexus development by creating an account on GitHub.

6 stars · 2 forks · Go

README

TormentNexus — Universal AI Control Plane

One-command install: npx @tormentnexus/install Local-first, open-source AI control plane with persistent multi-tier memory, MCP tool orchestration across 20,000+ servers, multi-agent swarm coordination, and corporate-grade security — all running on your machine. 📄 Read the Technical Whitepaper | 💬 Join Discord

Installation Quick Start (Windows) scripts\install.bat Quick Start (macOS / Linux) python3 scripts/install-client-support.py GUI Installer python3 scripts/install-gui.py What Gets Installed The installer detects and configures TormentNexus for 38+ AI coding agents. Each client receives every integration it supports:

Client SKILL MCP CMD HOOK EXT AGENT

Claude Code x x x x - -

Cursor x x x x x -

Windsurf x x x x x -

Gemini x x x - x x

Codex CLI x x x - - -

Grok Build x x x x x -

Antigravity x x - - x x

Aider - x - - - -

CodeWhale x x x x x -

Goose x x x x x -

Pi x x x - x -

Cline / Roo x x x x - -

+ 26 more x x varies varies varies varies

Corporate On-Premises Installation For enterprises running TormentNexus behind a firewall: python3 scripts/install-client-support.py --mode corporate scripts\install.bat corporate Corporate mode adds:

SSO/OIDC configuration for enterprise identity providers RBAC roles with admin/user/auditor defaults Audit logging to local SQLite with daily rotation Multi-tenant isolation for on-premises tenant separation Enterprise license key setup

Server Deployment GOOS=linux GOARCH=amd64 go build -o tn-kernel ./cmd/tormentnexus pm2 start tn-kernel --name tn-kernel -- serve -port 8090 -host 127.0.0.1

TormentNexus: The Cognitive Kernel — Universal Open-Source AI Control Plane for Multi-Agent Workflows, MCP Tools & Context-Aware Memory

TormentNexus is a local-first, open-source universal AI control plane and coding harness engineered to give your LLM agents infinite persistent memory, tool orchestration, and autonomous infrastructure assimilation—all running locally on your machine or in production.

🏢 Corporate & Enterprise Deployments (HyperNexus) For professional, corporate, and enterprise deployments, visit HyperNexus. HyperNexus is the official licensed, certified, authoritative, cloud-hosted corporate installation of the TormentNexus kernel. It provides:

Tenant Isolation: Automated provisioning scripts to spin up per-tenant containers with isolated volumes and resource limits. Enterprise-Grade Security: Full SSO support and fine-grained Role-Based Access Control (RBAC) middleware. Air-Gapped & VPC Support: Production-ready deployment configurations with daily audit logs for SIEM integration. Stripe Billing Integration: Built-in webhook configurations and subscription seats management.

Table of Contents

What It Does Architecture Core Pillars Monorepo Structure The Go Sidecar The Dashboard MCP Ecosystem Memory & Context Swarm & Multi-Agent API Surface Quick Start What's Planned Roadmap Documentation Contributing License

What It Does TormentNexus is a decision system and universal bridge — not just an aggregator. It runs locally as a modular monolith that unifies the chaotic landscape of AI tools, models, and agents into a single, coherent operating system for AI-driven development. Current Capabilities (v1.0.0-b1)

Capability Status Details

MCP Registry Stable Infinite tracked MCP servers, unlimited populated in SQLite catalog, infinite verified servers, unlimited verified tools

Native Go Tools Beta Unlimited native Go tool implementations replacing external MCP servers (filesystem, Slack, SQLite, DuckDuckGo, Ollama, TTS, Vercel, NWS, DexPaprika, Firecrawl, Exa, arXiv, Semantic Scholar, Mem0, Alpaca, Alpha Vantage, Hugging Face, Semgrep, Octagon, Browser Automation, ChromaDB, Basic Memory, MindsDB, Serena, AST-grep, PAL, Thoughtbox, and more)

Progressive Tool Routing Stable Semantic vector search + BM25 ranking injects only the most relevant tools into LLM context windows

Dual-Tier Memory Stable L1 (session scratchpad) + L2 (semantic SQLite vault) with heat-score lifecycle and autonomous context harvesting

LLM Waterfall Stable Cascading failover: NVIDIA NIM → OpenRouter → Local LM Studio / Ollama with 429/5xx handling

Multi-Agent Swarm Beta A2A protocol coordination, role rotation (Planner→Implementer→Tester→Critic), consensus engine

Autonomous Healer Stable Diagnose → Fix → Verify → Retry loop with native code execution (tsc, vitest, go test) and L2 vault persistence

Browser Automation Beta Native chromedp handlers: navigate, screenshot, evaluate, click, fill, get HTML

Skill Registry Stable Unlimited assimilated skills from multiple harness ecosystems (Aider, Agent, CCS, Hermes, Pi, etc.) with Jaccard deduplication

CodeWhale Extension Stable Native Rust extension with full Pi extension parity — infinite MCP tools, unlimited custom tools, infinite slash commands, unlimited shortcuts, L2 memory hooks, RBAC, @memory:key expansion, per-turn context harvesting, session compaction

Dashboard Stable Next.js 16 + React 19 + Tailwind CSS 4 with real-time telemetry, knowledge graph, healer view, swarm visualizer

npm Packages Published @tormentnexus/install, @tormentnexus/core, @tormentnexus/cli, @tormentnexus/openhands, @tormentnexus/vscode, @tormentnexus/cursor

tRPC Bridge Stable Type-safe API layer (port 7778) connecting UI to Go sidecar

Session Import Beta Automatic ingestion of Claude, Aider, and other harness session artifacts

Enterprise Licensing Experimental Ed25519-signed license token validation with offline verification

Supervisor Nudge Stable Autonomous Windows UI automation to maintain development momentum across AI chat surfaces

Deep Link Protocol Beta tormentnexus://attach?session=ID and tormentnexus://create?cliType=aider URI handling

Provider Metrics Stable Real-time telemetry tracking for all LLM providers with latency and cost analysis

🚀 One-Command Install npx @tormentnexus/install That's it. Detects and configures TormentNexus for 38+ AI coding agents including Claude, Gemini, Cursor, Windsurf, Aider, CodeWhale, and more. Each gets MCP config, skills, hooks, and commands.

CLI tools

OpenHands integration

Core kernel

Architecture TormentNexus is a high-performance Go modular monolith with a TypeScript/Next.js frontend, operating as a local-first control plane. ┌─────────────────────────────────────────────────────────────┐ │ OPERATOR LAYER │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │ │ Web Dash │ │ CLI (TS) │ │ VS Code │ │ │ │ Port 7779 │ │ tormentnexus│ │ Extension │ │ │ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ │ │ │ │ │ │ │ └────────────────┴────────────────┘ │ │ │ │ │ ┌───────────────────────┴───────────────────────┐ │ │ │ GO SIDECAR (Port 7778) — The Authoritative Kernel │ │ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │ │ │ SkillStore│ │ EventBus │ │ Vault │ │ Healer │ │ │ │ │ (BM25) │ │ (Swarm) │ │(sqlite) │ │(Immune) │ │ │ │ └─────────┘ └─────────┘ └─────────┘ └─────────┘ │ │ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │ │ │ Router │ │ PairOrchestrator│ │ CodeExecutor│ │ MCP Sync │ │ │ │ │(Progressive)│ │(Consensus) │ │(Sandbox) │ │(Registry)│ │ │ │ └─────────┘ └─────────┘ └─────────┘ └─────────┘ │ │ └──────────────────────────────────────────────────────┘ │ │ │ │ ┌───────────────────────┴───────────────────────┐ │ │ │ EXTERNAL MODELS & TOOLS │ │ │ │ OpenAI · Anthropic · Gemini · OpenRouter · Ollama │ │ │ 600+ MCP Servers · 3,900+ Native Go Tools │ │ └──────────────────────────────────────────────────────┘ └─────────────────────────────────────────────────────────────┘

Key Ports

Service Port Purpose

Go Sidecar 7778 Authoritative native kernel (HTTP API + tRPC)

Next.js Dashboard 7779 Web observation deck

Core Pillars 1. Progressive MCP Tool Routing & Parity Models should never be overwhelmed with a 50,000-token tool dump. TormentNexus employs a multi-layered, progressive disclosure system:

Semantic Search: Local vector embeddings match the active prompt against a global MCP directory of infinite servers. The Router: Only the top highly relevant tool schemas are injected into the active LLM context. Universal Parity: Byte-for-byte identical tool signatures for Claude Code, Codex, Gemini CLI, Cursor, and Windsurf.

2. Dual-Tier Memory Architecture (L1 / L2) Context is finite; memory must be infinite.

L1 — Session Scratchpad: Ephemeral, lightning-fast memory tied directly to the active session. L2 — The Vault: Permanent semantic storage in SQLite with sqlite-vec. Saves exact transcripts and LLM-compressed heuristics. Context Harvesting: Every session autonomously queries the L2 Vault to pull in relevant historical heuristics. Heat Mechanics: Relevance increases heat, time causes decay — biological memory modeling.

3. The Resilient LLM Waterfall Uptime is non-negotiable. TormentNexus's inference client natively catches 429s (Rate Limits) and 5xx (Server Errors), seamlessly cascading the exact payload down a prioritized chain without crashing:

NVIDIA NIM / Primary APIs OpenRouter (Secondary aggregator fallback) Local LM Studio / Ollama (Ultimate offline fallback)

4. Multi-Agent Swarm & P2P Mesh TormentNexus coordinates specialized models inside shared chatrooms via the Agent-to-Agent (A2A) protocol.

Role Rotation: Models take turns acting as Planner, Implementer, Tester, and Critic. Consensus & Debate: Agents autonomously bid on tasks, share context via a neural transcript, and debate implementations until consensus is reached. PairOrchestrator: Enforces a strict Planner → Checker → Implementer → Critic state machine with weighted consensus scoring.

5. Truth Over Hype Dashboards TormentNexus's dashboards reflect actual SQLite database rows and active Go goroutine states. No mocked UI scaffolds. Monitor telemetry, traffic inspection, working-set capacity, and LLM routing histories in real-time. 6. Autonomous Immune System Every failure is an opportunity for diagnosis, remediation, and verification.

HealerService: Multi-turn Diagnose → Fix → Verify → Retry loop using the native CodeExecutor. L2 Vault Persistence: All healing events and extracted facts are saved as long-term memory for fleet-wide intelligence sharing. Supervisor Nudge Protocol: Autonomously maintains development momentum by re-engaging inactive agents through professional, context-aware directives.

Monorepo Structure TormentNexus is a pnpm monorepo with four major layers: tormentnexus/ ├─ apps/ # Operator-facing applications │ ├─ web/ # Next.js 16 dashboard (primary browser UI) │ ├─ maestro/ # Electron desktop shell │ ├─ maestro-go/ # Go-adjacent desktop lane (experimental) │ ├─ vscode/ # VS Code extension │ ├─ tormentnexus-extension/ # Browser extension │ ├─ cloud-orchestrator/ # Nested cloud stack (mini-monorepo) │ └─ tormentnexus-extension/ # Tormentnexus extension │ ├─ packages/ # Shared libraries & TypeScript control plane │ ├─ core/ # Main TS control plane, tRPC routers, orchestration │ ├─ cli/ # CLI entrypoint (`tormentnexus` command) │ ├─ ui/ # Shared React UI components (Radix + Tailwind) │ ├─ ai/ # Model/provider SDK integration layer │ ├─ memory/ # Memory storage, retrieval, embeddings, vector DB │ ├─ types/ # Shared TypeScript types │ ├─ tools/ # Tool definitions and helpers │ ├─ mcp-registry/ # MCP metadata and registry surfaces │ ├─ mcp-client/ # MCP client integration │ ├─ agents/ # Agent-related logic and adapters │ ├─ adk/ # Agent Development Kit layer │ ├─ search/ # Search and indexing support │ ├─ tormentnexus-supervisor/ # Windows supervisor bridge (UI automation) │ ├─ browser/ # Legacy browser support │ ├─ browser-extension/ # Shared browser-extension package │ ├─ enterprise/ # Enterprise features (SSO, RBAC stubs) │ ├─ jetbrains/ # JetBrains IDE integration │ ├─ zed-extension/ # Zed editor extension │ └─ tsconfig/ # Shared TypeScript configuration │ ├─ go/ # Go modular monolith (authoritative kernel) │ ├─ cmd/tormentnexus/ # Go entrypoint │ ├─ internal/ │ │ ├─ httpapi/ # HTTP API server (600+ endpoints, 18K+ lines) │ │ ├─ tools/ # 3,900+ native Go tool implementations │ │ ├─ harnesses/ # Harness registry and management │ │ ├─ memory/ # L1/L2 memory manager │ │ ├─ memorystore/ # SQLite vault, hydration, search │ │ ├─ mcp/ # MCP native router, progressive disclosure │ │ ├─ orchestration/ # PairOrchestrator, A2A skill registry │ │ ├─ healer/ # Autonomous immune system │ │ ├─ llm/ # Waterfall routing, provider abstraction │ │ ├─ eventbus/ # High-frequency resilient message broker │ │ ├─ codeexec/ # Sandboxed code execution │ │ ├─ config/ # Configuration management │ │ ├─ vault/ # Secure persistence layer │ │ ├─ sync/ # MCP sync and assimilation │ │ ├─ graph/ # Dependency graph analysis │ │ ├─ repograph/ # Repository graph visualization │ │ ├─ license/ # Ed25519 license validation │ │ ├─ supervisor/ # Supervisor automation │ │ ├─ session/ # Session management │ │ ├─ sessionimport/ # Session import pipeline │ │ ├─ skillregistry/ # Skill registry with Jaccard deduplication │ │ ├─ toolregistry/ # Native tool registry │ │ ├─ flightrecorder/ # Audit and telemetry │ │ ├─ metrics/ # Provider performance metrics │ │ ├─ marketplace/ # Tool marketplace │ │ ├─ gossip/ # P2P mesh communication │ │ ├─ mesh/ # Mesh networking │ │ ├─ process/ # Process management │ │ ├─ workspaces/ # Workspace management │ │ ├─ workflow/ # Workflow engine │ │ ├─ git/ # Git operations │ │ ├─ gitservice/ # Git service layer │ │ ├─ ctxharvester/ # Context harvesting │ │ ├─ hsync/ # Harness synchronization │ │ ├─ interop/ # Language interoperability │ │ ├─ toon/ # Animation/graphics utilities │ │ ├─ ai/ # AI integrations (Go) │ │ ├─ buffer/ # Buffer management │ │ ├─ cache/ # Caching layer │ │ ├─ controlplane/ # Go control plane │ │ ├─ buildinfo/ # Build information │ │ ├─ lockfile/ # Lock file management │ │ ├─ submodules/ # Submodule management │ │ └─ providers/ # Provider integrations (Go) │ └─ go.mod, go.sum # Go module dependencies │ ├─ data/ # Local knowledge assets │ ├─ assimilation_state.db # MCP assimilation tracking (14,250 rows) │ ├─ bobbybookmarks/ # Bookmark ecosystems for catalog updates │ ├─ prompt_library.db # Prompt library (planned) │ └─ assimilate_skills.py # Skill ingestion script │ ├─ docs/ # Comprehensive documentation │ ├─ API_ENDPOINTS.md # 600+ endpoint reference │ ├─ PROJECT_STRUCTURE.md # Full module diagram │ ├─ ARCHITECTURE.md # Architecture overview │ ├─ UNIVERSAL_LLM_INSTRUCTIONS.md # Agent coordination rules │ ├─ GLOBAL_LIBRARY_INDEX.md # Global MCP library index (2.3MB) │ ├─ BUILTIN_TOOLS_EVIDENCE_LOCK.md # Evidence lock status │ └─ [40+ more docs] # Guides, protocols, security FAQ │ ├─ scripts/ # Workspace build/dev/maintenance scripts │ ├─ build_all.mjs # Full monorepo build │ ├─ dev_tabby_ready.mjs # Development launcher │ ├─ check_release_gate.mjs # CI release gate │ ├─ sync_versions.mjs # Version synchronization │ └─ [20+ more scripts] # Validation, indexing, pruning │ ├─ submodules/ # External upstream assimilations │ ├─ tormentnexus/ # External CLI harness upstream │ └─ tormentnexus-mcp/ # External MCP reference lane │ ├─ swarm.py, swarm_v7.py # Automated Go tool generation swarm ├─ tormentnexus.db # Main registry (MCP servers, tools, sessions) ├─ catalog.db # unlimited populated MCP server catalog ├─ provider_metrics.db # Provider telemetry database ├─ README.md # This file ├─ ROADMAP.md # Active development roadmap ├─ CHANGELOG.md # Detailed version history (400+ entries) ├─ AGENTS.md # Multi-agent coordination protocol ├─ VISION.md # North star and philosophical pillars ├─ MEMORY.md # Accumulated multi-agent insights ├─ HANDOFF.md # Session handoff protocol ├─ package.json # Root monorepo scripts └─ pnpm-workspace.yaml # Workspace boundaries

The Go Sidecar The Go sidecar is the authoritative execution kernel of TormentNexus. It is a high-performance modular monolith with dozens of internal packages and unlimited native tool implementations. Why Go?

Performance: Single-binary deployment, zero runtime dependencies, sub-millisecond API latency Reliability: Native goroutine-based concurrency, robust error handling, memory safety Portability: Cross-compilation to any platform; runs on Windows, macOS, Linux, and WSL MCP Assimilation: Replacing fragile Node.js/Python MCP servers with compiled, type-safe Go handlers

Native Go Tool Categories

Category Example Integrations

Web Search & Scraping DuckDuckGo, Firecrawl, Exa

Academic & Research arXiv, Semantic Scholar, PubMed, Open Library

Finance & Markets Alpaca, Alpha Vantage, CoinGecko, Yahoo Finance

Science & Space NASA (APOD, NEO, Mars Weather, EPIC), Open-Meteo

Entertainment PokéAPI, TVMaze, JokeAPI

Reference World Bank, Nobel Prize, Open Library

AI & LLM Ollama, Hugging Face, MindsDB

Security Semgrep, AST-grep

Communication Slack

Cloud & DevOps Vercel, Filesystem

Memory Basic Memory, ChromaDB, Mem0

Swarm Tool Generation The project includes an automated swarm pipeline (swarm.py / swarm_v7.py) that generates native Go tool implementations from MCP server specifications. This enables rapid assimilation of the MCP ecosystem at scale.

5 workers with --forever mode for continuous generation 200 task limit per run Parallel batch validation of generated tools Self-healing: Automatically removes broken implementations and regenerates

The Dashboard The TormentNexus Dashboard (apps/web) is a rich Next.js 16 / React 19 / Tailwind CSS 4 operator interface providing real-time observability and control over the entire system. Dashboard Pages

Route Purpose

/ Landing page with system overview

/dashboard Main command center

/dashboard/brain Knowledge graph v

source