Skip to content

About

No description, website, or topics provided.

Resources

Security policy

Stars

1 star

Watchers

0 watching

Forks

Latest commit

Β 

History

129 Commits

Folders and files

NameName
Last commit message
Last commit date
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 

Repository files navigation

Nexus logo

Nexus

The autonomous AI agent for your desktop β€” Code it. Draft it. Prove it.

A full-capability coding agent for any repository, a general desktop assistant that generates real deliverables, and a grounded research notebook with verified citations β€” unified into a single native desktop application.

Windows 10 / 11 (NSIS + Portable) Β· macOS & Linux configurable

Electron React TypeScript agentcore Version License

Download the latest release Β· Landing page Β· Changelog


Nexus is an autonomous AI desktop agent engineered with Electron + React + TypeScript. Its agentic runtime is self-built (no agent framework):

  • agentcore (electron/agentcore/) β€” messages, tool model, ReAct loop, virtual filesystem backend, middleware and the streaming LLM client (OpenAI-compatible / Anthropic Messages / Google Gemini adapters),
  • a plain-function supervisor loop for deterministic outer execution, disk checkpointing, and verify/repair self-healing,
  • progressive-disclosure skills, todo planning and subagent delegation built directly into the loop.

Everything executes on your local machine: your API keys (safely encrypted via OS keychain/DPAPI), your choice of 15+ cloud or local models (including offline Ollama), and all session storage residing on disk β€” with zero proprietary telemetry or middleman cloud.


The Three Core Modes

Nexus features three dedicated operational surfaces accessible from the persistent top bar:

Mode Purpose Workspace Root
Code Autonomous software engineer β€” Plan / Ask / Auto / Full execution, diff-first verification, multi-level undo, git worktrees, Monaco editor, and PTY terminal. Any local directory or Git repository you open
Home General assistant β€” Web research, document deliverables (Word, PowerPoint, Excel, PDF, LaTeX, Markdown), and structured long-term memory. Dedicated directory at Documents/Nexus
Notebook NotebookLM-inspired grounded research engine over documents, YouTube transcripts, and web pages with strict citation attribution. Isolated per-session SQLite & vector libraries

1. Code Mode β€” Autonomous Software Engineering

  • Four Autonomous Modes:
    • Plan: Hard read-only mode (no file mutations, no shell commands, no external side effects) designed for architecture exploration and roadmapping.
    • Ask: Interactive paired-programming mode asking for guidance and confirmations before mutations.
    • Auto: Full autonomous execution end-to-end with automated self-repair loops.
    • Full: Full Access mode β€” the agent runs every shell command, install, and git operation without approval prompts (including risky-but-legitimate operations like git reset --hard and git push). Only the built-in destructive guardrails stay hard-enforced: disk/home/system wipes, machine shutdown, registry deletes, fork bombs, and privilege escalation are always blocked, as are any user-defined deny rules in .nexus/.
  • Diff-First Verify & Repair Loop: After file modifications, an autonomous supervisor reviews Git diffs and executes relevant verification cascades (typechecking, linters, unit tests). If failures occur, the supervisor extracts diagnostics and initiates repair cycles (up to 3 in Ask, 5 in Auto/Full).
  • Multi-Level Undo & Checkpoints: File snapshots paired with 20-deep run checkpoints. One-click Undo run, per-hunk diff discard, and Nexus-specific commit resets that never alter your personal commit history.
  • Isolated Git Worktrees: Spin up ephemeral sessions inside isolated Git worktrees (.nexus/worktrees/<session>). Test, develop, and then select Merge to Main, Discard, or utilize the built-in 3-way conflict resolver.
  • Code Intelligence & LSP:
    • Out-of-process Language Server Protocol (LSP) integration for TypeScript, Python, Go, Rust, and C++ providing definitions, references, document symbols, and diagnostics.
    • WebAssembly-backed Tree-sitter grammar warmup for instant syntactic outline extraction and symbol indexing.
    • Persistent repository map and project index.
  • Developer Tooling: Monaco code editor, embedded xterm.js terminal powered by an out-of-process PTY host (pty-host.cjs), background daemon manager (dev servers with port detection and log streaming), @-file autocomplete mentions, and image attachment previews.
  • Atomic Multi-File Patching: High-speed, atomic file patching (apply_patch) supporting search-and-replace blocks, unified diff hunks, file creation, deletion, and relocation.
  • Rules & Memory Layering: Automatic ingestion of .cursorrules, AGENTS.md, CLAUDE.md, .windsurfrules, and .nexus/rules, with persistent project and session memory appended after each completed run.

