🧠 NEURIX

Neural Engine for Unified Reasoning, Intelligence and eXecution

Multi-agent orchestration framework for Claude Code.

npx neurix install

What is NEURIX?

NEURIX installs a team of specialized AI agents into your project, coordinated through slash commands. Instead of freeform prompting, you get structured phases — planning, execution, review — with each agent handling its domain.

A universal core team (conductor, architect, developer, reviewer, analyst, writer) is always included. Optional tech stacks layer framework-specific skills on top.

Install

# Interactive — guides you through categories, stacks, MCP servers and IDE integration
npx neurix install

# Non-interactive — core only, all MCP servers auto-selected, no prompts
npx neurix install --yes

# Specific stacks
npx neurix install --stacks react
npx neurix install --stacks react,nestjs

# Custom name + prefix
npx neurix install --name "MyEngine" --prefix "me" --stacks react
#  → _myengine/  runtime directory
#  → /me-plan, /me-run, /me-analyse … slash commands

Options

| Flag | Default | Description | |------|---------|-------------| | --name | NEURIX | Runtime directory name (_neurix/) | | --prefix | neurix | Slash command prefix (/neurix-plan) | | --stacks | (none) | Comma-separated stack codes to install | | --tools | claude-code | IDE integration (claude-code, cursor) | | --yes | false | Skip all prompts, use defaults |

Interactive Install Flow

The installer guides you in three steps:

1 — Select categories

? Select stack categories:
  ❯ ◯ backend
    ◯ frontend

2 — Select stacks per category (separate prompt per category, no mixing)

[backend] Select stacks to install:
  ❯ ◯ NestJS (10+)   — NestJS framework-specific patterns
    ◯ Node.js (20+)   — Node.js backend patterns with Express/Fastify
    ◯ Symfony (6.4+)  — Symfony framework-specific patterns

[frontend] Select stacks to install:
  ❯ ◯ Angular (20+)
    ◯ React (18+)

3 — Select MCP servers per stack (granular — zero or more per stack)

[React] MCP servers to install:
  ❯ ◯ context7   — Injects up-to-date React/Vite docs into prompts
    ◯ playwright  — Microsoft Playwright — E2E testing, screenshots

[NestJS] MCP servers to install:
  ❯ ◯ postgres   — PostgreSQL schema inspection and querying
    ◯ redis       — Redis key-value access for cache layer
    ◯ playwright  — E2E testing of NestJS-backed web apps

MCP servers are written to .mcp.json in your project root. Duplicate servers across stacks are deduplicated automatically.

What Gets Installed

your-project/
├── _neurix/
│   ├── core/
│   │   ├── agents/        ← conductor, architect, developer, reviewer, analyst, writer
│   │   ├── workflows/     ← plan, run, analyse, debug, status, init
│   │   ├── skills/        ← orchestration, code-generation, file-analysis,
│   │   │                     refactoring, web-research, doc-writing
│   │   └── tasks/         ← help, graph
│   ├── react/             ← (if selected) React-specific skills
│   │   ├── context.md     ← generated at install (stack.yaml + your MCP choices)
│   │   └── skills/        ← component, hooks, state, testing
│   ├── nestjs/            ← (if selected) NestJS-specific skills
│   │   ├── context.md
│   │   └── skills/        ← module, controller, service, guard, testing
│   ├── _config/
│   │   ├── config.yaml    ← project name, prefix, installed stacks
│   │   ├── manifest.yaml  ← version, file count, stack options
│   │   └── templates/     ← plan.md, workflow-status.yaml, session.md, stack-context.md
│   └── _memory/
│       └── session.md     ← Conductor saves state here at each phase transition
├── _neurix-output/
│   ├── plan.md            ← current active plan (with Plan ID + date)
│   ├── workflow-status.yaml
│   └── plans/             ← automatic backups of previous plans
│       ├── plan-PLAN-20260315-001.md
│       └── workflow-status-PLAN-20260315-001.yaml
├── .claude/commands/      ← /neurix-* slash commands
└── .mcp.json              ← MCP server definitions (if any selected)

Slash Commands

| Command | Description | |---------|-------------| | /neurix-plan | Create the execution plan — auto-saves, backs up previous | | /neurix-plan "..." | Plan from a free-form description | | /neurix-plan --reset | Force a new plan even if one is in progress | | /neurix-run | Execute the current plan | | /neurix-run --step | Execute one task at a time | | /neurix-run --dry | Simulate without writing anything | | /neurix-analyse | Full project analysis | | /neurix-debug | Diagnose the NEURIX framework health | | /neurix-status | Quick progress overview | | /neurix-init | Initialize session tracking | | /neurix-graph | Visual workflow map and agent diagram | | /neurix-help | Show all commands and guidance |

Plan Management

Every /neurix-plan invocation is fully automatic — no save prompts.

Plan lifecycle

/neurix-plan
     │
     ▼
 Guard: plan already in progress?
     │ no                    │ yes → stop + show plan_id, phase, next action
     ▼
 Load stacks context
 Read project files (parallel)
 Decompose into phases
     │
     ▼
 Draft plan  →  show to user  →  "Any modifications?"
     │                                    │ changes requested → apply → show again
     │ confirmed ◄──────────────────────────────────────────────
     ▼
 Backup previous plan to _neurix-output/plans/plan-<old_id>.md
 Save _neurix-output/plan.md               Plan ID: PLAN-20260315-002
 Save _neurix-output/workflow-status.yaml  plan_id, plan_version, created_at
     │
     ▼
 ✅ Plan PLAN-20260315-002 saved. Run /neurix-run to start.

