README.md

June 5, 2026 · View on GitHub

⚡ NexusAgent

The Zero-Config, Self-Evolving Local AI Agent Framework

Privacy-first · GraphRAG memory · Skill auto-generation · Plugin ecosystem

Install · Quick Start · Features · CLI · Website · Config · Plugins

Features
Architecture
Installation
Quick Start
CLI Reference
Configuration
Plugin System
API Reference
Enterprise Features
Comparison
Performance
Roadmap
Contributing
License
Acknowledgments

✨ Features

🧠 GraphRAG Memory — Persistent knowledge graph using NetworkX for intelligent context retrieval
🔧 Auto Skill Generation — Agent writes its own tools during runtime and saves them permanently
🔌 Plugin System — Extend with custom plugins, hot-reload support, hook-based architecture
🐳 Docker Ready — Full containerization with Docker and docker-compose support
🌐 Web Dashboard — Optional FastAPI dashboard for monitoring skills, memory, and task history
🔒 Privacy-First — Local-first execution with Ollama. Optional cloud models via LiteLLM.
⚡ Zero Config — Works out of the box with Ollama; configurable when you need it
📦 Sandboxed Execution — Isolated skill execution with timeouts and memory limits
🤖 Multi-Agent System — Orchestrate multiple agents with task delegation and role-based routing
🛡️ Enterprise Security — Encrypted cloud sync (Fernet), audit logging with RBAC
🎤 Voice Interface — Speech-to-text (Whisper) and text-to-speech integration
💻 IDE Integration — JSON-RPC server for VS Code, JetBrains, and other editors
🚀 Self-Updating — Check for new versions, auto-update skills from a registry
💾 Export System — Export skills, graphs, and reports as JSON, Markdown, or skill packs
🎯 Multi-Model — Works with any model via LiteLLM (Ollama, OpenAI, Anthropic, etc.)

🏗 Architecture

graph TB
    CLI[CLI / Web Dashboard] --> Agent[NexusAgent Core]
    Agent --> LiteLLM[LiteLLM Router]
    LiteLLM --> Ollama[Ollama / OpenAI / Anthropic]
    
    Agent --> Memory[GraphRAG Memory<br/>NetworkX]
    Agent --> Skills[Skill Tree<br/>Auto-Generated Tools]
    Agent --> Plugins[Plugin Manager<br/>Hot-Reload]
    Agent --> Sandbox[Sandbox Executor<br/>Isolated Subprocess]
    
    Config[Config Manager<br/>YAML/JSON] --> Agent
    Updater[Self-Updater<br/>PyPI + Registry] --> Agent
    Exporter[Export Engine<br/>JSON / MD / ZIP] --> Agent
    
    Memory --> Persist[(Local Storage<br/>.nexus/)]
    Skills --> Persist
    Plugins --> PluginDir[.nexus/plugins/]
    
    style Agent fill:#0ea5e9,color:#fff
    style Memory fill:#22c55e,color:#fff
    style Skills fill:#a855f7,color:#fff
    style Plugins fill:#f59e0b,color:#fff

📦 Installation

pip (Recommended)

pip install nexus-agent

pipx (Isolated)

pipx install nexus-agent

Docker

docker pull rudra496/nexus-agent
docker run -it -v $(pwd):/workspace rudra496/nexus-agent run "Explain quantum computing"

From Source

git clone https://github.com/rudra496/nexus-agent.git
cd nexus-agent
pip install -e .

Requires: Python 3.10+ and Ollama for local models (optional for cloud models).

🚀 Quick Start

# 1. Start Ollama (if using local models)
ollama serve

# 2. Pull a model
ollama pull llama3

# 3. Run your first task
nexus run "Create a Python function to calculate Fibonacci numbers"

# 4. Check status
nexus status

# 5. Trigger self-evolution — scans your workspace and builds GraphRAG memory
nexus evolve

# 6. View generated skills
nexus skills

📋 CLI Reference