2. Home Mode β€” Desktop Assistant & Document Generation

  • Real Document Deliverables: Generates complete, fully formatted files β€” .docx Word documents, .pptx presentations, .xlsx workbooks, .pdf, .md, and LaTeX β€” not raw code snippets.
  • Native Interactive Charts & Visual Graphs:
    • Renders inline interactive data visualizations in chat deliverables supporting 8+ chart formats: bar`, hbar, ````line, area`, pie, ````donut, scatter`, radar, and ````mermaid flowcharts/diagrams.
    • Dynamically adopts active palette colors across all 10 application themes with interactive tooltips, data point inspection, and responsive scaling.
  • Supervisor Visual Auto-Embedding:
    • Automatically rescues chart blocks placed in unrequested .md files and renders them directly in the chat stream.
    • Auto-detects generated chart plots (e.g. Python matplotlib chart_*.png, .svg) and embeds them into the final response under a formatted Visual Evidence & Charts section.
  • Strict Deliverable Contracts: Enforces tangible output verification so the model cannot substitute conversational promises ("I will now create...") for actual deliverables when files or charts are requested.
  • Magic-Byte & OpenXML Validation: Every generated document is validated against binary magic bytes and inspected via zip/XML structure parsers to ensure corruption-free files compatible with Microsoft Office and Google Docs.
  • Structured Long-Term Memory:
    • Four distinct memory tiers: User Profile, Preferences, Factual Knowledge, and Project Context.
    • Dynamically injected into context based on conversational relevance.
    • Granular control: tell the agent "remember that..." or selectively remove items via per-fact Forget buttons.
  • Web Research & Visual Automation: Integrated headless and visual browser tools with snapshot inspection, element grounding, and SSRF-safe request capabilities.

3. Notebook Mode β€” Grounded Research & Studio Artifacts

  • Multi-Source Ingestion Pipeline:
    • Ingests PDF, DOCX, PPTX, TXT, Markdown, CSV, TeX, YouTube video transcripts, and public web pages.
    • Resilient asynchronous processing pipeline (queued β†’ parsing β†’ chunking β†’ indexing β†’ ready) with crash recovery.
  • Net-Guard SSRF Protection: Ingestion and web fetch pipeline enforces strict network security boundaries (net-guard.ts), blocking private intranet ranges, localhost, and non-HTTP protocols.
  • Grounded Chat with Verified Citations:
    • Hybrid retrieval combining dense vector similarity (SQLite vectors), BM25 lexical token matching, and structural heading boosts.
    • Clickable [S1], [S2] citation badges that instantly open the exact passage and highlight the evidence source in the side panel.
    • Transparent retrieval traces displaying passage scores and candidate ranking.
  • Strict Groundedness Gate: Evaluates answer fidelity on a 0–10 scale. When ingested sources do not contain sufficient evidence, the model refuses to hallucinate rather than guessing.
  • Studio Generative Artifacts: One-click generation of:
    • Reports (DOCX / PDF)
    • Presentations (PPTX)
    • Quizzes (Graded multi-choice and boolean questions with passage citations and interactive player)
    • Flashcards (Study flashcard sets with interactive review player)
    • Mind Maps (Interactive hierarchical graph rendered on visual canvas with zoom & pan)
    • Summaries (Executive overviews, section analyses, and key takeaways)

OpenCode & Antigravity Step Experience

Nexus features a redesigned, interactive step execution feed inspired by OpenCode and Antigravity, active across Code, Home, and Notebook modes:

  • Connected Stepper Timeline: Step execution is rendered along an interconnected vertical track with clean status nodes:
    • πŸ”„ Running: Active spinner with glowing aura and pulsating live beacon.
    • βœ… Completed: Crisp emerald checkmark with execution timing.
    • ❌ Failed / Error: Dedicated warning icon and collapsible diagnostic trace.
  • Antigravity Live Pulse Beacon: When the agent is actively executing, the summary header features an animated dual-ring pulse beacon (stepBeaconPulse).
  • Standardized Tool Badges: Activities are color-coded and labeled with monospace pills:
    • READ: File reading with line ranges (src/App.tsx:1-120).
    • WRITE / EDIT / PATCH: Atomic file additions, modifications, and patches.
    • BASH / RUN: Terminal command executions ($ npm test).
    • SEARCH / GREP / GLOB / LSP: Codebase grep, globbing, directory listing, and symbol lookups.
    • SKILL: Skill consultations and on-demand loads.
    • WEB / BROWSE: Web queries and page visits.
    • AGENT: Subagent delegations.
    • PLAN: Interactive working plan item trackers.
  • Live Active Step Highlighting: The currently running step displays an animated shimmer gradient wave and live present-tense verbs ("Executing command", "Reading file", "Applying patch").
  • Consolidated Step Pairing: Merges tool invocations and subsequent completions into a single unified step card, avoiding duplicate or noisy activity rows.
  • Agent Reasoning Stream (Claude Code-style): Model reasoning surfaces as a first-class THINKING step in every mode's feed β€” reasoning deltas from Anthropic extended thinking, DeepSeek/OpenRouter reasoning_content, and generic reasoning kwargs accumulate into one live block (warm italic prose, expandable, capped to a recent tail), close with each tool call, and stream inside subagent cards too. Reasoning stays ephemeral: it enriches the live feed without bloating the persisted transcript.
  • Expandable Output Cards: Terminal outputs, file excerpts, and diagnostic logs feature dark monospace styling, syntax presentation, and a one-click Copy to Clipboard button.

Feature Matrix

Feature Details
15 LLM Providers OpenAI, Anthropic Claude, Google Gemini, Mistral, Groq, xAI Grok, OpenRouter, DeepSeek, OpenCode Zen, Together AI, Fireworks, Azure OpenAI, AWS Bedrock, local Ollama, and custom OpenAI-compatible endpoints with dynamic model discovery.
Model Context Protocol (MCP) Native MCP client supporting stdio, HTTP, and SSE transports. Features connection health testing, isolated fault boundaries, and encrypted configurations.
Plugin Marketplace Redesigned desktop store in Settings. Features Omni-search, status filters, capability chips (Skills, Subagents, Commands, Rules, Hooks), Grid/List views, slide-over details modal, custom registry feeds, and local auto-discovery dev roots.
Modular Bundled Suites Includes Nexus Engineering Suite (curated rules & workflows across TypeScript, Python, React, Rust, Go, Vue, Swift, Docker, PostgreSQL) and Nexus Research Studio (deep research, agent evaluation, docx/pptx/xlsx/pdf tooling).
Interactive Visualizations Native in-chat rendering of 8+ interactive chart types (bar, hbar, line, area, pie, donut, scatter, radar, and Mermaid diagrams) with multi-theme styling, interactive tooltips, and automatic image plot embedding.
Specialist Subagents 68 specialized agents (architect, code reviewer, security reviewer, TDD guide, language-specific build error resolvers) dispatched as scoped subagents (max 3 concurrent per run, 1 mutating).
Coding Rule Packs 122 rule sets across 22 languages and frameworks, dynamically merged with workspace rules.
Slash Commands 38 built-in slash commands (/plan, /auto, /review, /test, /security, /pr, /build-fix, etc.) plus custom user-defined commands supporting variable replacement ({{input}}, $ARGUMENTS).
Adaptive Loop Supervisor Smart per-target repeat detection with steer-forward notices, quota-governed research limits, doom-loop circuit breakers, and Windows path normalization.
Fail-Safe Token Accounting Comprehensive token and cost persistence across successful, cancelled, and failed runs.
Lifecycle Hooks Shell lifecycle hooks configured via .nexus/hooks.json (run:start, run:end, tool:before, tool:after, verify:fail) with stdin JSON payloads and tool veto capabilities.
Agent Browser Embedded hidden webview profiles per mode with rendered DOM inspection, interactive element actions, and SSRF-safe API fetch utilities.
10 Themes Nexus Emerald, Dark-White, Midnight, Grape, Ember, Crimson, Lagoon, Moss, Alabaster, and Daylight.
Auto-Updates Integrated updater via GitHub Releases (electron-updater) with live background progress pill.

Plugin Marketplace & Modular Extensibility

Nexus features a modular extension system packaged as self-contained plugin bundles (.nexus/plugins/<name>/). Each plugin can bundle skills, specialist subagents, custom slash commands, coding rule packs, and lifecycle hooks into a single distributable unit.

Store Interface (Settings β†’ Marketplace)

The in-app Marketplace provides an experience tailored for discovering and managing plugins:

  • Hero Banner & Live Metrics: Ambient gradient header displaying live connectivity status (Official Registry vs. Custom Feed) alongside real-time counts for Total Packages, Installed, and Local Dev items.
  • Flagship Spotlight: Highlights recommended suites (nexus-engineering-suite) with capability breakdowns and instant 1-click install/manage actions.
  • Omni-Search & Multi-Filter Toolbar: Text search by name or author, segmented status tabs (All, Installed, Available, Local Dev), sorting (Featured, Name, Installed), and responsive Grid vs. List layout switching.
  • Capability Filter Chips: Filter plugins by injected capabilities:
    • ✨ Skills: Workflow guides and tool expansions.
    • πŸ€– Subagents: Domain-specific specialist agents.
    • πŸ’» Slash Commands: Workspace shortcuts with argument substitution.
    • πŸ›‘οΈ Rules: Granular coding standards and framework best practices.
    • ⚑ Hooks: Event triggers for lifecycle automation.
  • Plugin Details Inspector: Slide-over modal inspects long descriptions, capability explanations, supported workspace modes, local source paths, technical IDs, and direct action triggers.
  • Custom Feeds & Dev Roots Modal: Manage custom JSON registry URLs and configure local auto-discovery directories (pickDevRoot) to automatically hot-load unpacked plugins during development.

Bundled Flagship Suites

  • Nexus Engineering Suite (nexus-engineering-suite): Comprehensive engineering standards, architecture decision records, testing pipelines, and Docker/DB patterns for TypeScript, React, Python, Rust, Go, Vue, and Swift.
  • Nexus Research Studio (nexus-research-studio): Autonomous research tools, agent-evaluator, spec-miner, docs-lookup, and document export engines (docx, pptx, xlsx, pdf).

Creating & Publishing Plugins

A plugin bundle requires a manifest.json at its root. Folders for skills/, agents/, rules/, commands/, and a hooks.json file are automatically detected:

{
  "id": "release-notes",
  "name": "Release Notes",
  "version": "1.0.0",
  "author": "Nexus Team",
  "description": "Creates formatted release notes and changelogs from Git commit history.",
  "modes": ["code", "home"],
  "capabilities": ["skills", "hooks"],
  "source": "https://example.com/plugins/release-notes.zip"
}

To publish to the official registry, add the plugin to plugins/ and add a listing to registry.json. Community registries can be loaded in Settings by adding the registry URL.

Architecture & Loop Design

                     β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
 User Prompt ──────▢ β”‚ 1. PLAN / ROUTE                                         β”‚
                     β”‚    - Mode heuristic & task routing                      β”‚
                     β”‚    - Active skills & prompt assets injection            β”‚
                     β”‚    - Relevant memory extraction                         β”‚
                     β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
                                                 β”‚
                                                 β–Ό
                     β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
                     β”‚ 2. DEEP AGENT LOOP (self-built agentcore)               β”‚
                     β”‚    - Tool calls: Filesystem, Bash, AST / LSP, Browser,  β”‚
                     β”‚      Web search, Memory, MCP, Subagents, ask_user       β”‚
                     β”‚    - Loop prevention & Doom loop circuit breakers       β”‚
                     β”‚    - Rate limit backoff & checkpoint snapshots          β”‚
                     β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
                                                 β”‚
                                                 β–Ό
                     β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
                     β”‚ 3. VERIFICATION (outer supervisor loop)                  β”‚
                     β”‚    - Diff-first inspection                              β”‚
                     β”‚    - Diagnostics cascade (Typechecks / Tests / Lints)   β”‚
                     β”‚    - Deliverable schema & magic-byte contract check     β”‚
                     β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
                                   β”‚ Failure                     β”‚ Success
                                   β–Ό                             β”‚
                     β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”               β”‚
                     β”‚ 4. REPAIR SUPERVISOR      β”‚               β”‚
                     β”‚    - Injects diagnostics  β”‚               β”‚
                     β”‚    - Ask: ≀ 3 repairs     β”‚               β”‚
                     β”‚    - Auto/Full: ≀ 5 repairs  β”‚               β”‚
                     β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜               β”‚
                                   β–²                             β”‚
                                   └─────── Loop back ────────────
                                                                 β”‚
                                                                 β–Ό
                                                  β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
                                                  β”‚ 5. FINALIZATION            β”‚
                                                  β”‚    - Checkpoint persistenceβ”‚
                                                  β”‚    - Memory facts update   β”‚
                                                  β”‚    - Git undo snapshot     β”‚
                                                  β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜

| Mode | Recursion Step Cap | Automated Repairs | Permissions |

|---|---|---|---| | Plan | 40 | 0 (None) | Read-only strictly enforced | | Ask | 100 | Up to 3 | Interactive confirmation for mutations | | Auto | 150 | Up to 5 | Fully autonomous with self-repair | | Full | 200 | Up to 5 | No approval prompts β€” destructive guardrails enforced only |

Loop Resilience & Supervision

  • Per-Target Loop Prevention: Instead of aborting an entire multi-step run when an external URL or web query returns unhelpful content, the loop supervisor tracks per-target query signatures:
    • 1st repeat: Executes normally.
    • 2nd repeat: Continues with an advisory note encouraging the model to explore alternate sources or move forward.
    • 3rd repeat: Restricts only that specific target URL/query for the duration of the run with steer-forward guidance, enabling the model to proceed with remaining plan objectives.
    • Doom-Loop Circuit Breaker: Retained as a terminal fallback if a model repeatedly loops without emitting productive tool calls or progress.
  • Adaptive Research Budgeting: Imposes quota-governed research limits (needsResearch contract) to prevent uncontrolled web search and browser loops.
  • Fail-Safe Token Accounting: Persists and finalizes token consumption across successful, cancelled, interrupted, or failed runs so session analytics accurately track all API costs.
  • Cross-Platform Path Normalization: Resolves Windows backslash differences, drive letters, and case discrepancies (electron/path-utils.ts) across diffing, search, and sandboxing.

Security, Approvals & Privacy

Nexus operates with direct filesystem and shell access on your machine by design. Safety is governed by multi-tier approval gates, a hardcoded denial backstop, and encrypted local storage:

  1. Interactive Approval Prompts: Sensitive operations trigger an interactive dialog with Deny / Allow once / Allow for session (120-second timeout automatically defaults to Deny). Heuristics intercept:
    • git push, git reset, git clean, git rebase
    • Package installations (npm install, pip install, cargo add, etc.)
    • Dynamic script execution (curl ... | sh, Invoke-Expression, PowerShell encoded commands)
    • Mutating network operations and file uploads
  2. Hardcoded Denial Backstop: Destructive commands are permanently blocked and cannot be bypassed:
    • Recursive deletion of drive roots, Windows directories, user profiles (rm -rf /, Remove-Item -Recurse ..\..)
    • Low-level disk formatting (mkfs, dd of=/dev/…, diskpart)
    • System registry wipes, user account creation, fork bombs
  3. Granular Permissions Policy: Configurable through .nexus/permissions.json or package.json -> nexus.permissions specifying custom allow, ask, and deny glob patterns. Agent runs lock the active policy at launch, preventing mid-run privilege escalation.
  4. Secret Protection at Rest: All API keys and MCP credentials are encrypted using Electron's safeStorage (Windows DPAPI, macOS Keychain, Linux Secret Service).
  5. Sanitized Subprocess Environments: Terminal environments strip credentials before spawning child processes. Daemons execute under a strict environment variable allowlist.
  6. No External Telemetry: No user prompts, source code, or trajectories leave your machine. Network activity is limited strictly to configured model endpoints and user-initiated web tools.

Data & Storage Layout

Category Storage Location Description
App State %APPDATA%/nexus/nexus-state.json Providers, settings, MCP configurations (keys encrypted)
Project Workspace <project>/.nexus/ Local index, checkpoints, trajectories, artifacts, hooks, plugins
Session Worktrees <project>/.nexus/worktrees/ Ephemeral Git worktree branches per session
Home Deliverables Documents/Nexus/ Validated office documents, spreadsheets, and presentations
Project Skills <project>/.nexus/skills/ Workspace-specific SKILL.md definitions
Notebook Libraries %APPDATA%/nexus/notebooks/<id>/ Ingested source files, passage chunks, and SQLite vector stores

Getting Started

Prerequisites

  • Node.js: v20 or higher
  • npm: v10 or higher
  • Operating System: Windows 10/11 (fully supported); macOS and Linux build configurations included.

Installation & Development

# Clone the repository
git clone https://github.com/amine-elhanine/nexus-code.git
cd nexus-code

# Install dependencies (use npm.cmd if PowerShell script execution is restricted)
npm install

# Start in development mode (Vite HMR + Electron)
npm run dev

# Run TypeScript compiler checks (renderer + electron)
npm run check

Running Test Suites

Nexus maintains a comprehensive testing harness:

# Run unit test suite (35 suites covering rate-limits, checkpoints, LSP, hooks, plugins, memory, charts, paths)
npm run test:unit

# Run notebook test suite (11 suites covering ingestion, RAG, SQLite vectors, net-guard, studio artifacts)
npm run test:notebook

# Run permissions and security policy test suite
npm run test:permissions

# Run full integration test suite (sandbox + agent execution)
npm test

# Run headless agent evaluation benchmark
npm run eval:agent

# Run offline deterministic notebook RAG evaluation
npm run eval:notebook

Production Build & Packaging

# Compile renderer and Electron main process
npm run build

# Launch production build locally
npm start

# Package desktop executables into release/ (NSIS installer + Portable)
npm run dist

# Package unpacked directory for rapid verification
npm run dist:dir

Headless CLI & Evaluation Harness

Nexus includes headless evaluation runners to benchmark models and prompt assets against standardized suites:

# Run agent evaluation benchmark
npm run eval:agent

# Run repeated evaluations to measure consistency
npm run eval:agent -- --repeat 3

# Paired ablation test comparing skills and rules impact
npm run eval:agent -- --case code-subtotal-cents --compare-assets skills,rules --repeat 2

# Offline deterministic notebook RAG evaluation
npm run eval:notebook

Repository Structure

nexus/
β”œβ”€β”€ electron/                   # Electron Main Process (TypeScript)
β”‚   β”œβ”€β”€ main.ts                 # Window management, lifecycle, IPC registry
β”‚   β”œβ”€β”€ agent-service.ts        # Agent core: graph orchestration, verify/repair, streaming
β”‚   β”œβ”€β”€ providers.ts            # 15 LLM provider integrations & model factory
β”‚   β”œβ”€β”€ command-service.ts      # Shell execution, permission gates, approval prompts
β”‚   β”œβ”€β”€ code-tools.ts           # Code intelligence tools (definitions, references, outline)
β”‚   β”œβ”€β”€ edit-tools.ts           # Atomic apply_patch, search-and-replace, file mutations
β”‚   β”œβ”€β”€ diff-service.ts         # Git diff engine, hunk discard, checkpoint rollbacks
β”‚   β”œβ”€β”€ worktree-service.ts     # Isolated git worktrees & 3-way conflict resolver
β”‚   β”œβ”€β”€ lsp-service.ts          # Language Server Protocol client (TS, Py, Go, Rust, C++)
β”‚   β”œβ”€β”€ hooks-service.ts        # Lifecycle hooks engine (.nexus/hooks.json)
β”‚   β”œβ”€β”€ plugins-service.ts      # Plugin discovery & management (.nexus/plugins/)
β”‚   β”œβ”€β”€ daemon-service.ts       # Background dev process & port manager
β”‚   β”œβ”€β”€ terminal-service.ts     # PTY terminal manager & pty-host.cjs bridge
β”‚   β”œβ”€β”€ browser-service.ts      # Hidden webview agent browser
β”‚   β”œβ”€β”€ home-*.ts               # Home mode: tasks, memory, deliverable validation
β”‚   β”œβ”€β”€ notebook-*.ts           # Notebook mode: SQLite vectors, hybrid RAG, studio generators
β”‚   β”œβ”€β”€ subagent-service.ts     # 68 specialist subagents execution engine
β”‚   └── system-*/               # Bundled skills, rules, commands, and agent profiles
β”œβ”€β”€ src/                        # Renderer UI (React 19 + TypeScript + Vite)
β”‚   β”œβ”€β”€ App.tsx                 # Main application layout, navigation, and modal manager
β”‚   β”œβ”€β”€ views/                  # Primary mode views: AgentView, HomeView, NotebookView, DiffView, MemoryView
β”‚   β”œβ”€β”€ components/             # UI components: chat stepper, Monaco editor, xterm terminal, studio modals
β”‚   β”œβ”€β”€ state/                  # Controllers: useAppController, useHomeController, useNotebookController
β”‚   β”œβ”€β”€ styles/                 # 10 themes and global styling system
β”‚   └── types.ts                # Shared TypeScript type definitions
β”œβ”€β”€ scripts/                    # Headless CLI and evaluation benchmarks
β”œβ”€β”€ evals/                      # Standardized evaluation datasets
β”œβ”€β”€ test/                       # 56+ test files and integration test suites
└── landing_page/               # Static marketing site

References & Credits

About

No description, website, or topics provided.

Resources

Security policy

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages