NeuroLoop

NeuroLoop is a BCI-aware AI coding and life companion powered by real-time consumer EXG devices. It reads brainwaves and physiology continuously and uses that live biometric data to inform every response — adapting its tone, offering guided protocols, and labelling meaningful mental states as they happen.

NeuroLoop™ runs on top of the pi coding agent framework and communicates with the NeuroSkill™ State of Mind BCI server, which exposes a local WebSocket API for real-time neural data.

Supported Devices

Native NeuroSkill connectors

LSL sources (local network)

Via NeuroSkill's built-in LSL adapter, NeuroLoop can ingest streams from Lab Streaming Layer publishers (e.g. OpenBCI/BrainFlow pipelines, MATLAB, Python pylsl, custom broadcasters).

Remote LSL

NeuroSkill also supports remote LSL over encrypted iroh QUIC tunnels (rlsl-iroh), so a remote EEG source can stream into your local Skill app and become available to NeuroLoop automatically.

Additional wearable/OS data surfaced through NeuroSkill

• Apple HealthKit (sleep, HR, HRV, steps, workouts)
• Oura Ring cloud sync (sleep/activity/readiness/HR/SpO2/workouts/mindfulness)
• OS Calendar ingestion (EventKit on macOS, .ics sources on Linux/Windows)

Paper

---

Features

• 🧠 Live EXG context — injects a real-time snapshot of brain state (focus, relaxation, engagement, drowsiness, HRV, sleep stage, consciousness indices, etc.) into every LLM turn
• 📡 Live TUI panel — real-time scores and EEG band bars stream directly into the terminal footer via WebSocket; no polling delay
• 🌉 LSL ingestion support — works with NeuroSkill's local LSL sources and remote LSL-over-iroh pipelines
• 🎯 Contextual skill loading — detects domain signals in each user message (stress, sleep, focus, grief, awe, philosophy, HRV, etc.) and runs the matching NeuroSkill™ commands in parallel before the LLM responds
• 🏃 Guided protocols — 100+ mind-body practices (breathing, meditation, somatic work, sleep, music, social-media, dietary, gym, eye exercises, etc.) proposed intelligently and executed step-by-step with OS notifications and EXG labelling
• 🏷️ Auto-labelling — silently annotates notable mental, emotional, and philosophical moments as timestamped EXG events; the label text and context are written by the LLM
• 💾 Persistent memory — reads and writes a long-term memory file (~/.neuroskill/memory.md) across sessions
• 🔍 Prewarm cache — kicks off expensive neuroskill compare runs proactively in the background so results are ready when needed
• 🌐 Web tools — web_fetch and web_search available to the agent
• 📅 Daily calibration nudge — reminds the user to run a calibration sequence at most once every 24 hours
• 🔑 In-app API key management — add, list, or remove provider API keys at runtime with /key (no file editing required); keys are stored securely in ~/.neuroloop/auth.json
• 🤖 Multi-provider model support — Anthropic, OpenAI, Gemini, Skill app local/remote LLM routes, and all Ollama models (including gpt-oss:20b as the default local model)
• 💬 Expanded Skill LLM catalog coverage — Qwen/Qwen-VL, GPT-OSS, Ministral, Gemma, Phi, OmniCoder, LFM, and uncensored Qwen families (availability depends on local catalog/download state)
• 🧩 In-TUI model configuration — create/update ~/.neuroloop/models.json interactively (/model-config add) or open it in your system editor (/model-config open)
• 🗂️ Update visibility — startup changelog card (shown once per version), /updates, and live version route/status commands (/version, /llm route)
• 🛡️ Cross-platform — works on macOS, Linux, and Windows (cross-platform port discovery, shell escaping, file permissions)
• 🔒 Safety hardened — SSRF protection on web tools, shell injection prevention, bounded memory/protocol limits, restrictive file permissions, Node ≥ 20 enforced at startup

---

Quick Start

npx neuroloop

