Provides a repair tool that streams single-turn patch generation to a local Ollama daemon at http://localhost:11434, enabling offline code repair with local models such as Qwen2.5-Coder.
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.
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:
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).
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.
Related MCP server: Orihime
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 |
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).
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!
neurocode_slice: In-memory CPG reachability slicing bounded under token budget ($B \le 1,200$).
neurocode_seeds: Static root-cause candidate entity discovery in $<2$ ms.
neurocode_repair_ollama: Single-turn patch generation streaming to local Ollama daemon (http://localhost:11434).
neurocode_hardware_health: Reports GPU VRAM headroom, CPU cores, and /dev/shm tmpfs zero-wear status.
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": []
}
}
}Add to .cursor/mcp.json or your Cursor settings:
{
"mcpServers": {
"neurocode": {
"command": "neurocode-mcp",
"args": []
}
}
}Add to your ~/.continue/config.json:
{
"experimental": {
"modelContextProtocolServers": [
{
"name": "neurocode",
"command": "neurocode-mcp",
"args": []
}
]
}
}pip install neurocode-ai(Or install locally from source: git clone https://github.com/Arkz-Deepak/neurocode.git && cd neurocode && pip install -e .)
# 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# 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 \
--applyneurocode-copilotAuthor: Deepak R.
Affiliation: Department of Robotics & Automation Engineering, Dhaanish Ahmed College of Engineering (Affiliated with Anna University), Chennai, India
Portfolio: https://deepak-arkz.me
GitHub: @Arkz-Deepak
IEEE Transactions on Software Engineering (TSE): paper_ieee_tse/neurocode_tse.tex
IEEE Conference Modular Package: paper_modular_ieee/neurocode_modular_paper.tex
MLSys Conference Format: paper_mlsys/neurocode_mlsys.tex
Kaggle Competition Executable Notebook: Kaggle Notebook Live
@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}
}This project is licensed under the MIT License.
Check local hardware capacity (VRAM allocation, GPU headroom, and tmpfs RAM availability).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations supplied, the description carries the full disclosure burden. "Check" implies a read-only, side-effect-free probe, and naming allocation/headroom/tmpfs tells the agent what dimensions are reported. However, it says nothing about whether the call is cheap or slow, whether it can fail when no GPU is present, or how results are shaped.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence with the resource named immediately and the three inspected quantities parenthesized. Every clause earns its place and there is no filler or repetition of the tool name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, so the description is the only source of information about what comes back, and it gives just a metric list without saying whether values are absolute, percentage, or threshold-flagged. For a no-argument diagnostic this is close to adequate, but the agent cannot anticipate the response well enough to plan around it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, which is the baseline-4 case; there is nothing the description could add or omit on this dimension. The empty schema is consistent with the no-argument framing of the description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Names a specific verb and resource ("Check local hardware capacity") and enumerates the three things inspected: VRAM allocation, GPU headroom, tmpfs RAM availability. That is far more concrete than the name alone. No sibling differentiation is attempted, but the siblings (slice, seeds, repair_ollama) are functionally distant, so the risk of confusion is low.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no when-to-use guidance at all: no statement of the precondition that should trigger a hardware check (e.g. before allocating, before a large job, after an OOM error), no when-not-to-use, and no reference to alternatives. The word "Check" implies a diagnostic read, but the agent must infer the trigger condition entirely.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Perform single-turn bug repair by sending a knapsack-sliced prompt to a local Ollama model instance.
| Name | Required | Description | Default |
|---|---|---|---|
| apply | No | Whether to write the patch to disk | |
| issue | Yes | Bug description or traceback | |
| model | No | Ollama model name (e.g. 'qwen2.5-coder:14b', 'qwen2.5-coder:7b') | qwen2.5-coder:7b |
| repo_path | Yes | Path to repository root | |
| ollama_url | No | Ollama server URL | http://localhost:11434 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are supplied, so the description carries the entire behavioral burden, yet it discloses only that repair is single-turn and model-backed. It never says whether files are modified (the schema's 'apply' flag is the only hint), what permissions or server state are required, whether output is a diff or prose, or how failures surface.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single efficient sentence with the action front-loaded and no filler. Its brevity is achieved partly by omitting needed behavioral detail, but as a structure it is clean and readable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation-capable tool with no annotations and no output schema, the definition is too thin. It omits what the tool returns (patch, diff, explanation), how the apply flag interacts with results, and the environmental prerequisite of a reachable Ollama endpoint.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so every parameter is already documented in the schema, establishing a baseline of 3. The description adds no syntax or usage detail beyond the schema; the 'knapsack-sliced prompt' wording vaguely implies repo_path and issue feed the prompt but adds no actionable semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: it repairs bugs by sending a prompt to a local Ollama model instance. The 'single-turn' qualifier and 'knapsack-sliced prompt' phrase hint at mechanism, but there is no explicit differentiation from siblings like neurocode_slice even though that sibling likely produces the slices referenced here.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no when-to-use guidance versus alternatives and no exclusions. An agent cannot tell from the text alone whether to choose this over neurocode_slice or another repair path, nor what preconditions (a running Ollama server, an existing repo) must hold.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Statically identify root-cause candidate functions, methods, and classes from an issue description or traceback in <2 ms.
| Name | Required | Description | Default |
|---|---|---|---|
| issue | Yes | Bug description or error traceback | |
| repo_path | Yes | Path to repository root |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations supplied, the description carries the burden, and 'statically' usefully signals that no code is executed and behavior is read-only. However it says nothing about output format, ranking/confidence of candidates, limits on result count, or whether the repo is modified, and the '<2 ms' latency claim is the only additional behavioral detail.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One sentence, front-loaded with the verb and resource, with the input source and performance claim appended. Nothing is redundant or buried.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-required-parameter tool with no output schema, the description conveys what kind of entities come back (candidate functions, methods, classes), which is the key missing piece an agent would need. It lacks detail on result ordering or size, but that is a modest gap at this complexity level.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both parameters are already documented. The description only reinforces that the issue input may be a plain bug description or an error traceback, which is marginal added meaning; the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb ('statically identify') and a concrete output set (root-cause candidate functions, methods, and classes) plus the input form (issue description or traceback), so an agent immediately knows what the tool produces. It does not explicitly contrast itself with siblings like neurocode_slice or neurocode_repair_ollama, which keeps it short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by the input contract: call it when you have a bug description or traceback and a repo path. There is no explicit statement of when to prefer this over neurocode_slice or neurocode_repair_ollama, and no exclusions or prerequisites are given, so the agent must infer routing from the single sentence.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Extract an AST-sliced repository context bounded strictly under token budget (<=1,200 tokens) using Host-side Code Property Graph reachability.
| Name | Required | Description | Default |
|---|---|---|---|
| issue | Yes | Bug report, error traceback, or coding query | |
| budget | No | Maximum token budget (default 1200) | |
| repo_path | Yes | Absolute or relative path to repository root |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden, and it does disclose two real behavioral traits: the hard token ceiling (<=1,200) and the mechanism (CPG reachability slicing) that determines what gets included. It does not state that the operation is read-only, whether results are deterministic, how the slice is structured, or what happens if the repo path is invalid or the issue is too vague.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence with the key constraint front-loaded after the verb and no filler or repetition. It is dense with unexplained internal terminology ('Host-side', 'Code Property Graph reachability'), which costs a little readability but not length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema and no annotations, so the description is the only source of context, and it never says what the returned 'slice' contains (file snippets? AST nodes? line ranges?) or how large the issue string may be. For a context-extraction tool whose whole value is the shape of its output, this is a meaningful gap, though the budget and mechanism disclosures partially compensate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all three parameters are already documented in the schema, which sets the baseline at 3. The description reinforces the budget concept ('bounded strictly under token budget') but adds no new semantics for repo_path or issue beyond what the schema states.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a concrete verb ('Extract') and a specific resource ('AST-sliced repository context') with its defining constraint (bounded under a token budget via CPG reachability). It never contrasts itself with the likely-overlapping sibling neurocode_seeds, and the phrase 'Host-side Code Property Graph reachability' is opaque jargon an agent must guess at.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is only implied: supplying a repo plus an issue suggests 'call this when you have a bug report or traceback and need relevant code'. There is no explicit when-to-use, no when-not-to-use, and no routing to neurocode_seeds or the other siblings, even though seeds plausibly covers a similar context-gathering step.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
neurocode_hardware_healthneurocode_repair_ollamaneurocode_seedsneurocode_sliceScored across 4 tools
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.
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.
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.
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.
Deterministic context layer for your codebase: change impact, blast radius, answers with receipts.
Codebase knowledge graph — architectural awareness for AI coding agents via MCP
Code intelligence for coding agents: semantic, AST, graph, and full-text search. 279+ languages.
Code intelligence platform for AI agents. 20 tools for architecture, security & impact analysis.
