███╗   ██╗███████╗ ██████╗    ██████╗ ██████╗ ██████╗ ███████╗██████╗ 
 ████╗  ██║██╔════╝██╔═══██╗  ██╔════╝██╔═══██╗██╔══██╗██╔════╝██╔══██╗
 ██╔██╗ ██║█████╗  ██║   ██║  ██║     ██║   ██║██║  ██║█████╗  ██████╔╝
 ██║╚██╗██║██╔══╝  ██║   ██║  ██║     ██║   ██║██║  ██║██╔══╝  ██╔══██╗
 ██║ ╚████║███████╗╚██████╔╝  ╚██████╗╚██████╔╝██████╔╝███████╗██║  ██║
 ╚═╝  ╚═══╝╚══════╝ ╚═════╝    ╚═════╝ ╚═════╝ ╚═════╝ ╚══════╝╚═╝  ╚═╝

Scalable AI coding agent built on a modular SDK for real-world software engineering tasks

Installation • Quick Start • Features • Workflow Mode • Code Review • Configuration • MCP Server • LiveBench Leaderboard

---

📊 LiveBench Performance

⚡ Efficiency Comparison in real world COMPLEX task:

Tip

neoCoder achieves the same results with 2.6x fewer tokens and API calls**

---

Top-5 Models (Global Average)

Rank	Model	Organization	Global Avg	Reasoning	Coding	Agentic	Math	Language
🏆	NeoCoder Agent 4.6 Opus	neoCoder	80.49	90.24	84.28	74.92	92.50	83.27
🥇	Claude Code 4.6 Opus	Anthropic	76.33	88.67	78.18	61.67	89.32	83.27
🥈	Claude Code 4.5 Opus	Anthropic	75.96	80.09	79.65	63.33	90.39	81.26
🥉	Claude 4.6 Sonnet Thinking	Anthropic	75.47	84.77	79.27	60.00	86.99	76.10
4	GPT-5.2 High	OpenAI	74.84	83.21	76.07	51.67	93.17	79.81
5	GPT-5.2 Codex	OpenAI	74.30	77.71	83.62	51.67	88.77	73.68

Evaluation Categories: 🧩 Reasoning • 💻 Coding • 🤖 Agentic Coding • 🔢 Mathematics • 📊 Data Analysis • 🗣️ Language • 📝 IF

📋 View full leaderboard (30+ models) →

✨ Key Features

Feature	Description
🧠 Orchestrator	Core agent loop with iterative reasoning and action execution
🔧 Extensions	Modular tool system (bash, file editing, code search)
💾 Memory Management	Hierarchical working memory with context compression
🎯 Multiple Modes	Coding, debugging, and refactoring modes
🚀 Workflow Preset	7-stage professional engineering pipeline with planning & testing
✅ Auto Code Review	Checks anti-patterns, bottlenecks, best practices & pitfalls on save
🖥️ Cross-Platform	Full support for Windows, Linux, and macOS
🔌 MCP Integration	Use as MCP server in Claude Code

---

📦 Installation

Note

Requires Python 3.10+ and pip

# Clone and install
cd neoCoder
pip install -e .

# With development dependencies
pip install -e ".[dev]"

# With MCP server support
pip install -e ".[mcp]"

---

🚀 Quick Start

Tip

Quick start in 3 steps: install → set API key → run

1️⃣ Initialize Configuration

neocoder \init-config          # Create example configuration

2️⃣ Set API Key

Important

API key from Anthropic or ZenMux is required

🪟 Windows CMD

set ANTHROPIC_API_KEY=your-key
set ZENMUX_API_KEY=your-key

💠 Windows PowerShell

$env:ANTHROPIC_API_KEY="your-key"
$env:ZENMUX_API_KEY="your-key"

🐧 Linux / macOS

export ANTHROPIC_API_KEY=your-key
export ZENMUX_API_KEY=your-key

3️⃣ Run

# Interactive mode
neocoder

# Single task
neocoder "Create a Python hello world script"

# With options
neocoder --mode debug "Fix test_api.py"
neocoder --preset thorough "Refactor auth module"

---

💻 Usage

Basic Commands

Command	Description
neocoder	Interactive mode
neocoder "task"	Execute single task
neocoder --help	Show help
neocoder \help	Show system commands
neocoder \version	Show version

✨ Professional Engineering Mode (Workflow Preset) ✨

The workflow preset is a production-grade, 7-stage development process with automatic planning, testing, and code review - designed for complex engineering tasks.

neocoder --preset workflow "your complex task"

7-Stage Engineering Pipeline:

Stage	Description	Auto-Approve
1️⃣ Problem Breakdown	Decomposes task into subtasks with dependencies	❌ Requires approval
2️⃣ Implementation Plan	Creates detailed step-by-step plan	❌ Requires approval
3️⃣ Implementation	Executes the plan with file operations	✅ Auto-proceeds
4️⃣ Integration Testing	Runs automated tests with retry logic	✅ Auto-proceeds
5️⃣ Tech Stack Review	Validates against best practices	✅ Auto-proceeds
6️⃣ Code Review	Automated review using project rules	✅ Auto-proceeds
7️⃣ Merge Preparation	Generates commit-ready summary	✅ Auto-proceeds

Key Features:

• 🔄 Stateful execution - Resume interrupted workflows
• 📊 Extended context - 16K tokens, 250 iterations
• 🎯 Deterministic - Temperature 0.0 for consistency
• 🔍 Quality gates - Automatic testing and code review
• 📝 Conventional commits - Auto-generated commit messages

Example Usage:

# Start a complex feature
neocoder --preset workflow "Add OAuth2 authentication with JWT tokens"

# Resume if interrupted (state is saved)
neocoder --preset workflow "Add OAuth2 authentication with JWT tokens"
# Prompt: Continue from previous state? (y/n)

# Reset workflow state
neocoder workflow reset

Real Complex Example

neocoder --preset workflow "Design a full-stack web application for a cryptocurrency trading bot dashboard.
The application should allow users to monitor their bot's performance in real-time, including current holdings, profit/loss, open trades, and historical performance data visualized through interactive charts.
Users should be able to configure trading parameters, such as risk tolerance, stop-loss levels, and take-profit targets, through an intuitive interface.
The application should feature secure authentication and authorization, protecting user data and trading credentials.
The backend should be built using Node.js with Express.js, utilizing a PostgreSQL database for data persistence.
The frontend should be built using React, with a clean and modern design emphasizing data visualization and ease of use.
The application should include robust error handling and logging capabilities.
The deployment should be considered, suggesting a suitable cloud platform and deployment strategy.
Provide the complete codebase, including frontend, backend, and database schema, ready for deployment.
The application should be named 'LovableBotDashboard'"

When to use Workflow Preset:

• ✅ Complex features requiring multiple files
• ✅ Refactoring with extensive testing
• ✅ Production-critical changes
• ✅ Team projects with code review requirements
• ❌ Quick fixes or single-file changes (use default mode)

---

Standard Presets

# Fast mode - Quick iterations
neocoder --preset fast "Fix the login bug"

# Thorough mode - Extended analysis
neocoder --preset thorough "Refactor auth module"

Workflow Commands

neocoder --preset workflow "your task"    # Run with workflow preset
neocoder workflow status                   # Check workflow status
neocoder workflow reset                    # Reset workflow state

System Commands

💡 Use backslash \ for system commands

neocoder \init-config    # Create configuration
neocoder \help           # Show system commands  
neocoder \version        # Show version

---

⚙️ Configuration

Configuration files are stored in ~/.neoCoder/:

~/.neoCoder/
├── 📄 settings.json        # Agent configuration
├── 📄 models.json          # Model definitions
├── 📄 tool_selection.json  # Tool selection settings
└── 📁 notes/               # Persistent notes from sessions

Environment Variables

Variable	Description
ANTHROPIC_API_KEY	Official Anthropic API key
ZENMUX_API_KEY	ZenMux API key (default)
NEOCODER_BASE_URL	Custom API endpoint
NEOCODER_CONFIG	Custom config path