Command	Description
`nexus run "prompt"`	Execute a task with the AI agent
`nexus evolve`	Scan workspace and build GraphRAG memory
`nexus status`	View memory, skills, and plugin diagnostics
`nexus skills`	List all auto-generated skills
`nexus config show`	Display current configuration
`nexus config set model.default ollama/codellama`	Set a config value
`nexus config reset`	Reset config to defaults
`nexus web`	Launch the web dashboard (port 8420)
`nexus export -f json -k skills`	Export skills as JSON
`nexus export -f markdown -k report`	Export full report
`nexus export -f skillpack`	Export shareable skill pack
`nexus plugin list`	List installed plugins
`nexus plugin reload`	Hot-reload plugins
`nexus update`	Check for updates and self-update
`nexus sync push`	Push local data to encrypted cloud sync
`nexus sync pull`	Pull data from cloud sync target
`nexus sync status`	Show cloud sync status
`nexus audit log`	View audit log entries
`nexus audit stats`	Show audit log statistics
`nexus marketplace search "query"`	Search marketplace for skills
`nexus marketplace install <name>`	Install a skill from marketplace
`nexus marketplace list`	List all available marketplace skills
`nexus benchmark run`	Run all performance benchmarks
`nexus benchmark compare <f1> <f2>`	Compare two benchmark files
`nexus agents register <name> --role coder`	Register a new agent
`nexus agents status`	Show multi-agent system status
`nexus voice`	Voice interface: listen and respond
`nexus analyze [path]`	AST-aware code analysis
`nexus mobile`	Start mobile companion API server

⚙ Configuration

NexusAgent uses a YAML config file at ~/.nexus/config.yaml (auto-created on first run).

model:
  default: "ollama/llama3"
  fallback: null
  max_tokens: 2048
  temperature: 0.7

memory:
  max_nodes: 10000
  max_edges: 50000
  persistence_file: ".nexus/memory/graph.pkl"

skills:
  directory: ".nexus/skills"
  auto_evolve: true
  sandbox_enabled: true
  timeout_seconds: 30

plugins:
  directory: ".nexus/plugins"
  hot_reload: true

web:
  enabled: false
  host: "127.0.0.1"
  port: 8420

See docs/configuration.md for the full reference.

🔌 Plugin System

Extend NexusAgent with custom plugins. Drop a .py file in .nexus/plugins/:

# .nexus/plugins/my_plugin.py

def nexus_pre_execute(prompt: str) -> str:
    """Hook called before agent execution."""
    print(f"[MyPlugin] Processing: {prompt[:50]}...")
    return prompt

def nexus_post_execute(response: str) -> str:
    """Hook called after agent execution."""
    return response.upper()  # Example transform

nexus plugin list    # See loaded plugins
nexus plugin reload  # Hot-reload changed plugins

See docs/plugin-guide.md for the full plugin development guide.

📖 API Reference

from src.agent import NexusAgent
from src.config import load_config, save_config
from src.plugins import PluginManager
from src.export import export_skills_json, export_markdown_report
from src.sandbox import Sandbox

# Create agent with custom model
agent = NexusAgent(model="ollama/codellama")

# Execute a task
response = agent.execute("Write a sorting algorithm")

# Evolve (scan workspace)
stats = agent.evolve()

# Export data
export_skills_json(agent, "skills.json")
export_markdown_report(agent, "report.md")

# Sandbox execution
sandbox = Sandbox(timeout=30, max_memory_mb=256)
result = sandbox.execute("print('Hello from sandbox!')")

See docs/api-reference.md for complete API docs.

🔐 Enterprise Features

NexusAgent includes enterprise-grade features for team deployments:

Audit Logging — Structured JSON-lines audit log tracking all agent actions with log rotation
RBAC — Role-based access control with admin, user, and viewer roles
Encrypted Sync — Fernet symmetric encryption for all synced data
CLI: nexus audit log, nexus audit stats, nexus sync push/pull/status

📊 Comparison

