Neuroskill Bci

NeuroSkill BCI Integration

Connect Zorro to a running NeuroSkill instance to read real-time brain and body metrics from a BCI wearable. Use this to give cognitively-aware responses, suggest interventions, and track mental performance over time.

> ⚠️ Research Use Only — NeuroSkill is an open-source research tool. It is > NOT a medical device and has NOT been cleared by the FDA, CE, or any regulatory > body. Never use these metrics for clinical diagnosis or treatment.

See references/metrics.md for the full metric reference, references/protocols.md for intervention protocols, and references/api.md for the WebSocket/HTTP API.

---

Prerequisites

• Node.js 20+ installed (node --version)
• NeuroSkill desktop app running with a connected BCI device
• BCI hardware: Muse 2, Muse S, or OpenBCI (4-channel EEG + PPG + IMU via BLE)
• npx neuroskill status returns data without errors

Verify Setup

node --version                    # Must be 20+
npx neuroskill status             # Full system snapshot
npx neuroskill status --json      # Machine-parseable JSON

If npx neuroskill status returns an error, tell the user:

• Make sure the NeuroSkill desktop app is open
• Ensure the BCI device is powered on and connected via Bluetooth
• Check signal quality — green indicators in NeuroSkill (≥0.7 per electrode)
• If command not found, install Node.js 20+

---

CLI Reference: npx neuroskill

All commands support --json (raw JSON, pipe-safe) and --full (human summary + JSON).

| Command | Description | |---------|-------------| | status | Full system snapshot: device, scores, bands, ratios, sleep, history | | session [N] | Single session breakdown with first/second half trends (0=most recent) | | sessions | List all recorded sessions across all days | | search | ANN similarity search for neurally similar historical moments | | compare | A/B session comparison with metric deltas and trend analysis | | sleep [N] | Sleep stage classification (Wake/N1/N2/N3/REM) with analysis | | label "text" | Create a timestamped annotation at the current moment | | search-labels "query" | Semantic vector search over past labels | | interactive "query" | Cross-modal 4-layer graph search (text → EXG → labels) | | listen | Real-time event streaming (default 5s, set --seconds N) | | umap | 3D UMAP projection of session embeddings | | calibrate | Open calibration window and start a profile | | timer | Launch focus timer (Pomodoro/Deep Work/Short Focus presets) | | notify "title" "body" | Send an OS notification via the NeuroSkill app | | raw '{json}' | Raw JSON passthrough to the server |

Global Flags

| Flag | Description | |------|-------------| | --json | Raw JSON output (no ANSI, pipe-safe) | | --full | Human summary + colorized JSON | | --port | Override server port (default: auto-discover, usually 8375) | | --ws | Force WebSocket transport | | --http | Force HTTP transport | | --k | Nearest neighbors count (search, search-labels) | | --seconds | Duration for listen (default: 5) | | --trends | Show per-session metric trends (sessions) | | --dot | Graphviz DOT output (interactive) |

---

1. Checking Current State

Get Live Metrics

npx neuroskill status --json

Always use --json for reliable parsing. The default output is colorized human-readable text.

Key Fields in the Response

The scores object contains all live metrics (0–1 scale unless noted):

{
  "scores": {
    "focus": 0.70,           // β / (α + θ) — sustained attention
    "relaxation": 0.40,      // α / (β + θ) — calm wakefulness
    "engagement": 0.60,      // active mental investment
    "meditation": 0.52,      // alpha + stillness + HRV coherence
    "mood": 0.55,            // composite from FAA, TAR, BAR
    "cognitive_load": 0.33,  // frontal θ / temporal α · f(FAA, TBR)
    "drowsiness": 0.10,      // TAR + TBR + falling spectral centroid
    "hr": 68.2,              // heart rate in bpm (from PPG)
    "snr": 14.3,             // signal-to-noise ratio in dB
    "stillness": 0.88,       // 0–1; 1 = perfectly still
    "faa": 0.042,            // Frontal Alpha Asymmetry (+ = approach)
    "tar": 0.56,             // Theta/Alpha Ratio
    "bar": 0.53,             // Beta/Alpha Ratio
    "tbr": 1.06,             // Theta/Beta Ratio (ADHD proxy)
    "apf": 10.1,             // Alpha Peak Frequency in Hz
    "coherence": 0.614,      // inter-hemispheric coherence
    "bands": {
      "rel_delta": 0.28, "rel_theta": 0.18,
      "rel_alpha": 0.32, "rel_beta": 0.17, "rel_gamma": 0.05
    }
  }
}