---

✅ Automatic Code Review

neoCoder automatically reviews your code on every file save with a comprehensive 4-tier quality check:

Review Priority Order

Priority	Check	Description
1️⃣	Anti-Patterns	God Objects, Spaghetti Code, Shotgun Surgery
2️⃣	Bottlenecks	N+1 queries, sync I/O in loops, inefficient operations
3️⃣	Best Practices	Missing docstrings, mutable defaults, proper comparisons
4️⃣	Pitfalls	Broad exception catching, assert misuse, list modification

Additional Checks

• 🔒 Security: Hardcoded secrets, SQL injection, eval/exec usage
• 🐛 Syntax: Parse errors, invalid code
• 📊 Complexity: Cyclomatic complexity, nesting depth
• 🎨 Style: Code duplication, magic numbers, dead code

Example Output:

✓ Code Review: Score 85/100, 2 issue(s)
[critical] No Anti-Patterns (line 45): God Object: Class 'UserManager' has 25 methods (>20)
  → Fix: Split into smaller, focused classes (Single Responsibility Principle)

Configuration: Code review rules can be customized in .neoCoder/code_review_config.json

---

🔌 MCP Integration

Warning

MCP server requires separate installation: pip install -e ".[mcp]"

Run neoCoder as an MCP server for Claude Code:

neocoder-mcp
# or
python -m neoCoder.mcp.server

Claude Code Configuration

Add to your Claude Code MCP settings (claude_desktop_config.json or via claude mcp add):

{
  "mcpServers": {
    "neocoder": {
      "command": "python",
      "args": [
        "-m",
        "neoCoder.mcp.server"
      ],
      "env": {}
    }
  }
}

Or using the CLI:

claude mcp add neocoder -- python -m neoCoder.mcp.server

With uv (recommended):

claude mcp add neocoder -- uv run --directory /path/to/neoCoder python -m neoCoder.mcp.server

---

🏗️ Architecture

flowchart LR
    subgraph Input["📥 Input"]
        User([User Task])
    end

    subgraph Agent["🧠 neoCoder Agent"]
        direction TB
        Orchestrator[Orchestrator]
        Memory[(Memory)]
        LLM[LLM Client]
        
        Orchestrator --- Memory
        Orchestrator --- LLM
    end

    subgraph Tools["🔧 Tools"]
        direction TB
        Bash[/Bash/]
        Files[/Files/]
        Search[/Search/]
    end

    subgraph Cloud["☁️ Cloud"]
        API((Claude API))
    end

    User --> Orchestrator
    Orchestrator --> Tools
    LLM <--> API

    style Input fill:#0d1117,stroke:#00ff00,color:#00ff00
    style Agent fill:#0d1117,stroke:#60a5fa,color:#fff
    style Tools fill:#0d1117,stroke:#f59e0b,color:#fff
    style Cloud fill:#0d1117,stroke:#8b5cf6,color:#fff

Loading

---

📁 Project Structure

neoCoder/
├── 📂 sdk/                 # Core SDK components
│   ├── orchestrator.py     # Agent loop
│   ├── llm/                # LLM client implementations
│   ├── memory/             # Memory management
│   └── extensions/         # Tool extensions
├── 📂 nca/                 # Code Agent implementation
│   ├── agent.py            # NeoCoderAgent
│   ├── config.py           # CCAConfig, PRESETS
│   └── prompts.py          # System prompts
├── 📂 cli/                 # Command-line interface
├── 📂 mcp/                 # MCP server implementation
└── 📂 config/              # Configuration management

---

🛠️ Alternative Setup Methods

Python Scripts

python neoCoder/scripts/neocoder-config.py
python neoCoder/scripts/neocoder-config.py --create --path /custom/path

Python Module

python -m neoCoder.config.init_config
python -m neoCoder.config.init_config /custom/path

---

📄 License

See LICENSE for details.

---

Made with ❤️ for developers