neocoder 1.0.4

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

** AI-Native Engineering Agent for Enterprise-Scale Codebase**

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

⚡ Efficiency Comparison in real world COMPLEX task:

🤖 AI/RUN Engineering Benchmark

Source: EPAM AI/RUN Engineering Benchmark

[!TIP] neoCoder achieves the same results with 2.6x fewer tokens and API calls

🏆 Toolathlon Benchmarking Language Agents for Diverse, Realistic, and Long-Horizon Task Execution

📊 LiveBench Performance

✨ Key Features

📦 Installation

[!NOTE] Requires Python 3.10+ and pipx or uv for the recommended global CLI install.

Recommended: pipx

pipx install neocoder

Alternative: uv

uv tool install neocoder

Local development

# Clone and install
cd neoCoder
pip install -e .

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

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

[!TIP] neoCoder loads configuration from %USERPROFILE%\\.neoCoder\\settings.json on Windows and ~/.neoCoder/settings.json on Linux/macOS, so the installed CLI works from any directory.

🚀 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 or SSO

[!IMPORTANT] Use an API key for standard providers, or SSO/JWT for enterprise gateways.

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

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

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

Enterprise SSO example:

neocoder sso login --url https://codemie.lab.epam.com

neoCoder will normalize this to the CodeMie API base and open the browser against /code-assistant-api/v1/auth/login/<port> automatically.

EPAM enterprise access is configured in a dedicated epam_sso settings section with its own URL, provider route, and model selection.

When epam_sso.enabled is true, neoCoder prompts for interactive SSO login on startup if no valid local session exists.

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

✨ Professional Engineering Mode (Workflow Preset) ✨

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

neocoder --preset workflow "your complex task"

8-Stage Engineering Pipeline:

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 "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

🛡️ File Change Confirmation

Use --confirm (-c) flag to require manual approval before each file modification:

neocoder --confirm "create a new module"
neocoder -c "refactor auth system"

Confirmation dialog options:

🎨 Command Palette (Interactive Mode)

In interactive mode, use :: commands for quick actions:

Built-in commands:

⚙️ 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

Review Priority Order

Additional Checks (all universal)

• 🔒 Security: Hardcoded secrets, SQL injection, eval/exec, insecure YAML, debug flags
• 🐛 Syntax: Parse errors (Python AST), brace/bracket balance (JS/TS)
• 📊 Complexity: Cyclomatic complexity, nesting depth
• 🎨 Style: Code duplication, dead code / unused imports
• 🏷️ Types: Missing type hints (Python), any usage (TypeScript)

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

📁 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 neoCoder/scripts/neocoder-config.py
python neoCoder/scripts/neocoder-config.py --create --path /custom/path

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