Also includes: device (state, battery, firmware), signal_quality (per-electrode 0–1), session (duration, epochs), embeddings, labels, sleep summary, and history.

Interpreting the Output

Parse the JSON and translate metrics into natural language. Never report raw numbers alone — always give them meaning:

DO: > "Your focus is solid right now at 0.70 — that's flow state territory. Heart > rate is steady at 68 bpm and your FAA is positive, which suggests good > approach motivation. Great time to tackle something complex."

DON'T: > "Focus: 0.70, Relaxation: 0.40, HR: 68"

Key interpretation thresholds (see references/metrics.md for the full guide):

• Focus > 0.70 → flow state territory, protect it
• Focus 0.60 → fatigue warning, micro-sleep risk
• Relaxation 0.70 sustained → mind dump or break
• TBR > 1.5 → theta-dominant, reduced executive control
• **FAA "Your focus started at 0.64 and climbed to 0.76 by the end — a clear upward trend.

> Cognitive load dropped from 0.38 to 0.28, suggesting the task became more automatic > as you settled in."

List All Sessions

npx neuroskill sessions --json
npx neuroskill sessions --trends      # show per-session metric trends

---

3. Historical Search

Neural Similarity Search

npx neuroskill search --json                    # auto: last session, k=5
npx neuroskill search --k 10 --json             # 10 nearest neighbors
npx neuroskill search --start  --end  --json

Finds moments in history that are neurally similar using HNSW approximate nearest-neighbor search over 128-D ZUNA embeddings. Returns distance statistics, temporal distribution (hour of day), and top matching days.

Use this when the user asks:

• "When was I last in a state like this?"
• "Find my best focus sessions"
• "When do I usually crash in the afternoon?"

Semantic Label Search

npx neuroskill search-labels "deep focus" --k 10 --json
npx neuroskill search-labels "stress" --json | jq '[.results[].EXG_metrics.tbr]'

Searches label text using vector embeddings (Xenova/bge-small-en-v1.5). Returns matching labels with their associated EXG metrics at the time of labeling.

Cross-Modal Graph Search

npx neuroskill interactive "deep focus" --json
npx neuroskill interactive "deep focus" --dot | dot -Tsvg > graph.svg

4-layer graph: query → text labels → EXG points → nearby labels. Use --k-text, --k-EXG, --reach to tune.

---

4. Session Comparison

npx neuroskill compare --json                   # auto: last 2 sessions
npx neuroskill compare --a-start  --a-end  --b-start  --b-end  --json

Returns metric deltas with absolute change, percentage change, and direction for ~50 metrics. Also includes insights.improved[] and insights.declined[] arrays, sleep staging for both sessions, and a UMAP job ID.

Interpret comparisons with context — mention trends, not just deltas: > "Yesterday you had two strong focus blocks (10am and 2pm). Today you've had one > starting around 11am that's still going. Your overall engagement is higher today > but there have been more stress spikes — your stress index jumped 15% and > FAA dipped negative more often."

# Sort metrics by improvement percentage
npx neuroskill compare --json | jq '.insights.deltas | to_entries | sort_by(.value.pct) | reverse'

---

5. Sleep Data

npx neuroskill sleep --json                     # last 24 hours
npx neuroskill sleep 0 --json                   # most recent sleep session
npx neuroskill sleep --start  --end  --json

Returns epoch-by-epoch sleep staging (5-second windows) with analysis:

• Stage codes: 0=Wake, 1=N1, 2=N2, 3=N3 (deep), 4=REM
• Analysis: efficiencypct, onsetlatencymin, remlatency_min, bout counts
• Healthy targets: N3 15–25%, REM 20–25%, efficiency >85%, onset --a-end --b-start --b-end --json

GPU-accelerated 3D UMAP projection of ZUNA embeddings. The `separation_score`
indicates how neurally distinct two sessions are:
- **> 1.5** → Sessions are neurally distinct (different brain states)
- ** "Quick check-in: focus is building at 0.62, relaxation is good at 0.55, and your
> FAA is positive — approach motivation is engaged. Looks like a solid start."

