neurocode
by Arkz-Deepak
README.md
# NeuroCode: Heterogeneous Code-Graph Slicing for On-Device Autonomous Software Engineering
[](https://pypi.org/project/neurocode-ai/)
[](https://opensource.org/licenses/MIT)
[](https://www.python.org/downloads/)
[]()
[](https://modelcontextprotocol.io)
[](https://ollama.ai)
[](https://www.kaggle.com/code/deepark121/neurocode-heterogeneous-graph-sliced-swe-agent)
**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.
---
## 🏛️ 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 under token budget ($B \le 1,200$).
2. `neurocode_seeds`: Static root-cause candidate entity discovery in $<2$ ms.
3. `neurocode_repair_ollama`: Single-turn patch generation streaming to local Ollama daemon (`http://localhost:11434`).
4. `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`
```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:
```json
{
"mcpServers": {
"neurocode": {
"command": "neurocode-mcp",
"args": []
}
}
}
```
### 3. Continue.dev Setup
Add to your `~/.continue/config.json`:
```json
{
"experimental": {
"modelContextProtocolServers": [
{
"name": "neurocode",
"command": "neurocode-mcp",
"args": []
}
]
}
}
```
---
## 🚀 Quickstart & CLI Usage
### 1. Installation via PyPI
```bash
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
```bash
# 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)
```bash
# 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
```bash
neurocode-copilot
```
---
## 👤 Author & Affiliation
- **Author**: **Deepak R.**
- **Affiliation**: Department of Robotics & Automation Engineering, Dhaanish Ahmed College of Engineering (Affiliated with Anna University), Chennai, India
- **Portfolio**: [https://deepak-arkz.me](https://deepak-arkz.me)
- **Email**: [`wssedd18@gmail.com`](mailto:wssedd18@gmail.com) / [`deepak121289@outlook.com`](mailto:deepak121289@outlook.com)
- **GitHub**: [@Arkz-Deepak](https://github.com/Arkz-Deepak)
---
## 📄 Publications & Preprints
- **IEEE Transactions on Software Engineering (TSE)**: [`paper_ieee_tse/neurocode_tse.tex`](paper_ieee_tse/neurocode_tse.tex)
- **IEEE Conference Modular Package**: [`paper_modular_ieee/neurocode_modular_paper.tex`](paper_modular_ieee/neurocode_modular_paper.tex)
- **MLSys Conference Format**: [`paper_mlsys/neurocode_mlsys.tex`](paper_mlsys/neurocode_mlsys.tex)
- **Kaggle Competition Executable Notebook**: [Kaggle Notebook Live](https://www.kaggle.com/code/deepark121/neurocode-heterogeneous-graph-sliced-swe-agent)
### Citation
```bibtex
@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](LICENSE).
TDQS
B3.3/5.0
Scored across 4 tools
Disambiguation4/5
Each tool occupies a distinct pipeline stage: slicing context, finding seed functions, running local LLM repair, and reporting hardware capacity. The only mild overlap is between neurocode_slice and neurocode_seeds, since both do static code analysis, but the descriptions frame them as complementary (seeds finds candidates, slice extracts bounded context). An agent can pick correctly in most cases.
Naming Consistency4/5
All names share a consistent neurocode_ prefix with snake_case, which makes the family instantly recognizable. The suffix style varies slightly (verb 'slice', noun 'seeds', verb_noun 'repair_ollama', noun_noun 'hardware_health'), a minor deviation from a strict verb_noun pattern but still readable and predictable.
Tool Count4/5
Four tools map cleanly onto the four stages of a local code-repair pipeline, so each earns its place. The set is on the lean side, but the narrow scope (single-turn Ollama repair) keeps it justified rather than thin.
Completeness3/5
The pipeline covers health check, candidate identification, context slicing, and repair, but stops at patch generation; there is no verification, test-run, or patch-application step, which is a notable gap for a repair workflow. There is also no way to select or configure models beyond the implicit local Ollama instance.
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues