Metadata-Version: 2.4
Name: agent-nexus-cli
Version: 0.1.2
Summary: Nexus Is A CLI-Based AI Coding Agent That Transforms Natural Language Into Efficient, Production-Ready Code!
Author-email: Rohit Vilas Ingole <rohit.vilas.ingole@gmail.com>
License: # The MIT License
        
        The MIT License
        
        Copyright 2026 Rohit Vilas Ingole <rohit.vilas.ingole@gmail.com>
        
        Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
        
Project-URL: Homepage, https://github.com/datarohit/nexus
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.14.2
Description-Content-Type: text/markdown
Requires-Dist: aiosqlite==0.22.1
Requires-Dist: httpx==0.28.1
Requires-Dist: langchain==1.2.7
Requires-Dist: langchain-community==0.4.1
Requires-Dist: langchain-core==1.2.7
Requires-Dist: langchain-mcp-adapters==0.2.1
Requires-Dist: langchain-openai==1.1.7
Requires-Dist: langgraph==1.0.7
Requires-Dist: langgraph-checkpoint==4.0.0
Requires-Dist: langgraph-checkpoint-sqlite==3.0.3
Requires-Dist: langgraph-prebuilt==1.0.7
Requires-Dist: langgraph-sdk==0.3.3
Requires-Dist: langsmith==0.6.4
Requires-Dist: mcp==1.25.0
Requires-Dist: openai==2.15.0
Requires-Dist: orjson==3.11.5
Requires-Dist: pathspec==1.0.3
Requires-Dist: pydantic==2.12.5
Requires-Dist: pydantic-core==2.41.5
Requires-Dist: pydantic-settings==2.12.0
Requires-Dist: python-dotenv==1.2.1
Requires-Dist: pyyaml==6.0.3
Requires-Dist: requests==2.32.5
Requires-Dist: rich==14.2.0
Requires-Dist: rich-click==1.9.6
Requires-Dist: sqlalchemy==2.0.46
Requires-Dist: structlog==25.5.0
Requires-Dist: tenacity==9.1.2
Requires-Dist: tiktoken==0.12.0
Provides-Extra: dev
Requires-Dist: isort==7.0.0; extra == "dev"
Requires-Dist: ruff==0.14.14; extra == "dev"
Requires-Dist: ty==0.0.13; extra == "dev"

# Nexus - AI Coding Agent

**Nexus is a modern, CLI-based AI coding agent that transforms natural language into efficient, production-ready code.**

Powered by **LangChain**, **LangGraph**, and **LangSmith**, Nexus provides a persistent, stateful coding assistant with advanced capabilities like human-in-the-loop approvals, full observability, and the **Model Context Protocol (MCP)** for extensible tooling.

⚡ Project Showcase ⚡
  Nexus Hero

       Showcase 2
       Showcase 3

       Showcase 4
       Showcase 5

       Showcase 6
       Showcase 7

## ✨ Features

- 🔄 **Stateful Conversations** - Persistent conversation history with SQLite checkpointing.
- 🔌 **Model Context Protocol (MCP)** - Connect external tools using the open standard MCP.
- 🛠️ **Powerful Built-in Tools** - File operations, shell commands, and code analysis.
- 👤 **Human-in-the-Loop** - Secure approval workflows (`y/n/d`) for tool execution.
- 🛡️ **Operational Modes** - Security-focused CODE, ARCHITECT, and ASK modes.
- 📉 **Intelligent Guidance** - Context-aware mode switch suggestions and agent-initiated transitions.

- 🚀 **Production-Ready** - Built with modern best practices, type safety, and structured logging.

## 🏗️ Architecture

Nexus is built on a robust stack:

- **LangChain** - Orchestration and tool integration.
- **LangGraph** - State machine for reliable agent workflows.
- **LangSmith** - Observability, tracing, and evaluation.
- **MCP (Model Context Protocol)** - Standardized connection to external data and tools.
- **Rich-Click** - Modern, beautiful CLI interface.
- **Pydantic** - Strict configuration and validation.
- **SQLite** - Local persistence for conversation threads.

## 📋 Prerequisites

- Python 3.10+
- OpenAI API key
- (Optional) LangSmith API key for tracing
- (Optional) Docker/Node.js for specific MCP servers

## 🚀 Installation

1. **Clone the repository:**

   ```bash
   git clone https://github.com/datarohit/nexus.git
   cd nexus
   ```

2. **Create and activate virtual environment:**

   ```bash
   # Using uv (recommended)
   uv venv
   source .venv/Scripts/activate  # Windows (Git Bash)
   
   # Or using standard venv
   python -m venv .venv
   source .venv/Scripts/activate
   ```

3. **Install dependencies:**

   ```bash
   # Using uv (fastest)
   uv pip install -e .
   
   # Or using pip
   pip install -e .
   ```

