https://github.com/rudra496/nexus-agent
⚡ Nexus Agent — Zero-config, self-evolving local AI agent framework. Multi-agent orchestration, GraphRAG, IDE integration. Runs 100% local with Ollama.
https://github.com/rudra496/nexus-agent
ai ai-agent automation autonomous-agent benchmark cli cloud-sync code-agent docker graphrag hacktoberfest ide-integration llm local-ai marketplace multi-agent ollama open-source python self-evolving
Last synced: 8 days ago
JSON representation
⚡ Nexus Agent — Zero-config, self-evolving local AI agent framework. Multi-agent orchestration, GraphRAG, IDE integration. Runs 100% local with Ollama.
- Host: GitHub
- URL: https://github.com/rudra496/nexus-agent
- Owner: rudra496
- License: mit
- Created: 2026-04-17T19:49:46.000Z (2 months ago)
- Default Branch: main
- Last Pushed: 2026-06-05T18:40:45.000Z (12 days ago)
- Last Synced: 2026-06-05T20:17:05.910Z (11 days ago)
- Topics: ai, ai-agent, automation, autonomous-agent, benchmark, cli, cloud-sync, code-agent, docker, graphrag, hacktoberfest, ide-integration, llm, local-ai, marketplace, multi-agent, ollama, open-source, python, self-evolving
- Language: Python
- Homepage: https://rudra496.github.io/nexus-agent
- Size: 228 KB
- Stars: 5
- Watchers: 0
- Forks: 0
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
- Support: SUPPORT.md
- Roadmap: ROADMAP.md
Awesome Lists containing this project
README
⚡ 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
---
## Table of Contents
- [Features](#features)
- [Architecture](#architecture)
- [Installation](#installation)
- [Quick Start](#quick-start)
- [CLI Reference](#cli-reference)
- [Configuration](#configuration)
- [Plugin System](#plugin-system)
- [API Reference](#api-reference)
- [Enterprise Features](#enterprise-features)
- [Comparison](#comparison)
- [Performance](#performance)
- [Roadmap](#roadmap)
- [Contributing](#contributing)
- [License](#license)
- [Acknowledgments](#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
```mermaid
graph TB
CLI[CLI / Web Dashboard] --> Agent[NexusAgent Core]
Agent --> LiteLLM[LiteLLM Router]
LiteLLM --> Ollama[Ollama / OpenAI / Anthropic]
Agent --> Memory[GraphRAG Memory
NetworkX]
Agent --> Skills[Skill Tree
Auto-Generated Tools]
Agent --> Plugins[Plugin Manager
Hot-Reload]
Agent --> Sandbox[Sandbox Executor
Isolated Subprocess]
Config[Config Manager
YAML/JSON] --> Agent
Updater[Self-Updater
PyPI + Registry] --> Agent
Exporter[Export Engine
JSON / MD / ZIP] --> Agent
Memory --> Persist[(Local Storage
.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)
```bash
pip install nexus-agent
```
### pipx (Isolated)
```bash
pipx install nexus-agent
```
### Docker
```bash
docker pull rudra496/nexus-agent
docker run -it -v $(pwd):/workspace rudra496/nexus-agent run "Explain quantum computing"
```
### From Source
```bash
git clone https://github.com/rudra496/nexus-agent.git
cd nexus-agent
pip install -e .
```
> **Requires:** Python 3.10+ and [Ollama](https://ollama.ai/) for local models (optional for cloud models).
## 🚀 Quick Start
```bash
# 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 ` | Install a skill from marketplace |
| `nexus marketplace list` | List all available marketplace skills |
| `nexus benchmark run` | Run all performance benchmarks |
| `nexus benchmark compare ` | Compare two benchmark files |
| `nexus agents register --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).
```yaml
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](docs/configuration.md) for the full reference.
## 🔌 Plugin System
Extend NexusAgent with custom plugins. Drop a `.py` file in `.nexus/plugins/`:
```python
# .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
```
```bash
nexus plugin list # See loaded plugins
nexus plugin reload # Hot-reload changed plugins
```
See [docs/plugin-guide.md](docs/plugin-guide.md) for the full plugin development guide.
## 📖 API Reference
```python
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](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](docs/roadmap.md) for the full roadmap.
### ✅ v0.1 — Core Agent
- [x] GraphRAG memory with NetworkX
- [x] Auto skill generation
- [x] Basic CLI (`run`, `evolve`, `status`, `skills`)
- [x] LiteLLM multi-model support + Ollama
### ✅ v0.2 — Plugins & Dashboard
- [x] Configuration management (YAML/JSON)
- [x] Plugin system with hot-reload
- [x] Web dashboard (FastAPI + REST API)
- [x] Sandboxed execution (timeout, memory limits)
- [x] Export system (JSON, Markdown, ZIP skill packs)
- [x] Self-updater + skill registry
- [x] Docker support
- [x] CI/CD + tests
### ✅ v0.3 — Multi-Agent
- [x] Multi-agent orchestration engine
- [x] Task delegation and intelligent routing
- [x] Collaborative shared memory
- [x] Agent communication protocol (broadcast + direct messaging)
- [x] Agent roles (coder, reviewer, tester, planner, researcher)
- [x] Priority-based task queue with load balancing
### ✅ v0.4 — Voice & IDE
- [x] Voice interface (Whisper STT + pyttsx3/edge-tts TTS)
- [x] IDE integration base (JSON-RPC, VS Code manifest, JetBrains ready)
- [x] AST-aware code memory (functions, classes, imports, dependencies)
- [x] Context window management (token budgeting, priority selection)
- [x] `nexus voice` and `nexus analyze` CLI commands
### ✅ v1.0 — Production
- [x] Encrypted cloud sync (Fernet, local/S3/WebDAV, delta sync)
- [x] Audit logging & RBAC (JSON-lines, admin/user/viewer, log rotation)
- [x] Skill marketplace (search, install, rate, 6 categories)
- [x] Performance benchmark suite (4 benchmarks, compare runs)
- [x] Mobile companion API (REST + JWT, mobile web UI)
- [x] 140+ tests across all modules
## 🤝 Contributing
Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing`)
5. Open a Pull Request
Please read our [Code of Conduct](CODE_OF_CONDUCT.md) and [Security Policy](SECURITY.md).
## 🐛 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](LICENSE) file for details.
## 🙏 Acknowledgments
- [LiteLLM](https://github.com/BerriAI/litellm) — Unified LLM API
- [NetworkX](https://networkx.org/) — GraphRAG memory backbone
- [Rich](https://rich.readthedocs.io/) — Beautiful CLI output
- [Typer](https://typer.tiangolo.com/) — CLI framework
- [FastAPI](https://fastapi.tiangolo.com/) — Web dashboard framework
- [Ollama](https://ollama.ai/) — Local LLM runtime
## 💖 Sponsor
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](https://github.com/rudra496/StealthHumanizer) |  | Free AI text humanizer — 13 providers, no login |
| [EdgeBrain](https://github.com/rudra496/EdgeBrain) |  | Edge AI inference — sub-100ms, no cloud |
| [DevRoadmaps](https://github.com/rudra496/devroadmaps) |  | 17 career paths, 1700+ free resources |
| [CodeVista](https://github.com/rudra496/codevista) |  | AI code analysis & security scanner |
| [MindWell](https://github.com/rudra496/mindwell) |  | Free mental health support platform |
| [ScienceLab 3D](https://github.com/rudra496/sciencelab3d) |  | 40+ virtual STEM experiments |
| [SightlineAI](https://github.com/rudra496/sightlineai) |  | AI smart glasses for the blind |
---
**[⭐ Star this repo](../../stargazers) · [🍴 Fork it](../../fork) · [👤 Follow @rudra496](https://github.com/rudra496)**
## Connect
- [](https://github.com/rudra496)
- [](https://www.linkedin.com/in/rudrasarker)
- [](https://x.com/Rudra496)
- [](https://youtube.com/@rudrasarker9732)
- [](https://dev.to/rudra_sarker)