Requires Node.js ≥ 20 (enforced at startup). The NeuroSkill™ EXG server must be running and a supported EXG device connected for live biometric features (see Supported Devices above).

---

How It Works

On every user message the harness:

1. Runs neuroskill status via WebSocket and injects the live EXG snapshot into a visible chat bubble and the LLM system prompt
2. Detects domain signals in the user's prompt (30+ categories: stress, sleep, focus, grief, awe, morals, symbiosis, HRV, somatic, consciousness, identity, etc.)
3. Runs the matching NeuroSkill™ commands in parallel — session metrics, label searches, sleep staging, compare cache — and appends results to the system context
4. If protocol intent is detected, injects the full protocol repertoire (skills/neuroskill-protocols/SKILL.md) on demand
5. Injects the capability index (NEUROLOOP.md) and any persistent agent memory so the LLM always has full context

The LLM receives the live EXG data, behavioural guidance, and domain-specific history. The user sees only the EXG snapshot bubble.

---

TUI

NeuroLoop extends the pi TUI with:

• ASCII art splash — hot-pink NeuroLoop™ block-letter logo shown at startup, auto-collapses to compact header after 8 seconds
• Custom header — brand logo (◆ NeuroLoop™ vX.Y.Z), connection status, device info, skills sync status, and command hints
• Live footer metrics — real-time scores row (focus, cog.load, relax, engage, drowsy, mood, ♥ bpm) and EEG band bars (δ θ α β γ) updated via WebSocket; the most recent EXG label and its timestamp are shown right-aligned
• Download progress — active LLM model downloads shown with progress bar, spinner, and percentage in the footer
• Status bar — EXG connection dot (◉ / ◌), "last updated" age, context usage, and current model
• Smart brain state toasts — automatic notifications for focus spikes/drops, drowsiness alerts, cognitive overload, heart rate anomalies, and deep relaxation (with per-rule cooldowns to avoid spam)
• Switchable themes — 7 built-in color themes (Neuro Dark, Neuro Light, Calm, Focus, Matrix, Dracula, Catppuccin) with runtime switching via /theme and persistence to ~/.neuroloop/theme.json
• LLM manager popup — bordered overlay panel (/llm) showing server status, model catalog with download progress, and one-click actions (start/stop server, select/download/pause/resume models)
• EXG sidebar panel — right-anchored overlay with sparkline score history, band power bars, and trend indicators
• Command palette — fuzzy-searchable overlay listing all commands
• Overlay manager — stacking, modal exclusivity, and Esc dismissal for all overlays
• Event-driven rendering — 16ms debounced render batching for EXG data (60fps cap), 30s fallback for "ago" text

Slash Commands

EXG / Brain State

LLM / Models

API Keys / Model Config

Health / Wearables

TUI / Appearance

Utilities

---

Tools

---

Skills

The following skill files are loaded from skills/ and made available to the LLM for contextual injection:

---

EXG Metrics

NeuroLoop exposes 40+ neuroscientific metrics derived from the Muse headset, including:

• EEG band powers (δ, θ, α, β, γ) across all available electrodes
• Ratios and indices: TAR, BAR, TBR, DTR, PSE, APF, BPS, SNR, Coherence, PAC, FAA
• Complexity measures: Permutation Entropy, Higuchi FD, DFA Exponent, Sample Entropy
• Composite scores: Focus, Relaxation, Engagement, Meditation, Cognitive Load, Drowsiness
• Consciousness metrics: LZC, Wakefulness, Information Integration
• PPG / HRV: Heart Rate, RMSSD, SDNN, pNN50, LF/HF Ratio, SpO₂, Baevsky Stress Index
• Sleep staging: Wake / N1 / N2 / N3 / REM
• Extended indices: Depression, Anxiety, Bipolar, ADHD, Headache, Migraine, Narcolepsy, Insomnia, Epilepsy risk, Mu Suppression