### When to Proactively Mention State

Mention cognitive state **only** when:
- User explicitly asks ("How am I doing?", "Check my focus")
- User reports difficulty concentrating, stress, or fatigue
- A critical threshold is crossed (drowsiness > 0.70, focus  0.75, protect the
session — silence is the correct response.

---

## 10. Suggesting Protocols

When metrics indicate a need, suggest a protocol from `references/protocols.md`.
Always ask before starting — never interrupt flow state:

> "Your focus has been declining for the past 15 minutes and TBR is climbing past
> 1.5 — signs of theta dominance and mental fatigue. Want me to walk you through
> a Theta-Beta Neurofeedback Anchor? It's a 90-second exercise that uses rhythmic
> counting and breath to suppress theta and lift beta."

Key triggers:
- **Focus  1.5** → Theta-Beta Neurofeedback Anchor or Box Breathing
- **Relaxation  0.70 sustained** → Cognitive Load Offload (mind dump)
- **Drowsiness > 0.60** → Ultradian Reset or Wake Reset
- **FAA  0.75, engagement > 0.70)** → Do NOT interrupt
- **High stillness + headache_index** → Neck Release Sequence
- **Low RMSSD (< 25ms)** → Vagal Toning

---

## 11. Additional Tools

### Focus Timer
```bash
npx neuroskill timer --json

Launches the Focus Timer window with Pomodoro (25/5), Deep Work (50/10), or Short Focus (15/5) presets.

Calibration

npx neuroskill calibrate
npx neuroskill calibrate --profile "Eyes Open"

Opens the calibration window. Useful when signal quality is poor or the user wants to establish a personalized baseline.

OS Notifications

npx neuroskill notify "Break Time" "Your focus has been declining for 20 minutes"

Raw JSON Passthrough

npx neuroskill raw '{"command":"status"}' --json

For any server command not yet mapped to a CLI subcommand.

---

Error Handling

| Error | Likely Cause | Fix | |-------|-------------|-----| | npx neuroskill status hangs | NeuroSkill app not running | Open NeuroSkill desktop app | | device.state: "disconnected" | BCI device not connected | Check Bluetooth, device battery | | All scores return 0 | Poor electrode contact | Reposition headband, moisten electrodes | | signal_quality values < 0.7 | Loose electrodes | Adjust fit, clean electrode contacts | | SNR < 3 dB | Noisy signal | Minimize head movement, check environment | | command not found: npx | Node.js not installed | Install Node.js 20+ |

---

Example Interactions

"How am I doing right now?"

npx neuroskill status --json

→ Interpret scores naturally, mentioning focus, relaxation, mood, and any notable ratios (FAA, TBR). Suggest an action only if metrics indicate a need.

"I can't concentrate"

npx neuroskill status --json

→ Check if metrics confirm it (high theta, low beta, rising TBR, high drowsiness). → If confirmed, suggest an appropriate protocol from references/protocols.md. → If metrics look fine, the issue may be motivational rather than neurological.

"Compare my focus today vs yesterday"

npx neuroskill compare --json

→ Interpret trends, not just numbers. Mention what improved, what declined, and possible causes.

"When was I last in a flow state?"

npx neuroskill search-labels "flow" --json
npx neuroskill search --json

→ Report timestamps, associated metrics, and what the user was doing (from labels).

"How did I sleep?"

npx neuroskill sleep --json

→ Report sleep architecture (N3%, REM%, efficiency), compare to healthy targets, and note any issues (high wake epochs, low REM).

"Mark this moment — I just had a breakthrough"

npx neuroskill label "breakthrough"

→ Confirm label saved. Optionally note the current metrics to remember the state.

---

References

• NeuroSkill Paper — arXiv:2603.03212 (Kosmyna & Hauptmann, MIT Media Lab)
• NeuroSkill Desktop App (GPLv3)
• NeuroLoop CLI Companion (GPLv3)
• MIT Media Lab Project

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: braxtonROSE4
• Source: braxtonROSE4/zorro-agent
• License: MIT

Install and usage instructions live in the source repository linked above.