Plan IDs

Each plan gets a unique identifier: PLAN-YYYYMMDD-NNN (auto-incremented).

# workflow-status.yaml
plan_id: "PLAN-20260315-002"
plan_version: 1
created_at: "2026-03-15 14:30"

Rollback

Previous plans are never deleted — they accumulate in _neurix-output/plans/:

_neurix-output/plans/
  plan-PLAN-20260315-001.md                   ← copy of the plan as executed
  workflow-status-PLAN-20260315-001.yaml      ← full task state at that time

To roll back: copy the backup files back to _neurix-output/ and resume with /neurix-run.

Agents

| Agent | Role | Key behaviors | |-------|------|---------------| | Conductor | Master orchestrator | Dispatches in parallel, retries failed tasks once then asks human, saves session state at each phase | | Architect | System design, specs | Reads existing code before designing, applies stack conventions as hard constraints | | Developer | Code, tests | Reads files before writing, loads stack skills, self-verifies output, asks before destructive ops | | Reviewer | Quality audit (read-only) | Checks stack-specific convention violations in addition to generic quality rules | | Analyst | Research, diagnostics | Reads all relevant files before analysing, calibrates findings against stack versions | | Writer | Documentation | Uses actual stack CLI and package manager in examples, adapts terminology per framework |

Skills

Each agent loads the relevant skill before starting complex tasks. Skills are procedures, not agents — they guide how to do the work.

| Skill | Used by | Purpose | |-------|---------|---------| | orchestration | Conductor | Decompose requests across agents, parallel vs sequential dispatch | | code-generation | Developer | Structured implementation: spec → file tree → code → tests → lint | | refactoring | Developer | Safe incremental refactoring with characterization tests | | file-analysis | Analyst, Architect | Project structure scan, metrics, health report | | web-research | Analyst | Parallel multi-source research with structured synthesis | | doc-writing | Writer | Audience-aware documentation with stack-accurate examples |

Stack-specific skills (e.g. react/skills/component.md) are loaded by Developer on top of core skills when a stack is installed.

Tech Stacks

| Category | Stack | Version | Skills | |----------|-------|---------|--------| | frontend | react | 18+ | component, hooks, state, testing | | frontend | angular | 20+ | component, signals, service, http, routing, state, reactive-forms, pipes, directives, module, ssr, performance, animations, accessibility, testing, zoneless, migration | | backend | nestjs | 10+ | module, controller, service, guard, testing | | backend | node | 20+ | rest-api, database, middleware, testing | | backend | symfony | 6.4+ | entity, controller, service, form, testing |

The Angular stack also includes 4 specialized agents: angular-architect, angular-developer, angular-reviewer, angular-migrator.

Each installed stack generates a context.md at install time (from stack.yaml + your MCP server choices). The Conductor reads _config/config.yaml at runtime and injects the relevant context.md into every agent dispatch.

How It Works

/neurix-plan
     │
     ▼
 .claude/commands/neurix-plan.md
     │
     ▼
 _neurix/core/workflows/plan.md
     │
     ▼
 Conductor  ←── reads _config/config.yaml + <stack>/context.md
     │                     injects stack context into every dispatch
     ├──────────────┬───────────────┬──────────────┐
     ▼              ▼               ▼              ▼
 Analyst        Architect       Developer      Reviewer
 (research)     (design)        (code)         (audit)
    │              │               │              │
    └──────────────┴───────────────┴──────────────┘
         all agents receive <stack_context> when dispatched
                             │
                             ▼
                     _neurix-output/

Session Memory

The Conductor automatically saves state to _neurix/_memory/session.md at each phase transition:

• Active plan path, current phase, completed task IDs
• Key architectural decisions made during the session
• Installed stacks active in the session

When the context window resets (long sessions), the Conductor reads session.md + workflow-status.yaml to resume exactly where it left off — no work is lost.

Update

# Detects existing install → prompts for Quick Update or Full Reinstall
npx neurix install

# Explicit update — reads existing manifest, preserves name/prefix/stacks
npx neurix update

On update, modified files are backed up as .bak before being overwritten — your customizations are preserved.

Customization

Edit any installed file directly — it survives updates via .bak backup.

_neurix/core/agents/your-agent.md      ← Add a custom agent
_neurix/core/skills/your-skill.md      ← Add a core skill
_neurix/react/skills/your-skill.md     ← Add a stack-specific skill

Testing

npm test                               # all 10 phases, 400+ assertions
node tools/test/index.js --phase 2     # single phase
node tools/test/index.js --phase 1,9   # CLI + E2E only

The test suite validates CLI behavior, loader unit tests, all agent XML structure, workflow coherence, skill alignment, stack YAML↔file integrity, template variables, and end-to-end install flows.

Status

npx neurix status --directory /path/to/project

Reports installed version, stacks, prefix, and runtime directory.

License

MIT