⚠️ Research Use Only. All metrics are experimental outputs from consumer-grade EXG hardware. They are not validated clinical measurements, not FDA/CE-cleared, and must not be used for diagnosis or treatment.

See METRICS.md for the full scientific reference for every metric.

---

Repository Structure

neuroloop/
├── src/
│   ├── main.ts               # Entry point — session setup, skill loading, model registry
│   ├── neuroloop.ts          # ExtensionFactory — tools, hooks, renderers, TUI, WebSocket
│   ├── compression.ts        # Response compression (standard/strong/off)
│   ├── memory.ts             # Persistent memory helpers (~/.neuroskill/memory.md)
│   ├── model-config.ts       # models.json helpers + system-open integration
│   ├── runtime-updates.ts    # npm/GitHub version checks + runtime installs
│   ├── skill-llm.ts          # Skill app LLM boot/connect/register helpers
│   ├── skills-sync.ts        # skills submodule sync helpers
│   ├── tui/
│   │   ├── index.ts          # Barrel export for all TUI modules
│   │   ├── themes.ts         # 7 switchable color themes with persistence
│   │   ├── toast.ts          # Smart brain state alert rules with cooldowns
│   │   ├── command-palette.ts # Fuzzy-searchable command overlay (SelectList)
│   │   ├── render-scheduler.ts # 16ms debounced render batching (replaces 30s timer)
│   │   ├── overlay-panel.ts  # EXG sidebar with sparklines, bands, trends
│   │   ├── overlay-manager.ts # Stacking, modal exclusivity, Esc dismissal
│   │   ├── llm-panel.ts      # Bordered LLM manager popup with progress bars
│   │   └── logo.ts           # ASCII art NeuroLoop™ logo (full/compact/mini)
│   ├── neuroskill/
│   │   ├── index.ts          # Public barrel
│   │   ├── run.ts            # runNeuroSkill() — CLI executor + cross-platform port discovery
│   │   ├── signals.ts        # detectSignals() — prompt domain detection
│   │   └── context.ts        # selectContextualData() — parallel data fetching + compare cache
│   └── tools/
│       ├── web-fetch.ts      # web_fetch tool
│       ├── web-search.ts     # web_search tool
│       └── protocol.ts       # run_protocol tool — step-by-step guided protocols
├── skills/                   # Domain skill files (one subdirectory per skill)
├── NEUROLOOP.md              # Capability index injected every turn
├── METRICS.md                # Full neuroscientific reference for all EXG metrics
└── dist/                     # Compiled output (neuroloop.js)

Agent data is stored under ~/.neuroloop/ (sessions, auth, settings, models, port config).

---

Security

• File permissions — auth.json, memory.md, port config, and calibration state are written with 0o600 (owner-only); directories with 0o700
• SSRF protection — web_fetch blocks requests to private/loopback/RFC-1918/link-local networks and file:// URLs
• Shell injection prevention — on Windows, all CLI arguments are escaped before passing to cmd.exe (shell: true); on Unix, execFile is used without a shell
• Bounded resources — memory file capped at 512 KB; protocol steps capped at 200 with max 5 min/step; stdout buffer set to 8 MB
• Fetch timeout — web_fetch has a hard 30s timeout via AbortSignal.any() in addition to the caller's cancellation signal
• Node version gate — startup rejects Node < 20 with a clear error (required for AbortSignal.any(), AbortSignal.timeout(), global fetch)
• PID sanitization — neuroskill's lsof fallback validates pgrep output is numeric before interpolating into shell commands
• Server identity validation — port discovery probe checks the /health JSON response structure, not just HTTP 200
• Dependency auditing — zero known vulnerabilities (npm audit)

---

Configuration

API Keys

The quickest way to add an API key is the built-in /key command:

/key               # interactive provider picker → paste key → done
/key list          # see what is configured
/key remove        # interactive removal
/key remove google # remove a specific provider directly

Keys are stored in ~/.neuroloop/auth.json. Supported providers:

You can also set keys via environment variables or by editing ~/.neuroloop/auth.json directly:

{
  "google":    { "type": "api_key", "key": "AIza..." },
  "anthropic": { "type": "api_key", "key": "sk-ant-..." },
  "openai":    { "type": "api_key", "key": "sk-..." }
}

After adding a key, switch to a model from that provider with /model (Ctrl+L).

Models

NeuroLoop supports all pi-compatible providers (Anthropic, OpenAI, Gemini) as well as any locally running Ollama models. gpt-oss:20b is always registered as the default Ollama model even when Ollama is unreachable.

Model selection order:

1. Model saved in the current session
2. Default from ~/.neuroloop/settings.json
3. First built-in provider with a valid API key or OAuth token
4. Skill app local LLM — auto-discovered on port 8375 via direct HTTP (/v1/chat/completions)
5. First available Ollama model (gpt-oss:20b when none are listed first)

When the Skill app has a running LLM, it is registered as the skill-llm provider and connected to directly via the OpenAI-compatible HTTP API — no CLI overhead for inference. If the Skill app's LLM server has an API key configured, set the SKILL_LLM_API_KEY environment variable.

EXG foundation model (inside NeuroSkill)

NeuroSkill's EXG embedding/search stack is powered by ZUNA (Zyphra/ZUNA), which converts 5-second EXG epochs into dense vectors used for similarity search, session compare, cross-modal joins, and sleep-stage pipelines.

Skill app local LLM catalog families

Current catalog families include:

• Qwen 3.5 (4B / 9B / 27B, plus Opus-distilled variants)
• Qwen coder lines (Qwen2.5.1 Coder 7B, Qwen3 Coder Next)
• Qwen3-VL 30B multimodal
• GPT-OSS 20B
• Ministral 3 14B (Instruct + Reasoning)
• Gemma 3 270M
• Phi-4 Reasoning Plus
• OmniCoder 9B
• LFM2.5-VL 1.6B
• Uncensored Qwen 3.5 variants (4B / 9B / 27B / 35B-A3B)

Many families include mmproj projector files for image input in the Skill app LLM server.

NeuroSkill backend capability alignment (from ../skill)

NeuroLoop tracks the NeuroSkill backend capabilities and exposes them through /neuro, neuroskill_run, and convenience commands where available. This includes:

• native multi-device EXG connectors (Muse, Ganglion, MW75, Hermes)
• local and remote LSL transports
• EXG embedding/search model stack (ZUNA)
• local Skill LLM server + model catalog management + tool-calling
• screenshot/vision/OCR cross-modal memory workflows
• HealthKit, Oura, and Calendar integrations

NeuroSkill™ Server Port

The agent auto-discovers the NeuroSkill™ server port using a cross-platform strategy:

1. Saved port from ~/.neuroloop/neuroskill_port.json
2. HTTP health-check probe on common ports (8375, 8376, 8377)
3. lsof process scan (macOS/Linux)

You can override the port at runtime with /exg port <n> — the chosen port is persisted for future sessions. The port is also passed to the neuroskill CLI via --port to skip mDNS discovery.

---

How to Cite

If you use NeuroLoop™ in academic work, please cite it as:

@software{neuroloop2026,
  author       = {Nataliya Kosmyna and Eugene Hauptmann},
  title        = {{NeuroLoop™: An EXG-Aware AI Companion Powered by Real-Time Brainwave Analysis}},
  year         = {2026},
  version      = {0.0.9},
  url          = {https://github.com/NeuroSkill-com/neuroloop}
}

Related Work

NeuroLoop™ builds on the following neuroscientific foundations. If you use specific metrics, please also cite the primary literature listed in METRICS.md. Key upstream works include:

@article{krigolson2017choosing,
  author  = {Krigolson, Olav E. and Williams, Chad C. and Norton, Angela and Hassall, Cameron D. and Colino, Francisco L.},
  title   = {Choosing {MUSE}: Validation of a Low-Cost, Portable {EEG} System for {ERP} Research},
  journal = {Frontiers in Neuroscience},
  volume  = {11},
  pages   = {109},
  year    = {2017},
  doi     = {10.3389/fnins.2017.00109}
}

@inproceedings{cannard2021validating,
  author    = {Cannard, Christian and Wahbeh, Helané and Delorme, Arnaud},
  title     = {Validating the Wearable {MUSE} Headset for {EEG} Spectral Analysis and Frontal Alpha Asymmetry},
  booktitle = {2021 IEEE International Conference on Bioinformatics and Biomedicine (BIBM)},
  year      = {2021},
  doi       = {10.1109/bibm52615.2021.9669778}
}

@article{coan2004frontal,
  author  = {Coan, James A. and Allen, John J. B.},
  title   = {Frontal {EEG} Asymmetry as a Moderator and Mediator of Emotion},
  journal = {Biological Psychology},
  volume  = {67},
  number  = {1--2},
  pages   = {7--50},
  year    = {2004},
  doi     = {10.1016/j.biopsycho.2004.03.002}
}

@article{casali2013theoretically,
  author  = {Casali, Adenauer G. and Gosseries, Olivia and Rosanova, Mario and Boly, Melanie and Sarasso, Simone and Casali, Karina R. and Casarotto, Silvia and Bruno, Marie-Aurélie and Laureys, Steven and Tononi, Giulio and Massimini, Marcello},
  title   = {A Theoretically Based Index of Consciousness Independent of Sensory Processing and Behavior},
  journal = {Science Translational Medicine},
  volume  = {5},
  number  = {198},
  pages   = {198ra105},
  year    = {2013},
  doi     = {10.1126/scitranslmed.3006294}
}

@article{klimesch1999eeg,
  author  = {Klimesch, Wolfgang},
  title   = {{EEG} Alpha and Theta Oscillations Reflect Cognitive and Memory Performance: A Review and Analysis},
  journal = {Brain Research Reviews},
  volume  = {29},
  number  = {2--3},
  pages   = {169--195},
  year    = {1999},
  doi     = {10.1016/s0165-0173(98)00056-3}
}

@article{donoghue2020parameterizing,
  author  = {Donoghue, Thomas and Haller, Matar and Peterson, Erik J. and Varma, Paroma and Sebastian, Priyadarshini and Gao, Richard and Noto, Torben and Lara, Antonio H. and Wallis, Jonathan D. and Knight, Robert T. and Bhatt, Parveen and Voytek, Bradley},
  title   = {Parameterizing Neural Power Spectra into Periodic and Aperiodic Components},
  journal = {Nature Neuroscience},
  volume  = {23},
  pages   = {1655--1665},
  year    = {2020},
  doi     = {10.1038/s41593-020-00744-x}
}

@article{pope1995biocybernetic,
  author  = {Pope, Alan T. and Bogart, Edward H. and Bartolome, Debbie S.},
  title   = {Biocybernetic System Evaluates Indices of Operator Engagement in Automated Task},
  journal = {Biological Psychology},
  volume  = {40},
  number  = {1--2},
  pages   = {187--195},
  year    = {1995},
  doi     = {10.1016/0301-0511(95)05116-3}
}

@article{bandt2002permutation,
  author  = {Bandt, Christoph and Pompe, Bernd},
  title   = {Permutation Entropy: A Natural Complexity Measure for Time Series},
  journal = {Physical Review Letters},
  volume  = {88},
  number  = {17},
  pages   = {174102},
  year    = {2002},
  doi     = {10.1103/PhysRevLett.88.174102}
}

@article{tononi2004information,
  author  = {Tononi, Giulio},
  title   = {An Information Integration Theory of Consciousness},
  journal = {BMC Neuroscience},
  volume  = {5},
  pages   = {42},
  year    = {2004},
  doi     = {10.1186/1471-2202-5-42}
}

---

License

GPLv3