4. **Configure environment:**

   Copy the example environment file:

   ```bash
   cp .env.example .env
   ```

   Edit `.env` with your keys:

   ```env
   OPENAI_API_KEY=sk-...
   LANGSMITH_API_KEY=ls__...  # Optional
   LANGSMITH_PROJECT=nexus
   LANGSMITH_TRACING=true
   ```

## 🔌 Model Context Protocol (MCP)

Nexus supports the Model Context Protocol, allowing you to easily extend its capabilities with external servers.

### Configuration

Create or edit `.nexus/mcp_config.json` in your project root to define servers.

**Example Configuration:**

```json
{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp"]
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "C:/Projects"]
    }
  }
}
```

Nexus automatically loads these servers, counts their tools, and injects their descriptions into the agent's system prompt so it knows exactly how to use them.

## 🎭 Multi-Mode System

Nexus supports three operational modes to provide structure and safety during complex tasks:

| Mode | Allowed Tools | File Access | Description |
| :--- | :--- | :--- | :--- |
| **CODE** | All tools | Unrestricted | Full access for implementation and debugging. |
| **ARCHITECT** | All tools | `.nexus/plans/` | Restricted mode for project planning and design. |
| **ASK** | MCP Tools | None | Conversation-only mode for questions and research. |

Nexus defaults to **CODE** mode. When a restricted action is attempted, Nexus will intelligently suggest a mode switch. The agent can also programmatically request a mode change via the `switch_mode` tool when it recognizes a shift in task requirements.

## 💻 Usage

### Interactive Chat

Start the agent in interactive mode:

```bash
nexus chat
```

You will see a dashboard showing the active session, loaded prompts, rules, and connected MCP servers.

**Slash Commands:**
While in chat mode, you can use the following slash commands:

- `/help` - Show all available commands.
- `/mode <name>` - Switch between `code`, `architect`, and `ask`.
- `/config` - View configuration and the active operational mode.

- `/mcps` - List active MCP servers and their tools.
- `/about` - Show application information.

### Command Line Mode

Send a single instruction without entering interactive mode:

```bash
nexus chat "Refactor main.py to use async/await"
```

### Thread Management

Maintain context across sessions using thread IDs:

```bash
nexus chat --thread-id feature-auth "Add login endpoint"
nexus chat --thread-id feature-auth "Now add logout"
```

### View History

Review past conversations:

```bash
nexus history --thread-id feature-auth
```

### Configuration Check

Verify your settings and loaded components:

```bash
nexus config
```

## 🏗️ Project Structure

```text
nexus/
├── nexus/
│   ├── agent/          # Core agent logic
│   │   ├── graph.py    # LangGraph definition & tool loading
│   │   ├── nodes.py    # Agent reasoning & approval nodes
│   │   ├── state.py    # State schema
│   │   ├── modes.py    # Mode definitions & configs
│   │   ├── restrictions.py # Tool restriction logic
│   │   └── approval.py # Interactive approval workflow
│   │
│   ├── tools/          # Tool definitions
│   │   ├── mcp.py      # MCP client & configuration handler
│   │   ├── file_ops.py # Built-in file tools
│   │   ├── shell.py    # Built-in shell tools
│   │   └── mode.py     # Mode management tools

│   │
│   ├── config/         # Configuration
│   │   ├── settings.py # Pydantic settings
│   │   └── prompts.py  # System prompts
│   │
│   ├── ui/             # Terminal Interface
│   │   ├── cli.py      # CLI entry point & UI components
│   │   └── console.py  # Rich console instance
│   │
│   └── main.py         # App entry point
│
├── .nexus/             # Local config directory
│   ├── mcp_config.json # MCP server definitions
│   └── prompts/        # Custom user prompts
│
└── readme.md           # Documentation
```

## ⚙️ Configuration Variables

| Variable | Description | Default |
| :--- | :--- | :--- |
| `OPENAI_API_KEY` | OpenAI API key | Required |
| `OPENAI_BASE_URL` | OpenAI base URL | None |
| `LANGSMITH_TRACING` | Enable tracing | true |
| `LOG_LEVEL` | Logging verbosity | INFO |
| `CHECKPOINT_DB` | SQLite DB path | checkpoints.db |

## 🤝 Contributing

Contributions are welcome! Please follow the code style guidelines:

1. Use **Ruff** for linting.
2. Use **MyPy/Ty** for type checking.
3. Ensure all functions have docstrings.

```bash
ruff check .
```

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](https://github.com/DataRohit/Nexus/blob/master/LICENSE) file for details.

## 🙏 Acknowledgments

- **LangChain & LangGraph** for the agent framework.
- **Anthropic & MCP Team** for the Model Context Protocol standard.
- **Rich** for the terminal UI.

---

### Made with ❤️ by Rohit Vilas Ingole
