# Nexus

> Nexus is an autonomous CLI coding agent powered by LangGraph and MCP. It plans complex tasks, persists context via SQLite, and securely orchestrates tools. Features specialized Architect/Code modes, real-time metrics, and human-in-the-loop safety for production workflows.

- **Type:** MCP server
- **Install:** `agentstack add mcp-datarohit-nexus`
- **Verified:** Pending review
- **Seller:** [DataRohit](https://agentstack.voostack.com/s/datarohit)
- **Installs:** 0
- **Category:** [Databases](https://agentstack.voostack.com/c/databases)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [DataRohit](https://github.com/DataRohit)
- **Source:** https://github.com/DataRohit/Nexus
- **Website:** https://pypi.org/project/agent-nexus-cli/

## Install

```sh
agentstack add mcp-datarohit-nexus
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 🚀 Nexus

### **Elite Autonomous AI Coding Agent Powered by LangGraph & MCP**

[](https://github.com/DataRohit/nexus)
[](https://github.com/DataRohit/Nexus/blob/master/license)
[](#)

[](https://www.python.org/downloads/)
[](https://www.langchain.com/)
[](https://langchain-ai.github.io/langgraph/)
[](https://openai.com/)
[](https://modelcontextprotocol.io/)

[](https://rich.readthedocs.io/)
[](https://docs.pydantic.dev/)
[](https://github.com/astral-sh/ruff)
[](https://www.sqlalchemy.org/)

**An intelligent, autonomous CLI coding agent with multi-modal operational modes, persistent context management, and seamless MCP server integration for production workflows.**

[Features](#-key-features) • [Architecture](#-architecture) • [Installation](#-installation) • [Usage](#-usage) • [Documentation](#-documentation)

---

## 📋 Overview

**Nexus** is a cutting-edge autonomous AI coding agent built on top of LangChain and LangGraph, designed to revolutionize how developers interact with code. It combines the power of large language models with a sophisticated state machine architecture, enabling it to plan, execute, and iterate on complex coding tasks with minimal human intervention.

Unlike traditional AI assistants, Nexus features:
- **Multi-Modal Operations** - Switch between CODE, ARCHITECT, and ASK modes for different workflows
- **Persistent Context** - SQLite-based checkpoint system maintains conversation history across sessions
- **MCP Integration** - Dynamically loads and manages Model Context Protocol servers for extended capabilities
- **Human-in-the-Loop Safety** - Optional approval workflow for critical operations
- **Real-Time Metrics** - Track token usage, latency, and performance across conversations
- **Intelligent Tool Execution** - Validates and restricts tool usage based on operational mode

---

  ⚡ Project Showcase ⚡
  
  
  
    
      
      
    
    
      
      
    
     
      
      
    
  

---

## ✨ Key Features

### 🧠 **Intelligent Agent System**
- **LangGraph State Machine** - Sophisticated workflow management with conditional edges
- **Dynamic Tool Loading** - Automatic discovery and integration of MCP server tools
- **Context-Aware Reasoning** - Maintains conversation history with intelligent truncation
- **Iterative Planning** - Multi-step task execution with configurable iteration limits
- **Mode-Based Restrictions** - Tool validation and filtering based on current operational mode

### 🎯 **Multi-Modal Operations**

#### **CODE Mode** *(Full Access)*
- Complete file system operations (read, write, list)
- Shell command execution with safety checks
- Unrestricted access to all tools and MCP servers
- Ideal for implementation, debugging, and system tasks

#### **ARCHITECT Mode** *(Planning-Focused)*
- File operations restricted to `.nexus/plans/` directory
- Enforces architectural planning separation
- Prevents accidental modification of implementation code
- Perfect for design documents, technical specs, and planning

#### **ASK Mode** *(Research & Conversation)*
- Read-only access to information
- No file modifications or shell execution
- MCP tools only for research and analysis
- Optimal for learning, documentation, and Q&A

### 🛠️ **Built-In Tools**

#### **File Operations**
- `read_file` - Read file contents with optional line range selection
- `write_file` - Create or overwrite files with automatic directory creation
- `list_directory` - List directory contents respecting `.gitignore` patterns

#### **Shell Integration**
- `execute_shell_command` - Safe shell command execution with output capture
- Dangerous pattern detection (prevents destructive operations)
- Configurable timeout and output truncation
- Automatic blocking of redirections and pipes

#### **Mode Management**
- `switch_mode` - Dynamic mode switching between CODE, ARCHITECT, ASK
- Automatic validation and approval workflows
- Context-aware mode suggestions

#### **Web Search**
- `web_search` - DuckDuckGo integration for real-time information
- Configurable result limits
- Formatted output with titles, URLs, and descriptions

### 🔌 **Model Context Protocol (MCP) Support**
- **Dynamic Server Loading** - Automatically discovers and connects to MCP servers
- **Multi-Server Management** - Supports multiple concurrent MCP connections
- **Tool Auto-Discovery** - Dynamically loads tools from connected servers
- **Context Injection** - Automatically adds MCP tool descriptions to agent prompts
- **Flexible Configuration** - JSON-based server configuration in `.nexus/mcp_config.json`

### 📊 **Performance & Monitoring**
- **Real-Time Metrics Tracking** - Request latency, TTFT (Time to First Token), token usage
- **SQLite Metrics Storage** - Persistent performance data across sessions
- **Session Summaries** - Aggregated statistics per thread
- **Detailed Breakdowns** - Input/output tokens, cached tokens, total usage
- **Rich Visualizations** - Beautiful terminal tables and panels via Rich library

### 🎨 **Premium CLI Experience**
- **Rich Terminal UI** - Beautiful, responsive interface with Rich library
- **Streaming Responses** - Real-time token streaming with live updates
- **Markdown Rendering** - Full markdown support in agent responses
- **Syntax Highlighting** - Code blocks with syntax highlighting
- **Interactive Prompts** - User-friendly approval workflows
- **Progress Indicators** - Spinners and status messages for long operations

### 🔒 **Safety & Validation**
- **Human-in-the-Loop** - Optional approval for all tool executions
- **Mode Validation** - Tools validated against current operational mode
- **Path Restrictions** - Enforced directory boundaries in ARCHITECT mode
- **Dangerous Pattern Detection** - Blocks potentially harmful shell commands
- **Gitignore Compliance** - Respects `.gitignore` patterns in file operations

### 💾 **Persistence & Configuration**
- **Checkpoint System** - SQLite-based conversation state persistence
- **Thread Management** - Multiple concurrent conversation threads
- **Custom Prompts** - Load custom system prompts from `.nexus/prompts/`
- **Rule Enforcement** - User-defined rules from `.nexus/rules/`
- **Environment-Based Config** - Pydantic settings with `.env` support

---

## 🏛️ Architecture

```mermaid
graph TB
    subgraph "User Interface Layer"
        CLI[Rich CLI Interface]
        Commands[Slash Commands]
        Prompts[Interactive Prompts]
    end
    
    subgraph "Agent Core"
        Graph[LangGraph State Machine]
        Agent[Agent Node]
        Tools[Tool Node]
        Approval[Approval Node]
    end
    
    subgraph "Tool System"
        FileOps[File Operations]
        Shell[Shell Commands]
        Mode[Mode Management]
        Search[Web Search]
        MCP[MCP Tools]
    end
    
    subgraph "State Management"
        Checkpoint[SQLite Checkpointer]
        State[Agent State]
        Metrics[Metrics Manager]
    end
    
    subgraph "Configuration"
        Settings[Pydantic Settings]
        Prompts_Config[Custom Prompts]
        Rules[User Rules]
        MCP_Config[MCP Servers]
    end
    
    subgraph "External Services"
        OpenAI[OpenAI API]
        MCP_Servers[MCP Servers]
        LangSmith[LangSmith Tracing]
    end
    
    CLI --> Graph
    Commands --> Agent
    Prompts --> Approval
    
    Graph --> Agent
    Graph --> Tools
    Graph --> Approval
    
    Agent --> FileOps
    Agent --> Shell
    Agent --> Mode
    Agent --> Search
    Agent --> MCP
    
    Agent --> State
    State --> Checkpoint
    Agent --> Metrics
    
    Settings --> Agent
    Prompts_Config --> Agent
    Rules --> Agent
    MCP_Config --> MCP
    
    Agent --> OpenAI
    MCP --> MCP_Servers
    Agent --> LangSmith
```

### **Agent Workflow**

1. **User Input** - Message entered via Rich CLI interface
2. **State Initialization** - Current state loaded from SQLite checkpoint
3. **Agent Reasoning** - LLM processes input with system prompt and context
4. **Tool Selection** - Agent decides which tools to use based on mode
5. **Approval (Optional)** - Human approval requested for tool execution
6. **Tool Execution** - Selected tools execute with validated parameters
7. **State Update** - New state persisted to checkpoint database
8. **Response Streaming** - Real-time token streaming back to user
9. **Metrics Logging** - Performance data saved to metrics database

---

## 🔧 Tech Stack

### **Core Framework**
| Technology | Version | Purpose |
|------------|---------|----------|
| Python | 3.14.2 | Programming Language |
| LangChain | 1.2.7 | LLM Framework |
| LangChain Core | 1.2.7 | Core Abstractions |
| LangChain Community | 0.4.1 | Community Components |
| LangChain OpenAI | 1.1.7 | OpenAI Integration |
| LangGraph | 1.0.7 | State Machine Framework |
| LangGraph Checkpoint | 4.0.0 | Checkpointing System |
| LangGraph Checkpoint SQLite | 3.0.3 | SQLite Checkpointer |
| LangGraph Prebuilt | 1.0.7 | Pre-built Nodes |

### **AI & ML**
| Technology | Version | Purpose |
|------------|---------|----------|
| OpenAI | 2.15.0 | LLM Provider |
| Tiktoken | 0.12.0 | Token Counting |
| LangSmith | 0.6.4 | Tracing & Debugging |

### **Data & Storage**
| Technology | Version | Purpose |
|------------|---------|----------|
| SQLAlchemy | 2.0.46 | ORM & Database Toolkit |
| aiosqlite | 0.22.1 | Async SQLite Driver |
| Pydantic | 2.12.5 | Data Validation |
| Pydantic Core | 2.41.5 | Core Validation Logic |
| Pydantic Settings | 2.12.0 | Settings Management |

### **CLI & UI**
| Technology | Version | Purpose |
|------------|---------|----------|
| Rich | 14.2.0 | Terminal UI Framework |
| Rich Click | 1.9.6 | Click Integration for Rich |
| Structlog | 25.5.0 | Structured Logging |

### **MCP & Tools**
| Technology | Version | Purpose |
|------------|---------|----------|
| MCP | 1.25.0 | Model Context Protocol |
| LangChain MCP Adapters | 0.2.1 | MCP-LangChain Bridge |
| DDGS | 9.10.0 | DuckDuckGo Search |
| Pathspec | 1.0.3 | Gitignore Pattern Matching |

### **Utilities**
| Technology | Version | Purpose |
|------------|---------|----------|
| HTTPX | 0.28.1 | HTTP Client |
| Requests | 2.32.5 | HTTP Requests |
| Python-dotenv | 1.2.1 | Environment Variables |
| PyYAML | 6.0.3 | YAML Parser |
| Tenacity | 9.1.2 | Retry Logic |
| Orjson | 3.11.5 | Fast JSON |

### **Development Tools**
| Technology | Version | Purpose |
|------------|---------|----------|
| Ruff | 0.14.14 | Linting & Formatting |
| isort | 7.0.0 | Import Sorting |
| Setuptools | 80.10.1+ | Package Building |
| Wheel | 0.46.3+ | Package Distribution |

---

## 📁 Project Structure

```
nexus/
├── .agent/                       # Agent configuration (legacy)│   
│   └── rules/                    # Coding standards
├── .github/                      # GitHub workflows
│   └── workflows/               # CI/CD pipelines
│       ├── ci.yml              # Continuous integration
│       ├── publish.yml         # PyPI publishing
│       └── release.yml         # Release automation
├── .nexus/                       # Nexus configuration directory
│   ├── db/                      # SQLite databases
│   │   ├── checkpoints.db      # Conversation checkpoints
│   │   └── metrics.db          # Performance metrics
│   ├── plans/                   # Architectural plans (ARCHITECT mode)
│   ├── prompts/                 # Custom system prompts
│   │   ├── system_prompt.md    # Main system prompt
│   │   ├── code_review_prompt.md
│   │   └── code_generation_prompt.md
│   ├── rules/                   # User-defined rules
│   │   └── python-code-documentation.md
│   └── mcp_config.json         # MCP server configuration
├── nexus/                        # Main package directory
│   ├── agent/                   # Agent core components
│   │   ├── approval.py         # Human approval workflow
│   │   ├── graph.py            # LangGraph state machine
│   │   ├── metrics.py          # Performance tracking
│   │   ├── modes.py            # Operational mode definitions
│   │   ├── nodes.py            # Graph node implementations
│   │   ├── restrictions.py     # Mode-based validation
│   │   ├── state.py            # Agent state definition
│   │   └── __init__.py
│   ├── commands/                # Slash command system
│   │   ├── base.py             # Command protocol
│   │   ├── core.py             # Core command implementations
│   │   ├── registry.py         # Command registry
│   │   └── __init__.py
│   ├── config/                  # Configuration management
│   │   ├── prompts.py          # Prompt loading & management
│   │   ├── settings.py         # Pydantic settings
│   │   └── __init__.py
│   ├── tools/                   # LangChain tool implementations
│   │   ├── file_ops.py         # File operation tools
│   │   ├── mcp.py              # MCP server management
│   │   ├── mode.py             # Mode switching tool
│   │   ├── shell.py            # Shell command tool
│   │   ├── web_search.py       # Web search tool
│   │   └── __init__.py
│   ├── ui/                      # User interface
│   │   ├── cli.py              # Rich-Click CLI
│   │   ├── console.py          # Rich console instance
│   │   └── __init__.py
│   ├── main.py                  # Application entry point
│   └── __init__.py
├── .editorconfig                # Editor configuration
├── .env.example                 # Example environment file
├── .gitattributes               # Git attributes
├── .gitignore                   # Git ignore patterns
├── .python-version              # Python version file
├── contributors.txt             # Project contributors
├── license                      # MIT License
├── pyproject.toml              # Project configuration & dependencies
└── readme.md                    # This file
```

---

## 🚀 Installation

### **Prerequisites**

- **Python 3.14.2+** - Latest Python release
- **Git** - Version control system
- **OpenAI API Key** - For LLM access
- **pip** or **uv** - Package manager

### **Quick Install**

```bash
# Clone the repository
git clone https://github.com/DataRohit/nexus.git
cd nexus

# Create virtual environment
python -m venv .venv

# Activate virtual environment
# On Windows (Git Bash)
source .venv/Scripts/activate

# On Windows (PowerShell)
.venv\Scripts\Activate.ps1

# On Linux/macOS
source .venv/bin/activate

# Install dependencies
pip install -e .

# Or with uv (faster)
uv pip install -e .
```

### **Configuration**

1. **Create Environment File**
```bash
cp .env.example .env
```

2. **Edit `.env` with your settings**
```bash
# OpenAI Configuration
OPENAI_API_KEY=sk-your-api-key-here
OPENAI_BASE_URL=https://api.openai.com/v1

# Model Settings
MODEL_NAME=gpt-4o
TEMPERATURE=0.7
MAX_TOKENS=4096

# LangSmith (Optional)
LANGSMITH_API_KEY=ls__your-api-key-here
LANGSMITH_PROJECT=nexus
LANGSMITH_TRACING=true

# Agent Settings
MAX_ITERATIONS=50
APPROVAL_REQUIRED=true

# Logging
LOG_LEVEL=INFO
DEBUG=false
```

3. **Configure MCP Servers (Optional)**

Create `.nexus/mcp_config.json`:
```json
{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp"]
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/directory"]
    }
  }
}
```

### **Verify Installation**

```bash
# Check installation
nexus --version

# Run help
nexus --help

# Start interactive chat
nexus chat
```

---

## 💻 Usage

### **Basic Commands**

```bash
# Start interactive chat session
nexus chat

# Chat with specific thread ID
nexus chat --thread-id my-project

# Disable streaming (static responses)
nexus chat --no-stream

# Send single message
nexus chat "Explain async/await in Python"

# View conversation history
nexus history --thread-id default --limit 10

# Show configuration
nexus config
```

### **Interactive Chat**

```bash
$ nexus chat

╭──────────────────────────────────────────────────╮
│ NEXUS - AI Coding Agent                          │
│ Powered by LangChain & LangGraph                 │
╰─────

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [DataRohit](https://github.com/DataRohit)
- **Source:** [DataRohit/Nexus](https://github.com/DataRohit/Nexus)
- **License:** MIT
- **Homepage:** https://pypi.org/project/agent-nexus-cli/

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: flagged — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-datarohit-nexus
- Seller: https://agentstack.voostack.com/s/datarohit
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.