neuroskill-bci skill

NeuroSkill BCI Integration

Connect Hermes 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).

Global Flags

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.40 → suggest a break or protocol
• Drowsiness > 0.60 → fatigue warning, micro-sleep risk
• Relaxation < 0.30 → stress intervention needed
• Cognitive Load > 0.70 sustained → mind dump or break
• TBR > 1.5 → theta-dominant, reduced executive control
• FAA < 0 → withdrawal/negative affect — consider FAA rebalancing
• SNR < 3 dB → unreliable signal, suggest electrode repositioning

2. Session Analysis

Single Session Breakdown

npx neuroskill session --json         # most recent session
npx neuroskill session 1 --json       # previous session
npx neuroskill session 0 --json | jq '{focus: .metrics.focus, trend: .trends.focus}'

Returns full metrics with first-half vs second-half trends ("up", "down", "flat"). Use this to describe how a session evolved:

"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 <UTC> --end <UTC> --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 <UTC> --a-end <UTC> --b-start <UTC> --b-end <UTC> --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