Feature	NexusAgent	Aider	Continue.dev	Cursor	OpenHands
Runs Locally (with Ollama)	✅	✅	✅	✅	✅
GraphRAG Memory	✅	❌	❌	❌	❌
Self-Evolving Skills	✅	❌	❌	❌	❌
Plugin System	✅	❌	✅	✅	✅
Web Dashboard	✅	❌	❌	✅	✅
Zero-Config Setup	✅	⚠️	⚠️	✅	⚠️
Sandboxed Execution	✅	❌	❌	❌	✅
CLI Interface	✅	✅	✅	❌	✅
Open Source (MIT)	✅	✅	✅ (Apache)	❌	✅

⚠️ = Requires some configuration. This comparison reflects publicly available documentation as of April 2026 and is provided in good faith — please verify for your specific use case.

⚡ Performance

NexusAgent is designed for minimal overhead. Key performance characteristics:

Component	Design Target	Notes
Startup	Near-instant	Only loads config + existing skills
Graph Retrieval	Proportional to graph size	Keyword-based lookup over NetworkX
Skill Execution	Bounded by sandbox timeout	Configurable, default 30s
Plugin Load	On-demand	Loaded once, hot-reloaded on change

Run nexus benchmark run to measure actual performance on your hardware. Use nexus benchmark compare to track regressions across versions.

🗺 Roadmap

See docs/roadmap.md for the full roadmap.

✅ v0.1 — Core Agent

GraphRAG memory with NetworkX
Auto skill generation
Basic CLI (run, evolve, status, skills)
LiteLLM multi-model support + Ollama

✅ v0.2 — Plugins & Dashboard

Configuration management (YAML/JSON)
Plugin system with hot-reload
Web dashboard (FastAPI + REST API)
Sandboxed execution (timeout, memory limits)
Export system (JSON, Markdown, ZIP skill packs)
Self-updater + skill registry
Docker support
CI/CD + tests

✅ v0.3 — Multi-Agent

Multi-agent orchestration engine
Task delegation and intelligent routing
Collaborative shared memory
Agent communication protocol (broadcast + direct messaging)
Agent roles (coder, reviewer, tester, planner, researcher)
Priority-based task queue with load balancing

✅ v0.4 — Voice & IDE

Voice interface (Whisper STT + pyttsx3/edge-tts TTS)
IDE integration base (JSON-RPC, VS Code manifest, JetBrains ready)
AST-aware code memory (functions, classes, imports, dependencies)
Context window management (token budgeting, priority selection)
nexus voice and nexus analyze CLI commands

✅ v1.0 — Production

Encrypted cloud sync (Fernet, local/S3/WebDAV, delta sync)
Audit logging & RBAC (JSON-lines, admin/user/viewer, log rotation)
Skill marketplace (search, install, rate, 6 categories)
Performance benchmark suite (4 benchmarks, compare runs)
Mobile companion API (REST + JWT, mobile web UI)
140+ tests across all modules

🤝 Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

Fork the repository
Create your feature branch (git checkout -b feature/amazing)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing)
Open a Pull Request

Please read our Code of Conduct and Security Policy.

🐛 Troubleshooting

Ollama not running? Start it with ollama serve or verify it's running at http://localhost:11434.

Windows compatibility — NexusAgent uses sys.executable for sandboxed execution, ensuring cross-platform compatibility.

Import errors — Make sure you installed with pip install -e ".[all]" for all optional dependencies.

📄 License

This project is licensed under the MIT License — see the LICENSE file for details.

🙏 Acknowledgments

LiteLLM — Unified LLM API
NetworkX — GraphRAG memory backbone
Rich — Beautiful CLI output
Typer — CLI framework
FastAPI — Web dashboard framework
Ollama — Local LLM runtime

If you find NexusAgent useful, consider supporting its development:

👤 Author

Rudra Sarker

_{Built with ⚡ by Rudra Sarker}

More Open Source Projects

Project	Stars	Description
StealthHumanizer		Free AI text humanizer — 13 providers, no login
EdgeBrain		Edge AI inference — sub-100ms, no cloud
DevRoadmaps		17 career paths, 1700+ free resources
CodeVista		AI code analysis & security scanner
MindWell		Free mental health support platform
ScienceLab 3D		40+ virtual STEM experiments
SightlineAI		AI smart glasses for the blind