neocoder 0.1.2

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

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

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

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	8-stage professional engineering pipeline with brainstorming, planning & testing
✅ Auto Code Review	Checks anti-patterns, bottlenecks, best practices, pitfalls & security 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 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

[!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, 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:

Stage	Description	Auto-Approve
1️⃣ Problem Breakdown	Decomposes task into subtasks with dependencies	❌ Requires approval
2️⃣ Brainstorming	High-level approach, alternatives, trade-offs, risks	❌ Requires approval
3️⃣ Implementation Plan	Creates detailed step-by-step plan based on brainstorming	❌ Requires approval
4️⃣ Implementation	Executes the plan with file operations	✅ Auto-proceeds
5️⃣ Integration Testing	Runs automated tests with retry logic	✅ Auto-proceeds
6️⃣ Tech Stack Review	Validates against best practices	✅ Auto-proceeds
7️⃣ Code Review	Automated review using project rules	✅ Auto-proceeds
8️⃣ 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 "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:

Key	Action
y	Accept changes
n	Reject changes
e	Edit in external editor
d	View full diff
a	Accept all remaining changes
q	Abort operation

---

🎨 Command Palette (Interactive Mode)

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

Command	Action
::	Open command palette with fuzzy search
::m	Switch mode (coding/debug/refactor)
::t	Switch or create thread
::s	Toggle mode (coding ↔ debug)

Built-in commands:

Command	Action
exit / quit / q	Exit agent
reset	Reset current session
help	Show help

---

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

---

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 docs/JSDoc, mutable defaults, proper comparisons
4️⃣	Pitfalls	Broad exception catching, empty catch blocks, assert misuse
5️⃣	Security	Deserialization, command injection, path traversal, insecure HTTP

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