自动化编码代理

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

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

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

cp .env.example .env

# 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

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

# Check installation
nexus --version

# Run help
nexus --help

# Start interactive chat
nexus chat

# 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

$ nexus chat

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

╭───────────── Session ──────────────╮
│ Model      : gpt-4o                │
│ Mode       : CODE                  │
│ Thread     : default               │
│ Working Dir: /path/to/project      │
│ Streaming  : Enabled               │
╰────────────────────────────────────╯

> How do I create a FastAPI endpoint?

[Agent responds with streaming output...]

> exit

/help       # Show all available commands
/about      # Application information
/config     # Show current configuration
/mcps       # Display active MCP servers and tools
/mode       # Switch operational mode
/metrics    # Show session performance metrics

# Switch to ARCHITECT mode for planning
/mode architect

# Switch to CODE mode for implementation
/mode code

# Switch to ASK mode for conversation
/mode ask

# Check current mode
/mode

# Start in ARCHITECT mode
/mode architect

> Create a design document for a REST API with authentication

[Agent creates planning documents in .nexus/plans/]

# Switch to CODE mode
/mode code

> Implement the authentication system we designed

[Agent creates implementation files]

> Review this Python code for security issues:
> [paste code]

[Agent provides detailed code review]

/mode ask

> What are the latest best practices for React Server Components?

[Agent searches web and provides summary]

# Required
OPENAI_API_KEY=sk-...              # OpenAI API key

# Optional
OPENAI_BASE_URL=...                # Custom API endpoint
MODEL_NAME=gpt-4o                  # LLM model to use
TEMPERATURE=0.7                    # Response randomness (0-2)
MAX_TOKENS=4096                    # Max response length
MAX_ITERATIONS=50                  # Max agent iterations
APPROVAL_REQUIRED=true             # Require approval for tools
LOG_LEVEL=INFO                     # Logging verbosity
DEBUG=false                        # Debug mode

{
  "mcpServers": {
    "server-name": {
      "command": "command-to-run",
      "args": ["arg1", "arg2"],
      "env": {
        "ENV_VAR": "value"
      }
    }
  }
}

# Read file
read_file(path="example.py")
read_file(path="example.py", start_line=10, end_line=20)

# Write file
write_file(path="new_file.py", content="print('Hello')")
write_file(path="nested/file.py", content="...", create_dirs=True)

# List directory
list_directory(path="src")
list_directory(path=".", recursive=True)
list_directory(path=".", include_gitignored=True)

# Execute command
execute_shell_command(command="ls -la")
execute_shell_command(command="python script.py", timeout=60)

# Safety features
# - Blocks dangerous patterns (rm -rf /, etc.)
# - No support for redirections or pipes
# - Output truncation for large outputs

# Search web
web_search(query="Python async best practices")
web_search(query="FastAPI tutorial", max_results=10)

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "ghp_your_token_here"
      }
    }
  }
}

/metrics

┌──────────────────────────────────────────┐
│         Session Metrics Summary          │
├──────────────────────┬───────────────────┤
│ Metric               │ Value             │
├──────────────────────┼───────────────────┤
│ Total Requests       │ 15                │
│ Total Latency        │ 45.32s            │
│ Avg Latency          │ 3.02s             │
│ Avg TTFT             │ 0.85s             │
├──────────────────────┼───────────────────┤
│ Total Input Tokens   │ 12,450            │
│ Total Output Tokens  │ 8,320             │
│ Total Tokens         │ 20,770            │
│ Total Cached Tokens  │ 3,200             │
└──────────────────────┴───────────────────┘

rm -rf /                    # Recursive deletion from root
:(){ :|:& };:               # Fork bomb
mkfs                        # Filesystem creation

Tool Execution Pending Approval

  Tool: write_file
  Action: Write content to file
  Parameters: path, content, ... (use 'd' to view details)

Approve? [y/n/d] (y):

# Custom System Identity

You are a specialized Python expert...

## Core Capabilities
- Expert in async/await patterns
- Django and FastAPI specialist
...

# Coding Standards

## Python
- Use type hints everywhere
- Maximum line length: 120 characters
- Follow PEP 8 with Ruff
...

# OpenAI
OPENAI_API_KEY              # Required: OpenAI API key
OPENAI_BASE_URL             # Optional: Custom API endpoint

# Model
MODEL_NAME                  # Default: gpt-4o
TEMPERATURE                 # Default: 0.7 (range: 0-2)
MAX_TOKENS                  # Default: 4096

# LangSmith
LANGSMITH_API_KEY           # Optional: LangSmith API key
LANGSMITH_PROJECT           # Default: nexus
LANGSMITH_TRACING           # Default: true

# Agent
MAX_ITERATIONS              # Default: 50
APPROVAL_REQUIRED           # Default: true

# Logging
LOG_LEVEL                   # Default: INFO
DEBUG                       # Default: false

# Check if command exists
which npx  # or npm, uv, python

# Test MCP server manually
npx -y @upstash/context7-mcp

# Check logs
DEBUG=true nexus chat

# Verify API key
echo $OPENAI_API_KEY

# Test with different model
MODEL_NAME=gpt-3.5-turbo nexus chat

# Check base URL
OPENAI_BASE_URL=https://api.openai.com/v1 nexus chat

# ARCHITECT mode file write failure
# Solution: Ensure path is in .nexus/plans/

# ASK mode tool restriction
# Solution: Switch to CODE mode (/mode code)

# Multiple instances running
# Solution: Close other Nexus instances

# Corrupted database
rm .nexus/db/checkpoints.db
# Restart Nexus (creates new database)

DEBUG=true LOG_LEVEL=DEBUG nexus chat

# Delete all configuration
rm -rf .nexus/

# Restart to regenerate defaults
nexus chat

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

# Install with dev dependencies
pip install -e ".[dev]"

# Or with uv
uv pip install -e ".[dev]"

# Lint code
ruff check .

# Format code
ruff format .

# Fix auto-fixable issues
ruff check --fix .

# Sort imports
isort .

git fork https://github.com/DataRohit/nexus.git

git checkout -b feature/amazing-feature

git commit -m "Add amazing feature"

git push origin feature/amazing-feature

# 1. Setup development environment
pip install -e ".[dev]"

# 2. Make changes
# ... edit files ...

# 3. Run linting
ruff check .
ruff format .

# 4. Test changes
nexus chat

# 5. Commit
git add .
git commit -m "Description of changes"

# 6. Push and create PR
git push origin feature-branch

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.