Skip to main content

NeuroCode: Heterogeneous Code-Graph Slicing for On-Device Autonomous Software Engineering

PyPI version Visual Studio Marketplace Glama MCP Server Awesome MCP Servers ICPC 2027 License: MIT Python 3.10+ Hardware: 4GB GPU

NeuroCode is a lightweight, heterogeneous neuro-symbolic framework and Model Context Protocol (MCP) server that enables small, local language models (1.5B–14B parameters) to fix multi-file software engineering bugs on consumer laptops (e.g., 4GB–8GB VRAM) without cloud API dependency or Out-of-Memory (OOM) crashes.

📌 Academic Reproducibility Notice:
For benchmark reproduction and evaluation datasets corresponding to the 35th IEEE/ACM ICPC 2027 (Submission #63) and the Elsevier Journal of Systems and Software (JSSOFTWARE-S-26-03997), please refer to frozen release tag v0.1.1. The master branch represents the actively maintained multi-language production release.


🌐 Multi-Language Code Property Graph & AST Grafting

NeuroCode natively parses and deterministically mutates code across 5 programming languages using in-memory Tree-sitter AST grammars:

  • Python (.py)
  • TypeScript (.ts, .tsx)
  • JavaScript (.js, .jsx, .mjs, .cjs)
  • Go (.go)
  • Rust (.rs)

🏛️ System Architecture

System Architecture

Unlike traditional coding agents that dump entire raw files into context windows (causing severe VRAM OOMs) or get trapped in multi-turn exploratory shell loops (grep, find, cat), NeuroCode divides cognitive labor across the PC hardware boundary:

  1. Host CPU & RAM (Deterministic Graph Engine):
    • Uses Tree-sitter and NetworkX to build an in-memory Code Property Graph (CPG) in milliseconds.
    • Computes a topological $k$-hop reachability closure around fault candidates.
    • Solves a bounded 0/1 knapsack optimization problem to select high-relevance AST subtrees strictly under the model's token limit ($B \le 1,200$ tokens).
  2. Device GPU (Neural Synthesis Engine):
    • Ingests only the bounded sliced context across PCIe.
    • Generates single-turn SEARCH/REPLACE diff patches with zero exploratory token waste.
    • Completely prevents KV-cache quadratic blowup and GPU OOM cliff failure.

📊 Comprehensive Empirical Evaluation (5-Benchmark Suite)

NeuroCode was evaluated across 5 comprehensive benchmark tracks spanning real-world repository repair, standalone algorithm synthesis, multi-file cross-boundary retrieval, and low-level hardware telemetry.

Benchmark Suite Metric Baseline / BM25 NeuroCode (Ours) Advantage
SWE-bench Lite ($N=292$) Valid Diff Apply / Resolved 0.0% (OOM on 4GB) / 0.0% 41.4% apply / 9.5% resolved Prevents OOM cliff; +23.9% apply over BM25
HumanEval ($N=164$) Pass@1 (Unit Test) 80.5% 86.0% (141/164) +5.5% via syntax-aware graph repair
MBPP ($N=100$) Pass@1 (Unit Test) 81.0% 87.0% (87/100) +6.0% algorithmic verification
RepoBench-R ($N=150$) Recall@1 / Token Budget 18.0% (745 tokens) 100.0% (428 tokens) -42.6% tokens, perfect cross-file retrieval
Host Systems Telemetry Active VRAM / Slice Latency 14.2 GB (OOM) 961.2 MB / 0.62 ms 93.2% VRAM reduction, 0 OOMs

💻 Physical Laptop Edge Validation (NVIDIA RTX 3050 Laptop GPU)

Tested live on an everyday developer laptop (AMD Ryzen 7 7435HS + NVIDIA RTX 3050 Laptop GPU, 4.0 GB VRAM):

  • Peak Active VRAM: 961.2 MB (Only 25.5% GPU capacity, leaving 2.54 GB buffer for system desktop UI).
  • Throughput: 15.8 tokens/second locally.
  • Host Slicing Overhead: 0.04 ms on CPU.
  • Disk SSD Wear: 0.0 GB (100% in-memory ephemeral RAM execution via /dev/shm).

🔌 Model Context Protocol (MCP) Integration

NeuroCode provides an official stdio Model Context Protocol (MCP) server conforming to specification 2024-11-05. Connect NeuroCode directly to Claude Desktop, Cursor, Continue.dev, or VS Code!

Native MCP Tools Exposed:

  1. neurocode_slice: In-memory CPG reachability slicing bounded strictly under token budget ($B \le 1,200$).
  2. neurocode_graft: Deterministic AST subtree grafting with automatic indentation alignment and optional test verification with auto-rollback.
  3. neurocode_trace: Sub-millisecond execution call-chain path tracing connecting functions and symbols.
  4. neurocode_map: Instant zero-token architecture flowchart (Mermaid.js) of the codebase.
  5. neurocode_impact: Structural blast radius inspection (all upstream callers and downstream callee invocations in <2 ms).
  6. neurocode_symbol: Sub-millisecond AST symbol lookup returning file locations, line spans, and callers.
  7. neurocode_validate_patch: In-memory pre-flight patch verification for syntax errors before writing to disk.
  8. neurocode_seeds: Static root-cause candidate entity discovery in $<2$ ms.
  9. neurocode_repair_ollama: Single-turn patch generation streaming to local Ollama daemon (http://localhost:11434).
  10. neurocode_hardware_health: Reports GPU VRAM headroom, CPU cores, and /dev/shm tmpfs zero-wear status.

1. Claude Desktop Setup

Add the following to your Claude Desktop configuration file:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Linux: ~/.config/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
{
  "mcpServers": {
    "neurocode": {
      "command": "/absolute/path/to/neurocode/.venv/bin/neurocode-mcp",
      "args": []
    }
  }
}

2. Cursor IDE Setup

Add to .cursor/mcp.json or your Cursor settings:

{
  "mcpServers": {
    "neurocode": {
      "command": "neurocode-mcp",
      "args": []
    }
  }
}

3. Continue.dev Setup

Add to your ~/.continue/config.json:

{
  "experimental": {
    "modelContextProtocolServers": [
      {
        "name": "neurocode",
        "command": "neurocode-mcp",
        "args": []
      }
    ]
  }
}

💻 Visual Studio Code Extension

Install directly from the Visual Studio Marketplace:

code --install-extension DeepakR.neurocode-ai

(Or download the .vsix binary from the v0.1.0 Release)

Extension Features:

  • Status Bar Telemetry: Live VRAM headroom and /dev/shm RAM health indicators.
  • Context Slicing: Right-click any active file or code block to extract sub-1,200 token reachability closure in $<100$ ms.
  • 1-Click Prompt Copy: Instant paste into Cursor, Claude, or Copilot without context overflow.
  • Autonomous Diff Viewer: Direct side-by-side patch inspection powered by local Ollama backbones.

🚀 Quickstart & CLI Usage

1. Installation via PyPI

pip install neurocode-ai

(Or install locally from source: git clone https://github.com/Arkz-Deepak/neurocode.git && cd neurocode && pip install -e .)

2. Extract Token-Bounded Slice for Any Issue

# Slices your codebase into a tight, bug-focused prompt under 1200 tokens
neurocode slice --repo /path/to/repo --issue "Fix ZeroDivisionError in matrix normalization" --budget 1200

3. Repair Code via Local Ollama Daemon (Zero Cloud API)

# Runs full repair using local Qwen2.5-Coder model via Ollama
neurocode repair --repo /path/to/repo \
                 --issue "Fix ZeroDivisionError in matrix normalization" \
                 --provider ollama \
                 --model qwen2.5-coder:7b \
                 --apply

4. Interactive Copilot Direct on Laptop GPU

neurocode-copilot

👤 Author & Affiliation


📄 Publications & Preprints

  • 35th IEEE/ACM International Conference on Program Comprehension (ICPC 2027):
  • Journal of Systems and Software (Elsevier):
    • Track: Full Research Article (Traditional Subscription, ₹0 APC)
    • Title: On-Device Autonomous Software Engineering: In-Memory Code Property Graph Reachability Slicing under Edge VRAM Constraints
    • Source: paper_elsevier_jss/neurocode_jss.tex
  • Kaggle Empirical Reproduction: Kaggle Notebook Live

Citation

@article{deepak2026neurocode,
  title={NeuroCode: Budget-Constrained Heterogeneous Code-Graph Slicing for Local Software Repair},
  author={Deepak, R.},
  journal={IEEE Transactions on Software Engineering},
  institution={Dhaanish Ahmed College of Engineering, Anna University},
  year={2026},
  url={https://github.com/Arkz-Deepak/neurocode}
}

📜 License

This project is licensed under the MIT License.

Metadata

Release files for neurocode-ai 1.3.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for neurocode-ai 1.3.0
File Size Uploaded Provenance Actions
neurocode_ai-1.3.0.tar.gz 81.7 kB Without provenance Details for neurocode_ai-1.3.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for neurocode-ai 1.3.0
File Interpreter ABI Platform Actions
neurocode_ai-1.3.0-py3-none-any.whl Python 3 none any Details for neurocode_ai-1.3.0-py3-none-any.whl

Total release size: 171.7 kB

Release files / neurocode_ai-1.3.0.tar.gz

Download URL neurocode_ai-1.3.0.tar.gz
Size 81.7 kB
Tags Source
SHA-256 checksum
How to use checksums
27b8576d6e1ee045a6838dc02d73a6c71765641a788ffaa73476ee91947592bf
BLAKE2b-256 checksum
How to use checksums
2c18cff5a80d5424e872333a7382f27e3ad67d485f804e67fbf58210db77bf61
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.3

Release files / neurocode_ai-1.3.0-py3-none-any.whl

Download URL neurocode_ai-1.3.0-py3-none-any.whl
Size 90.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
b1c16ffee9ed64fac539b2d808e8a0d5ef16713f8e53150688e241f2d1b965db
BLAKE2b-256 checksum
How to use checksums
ae07b09db891fd464789823dd4069891a2c9c9ceaea6ab060bbb979702984d4f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.3

Security for neurocode-ai 1.3.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page