Nexus

🚀 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

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

# 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

cp .env.example .env

1. Edit .env with your settings

# 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

1. Configure MCP Servers (Optional)

Create .nexus/mcp_config.json:

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

Verify Installation

# Check installation
nexus --version

# Run help
nexus --help

# Start interactive chat
nexus chat

---

💻 Usage

Basic Commands

# 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

$ 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.