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
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.
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 |
- 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 likegit reset --hardandgit 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.
- Real Document Deliverables: Generates complete, fully formatted files β
.docxWord documents,.pptxpresentations,.xlsxworkbooks,.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 ````mermaidflowcharts/diagrams. - Dynamically adopts active palette colors across all 10 application themes with interactive tooltips, data point inspection, and responsive scaling.
- Renders inline interactive data visualizations in chat deliverables supporting 8+ chart formats:
- Supervisor Visual Auto-Embedding:
- Automatically rescues chart blocks placed in unrequested
.mdfiles 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.
- Automatically rescues chart blocks placed in unrequested
- 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.
- 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)
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
THINKINGstep in every mode's feed β reasoning deltas from Anthropic extended thinking, DeepSeek/OpenRouterreasoning_content, and genericreasoningkwargs 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 | 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. |
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.
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.
- 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).
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.
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
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 |
- 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 (
needsResearchcontract) 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.
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:
- 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
- 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
- Recursive deletion of drive roots, Windows directories, user profiles (
- Granular Permissions Policy: Configurable through
.nexus/permissions.jsonorpackage.json -> nexus.permissionsspecifying customallow,ask, anddenyglob patterns. Agent runs lock the active policy at launch, preventing mid-run privilege escalation. - Secret Protection at Rest: All API keys and MCP credentials are encrypted using Electron's
safeStorage(Windows DPAPI, macOS Keychain, Linux Secret Service). - Sanitized Subprocess Environments: Terminal environments strip credentials before spawning child processes. Daemons execute under a strict environment variable allowlist.
- 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.
| 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 |
- Node.js: v20 or higher
- npm: v10 or higher
- Operating System: Windows 10/11 (fully supported); macOS and Linux build configurations included.
# 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 checkNexus 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# 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:dirNexus 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:notebooknexus/
βββ 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
- Model Context Protocol (MCP) β Open tool interoperability (raw SDK,
@modelcontextprotocol/sdk) - zod β Tool schema authoring and validation
- Monaco Editor & xterm.js β In-app editor and terminal interfaces