Use live BCI cognitive and mood state from NeuroSkill.

Skill metadata


Source	Optional — install with `mibyan skills install official/health/neuroskill-bci`
Path	`optional-skills/health/neuroskill-bci`
Version	`1.0.0`
Author	Mibyan + Nous Research
License	MIT
Platforms	linux, macos, windows
Tags	`BCI`, `neurofeedback`, `health`, `focus`, `EEG`, `cognitive-state`, `biometrics`, `neuroskill`

Reference: full SKILL.md

The following is the complete skill definition that Mibyan loads when this skill is triggered. This is what the agent sees as instructions when the skill is active.

NeuroSkill BCI Integration

Connect Mibyan 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 <command>`

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 <N>`	Override server port (default: auto-discover, usually 8375)
`--ws`	Force WebSocket transport
`--http`	Force HTTP transport
`--k <N>`	Nearest neighbors count (search, search-labels)
`--seconds <N>`	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.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.

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 <minutes> 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 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 <UTC> --end <UTC> --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: efficiency_pct, onset_latency_min, rem_latency_min, bout counts
Healthy targets: N3 15–25%, REM 20–25%, efficiency >85%, onset <20 min

npx neuroskill sleep --json | jq '.summary | {n3: .n3_epochs, rem: .rem_epochs}'
npx neuroskill sleep --json | jq '.analysis.efficiency_pct'

Use this when the user mentions sleep, tiredness, or recovery.

6. Labeling Moments

npx neuroskill label "breakthrough"
npx neuroskill label "studying algorithms"
npx neuroskill label "post-meditation"
npx neuroskill label --json "focus block start"   # returns label_id

Auto-label moments when:

User reports a breakthrough or insight
User starts a new task type (e.g., “switching to code review”)
User completes a significant protocol
User asks you to mark the current moment
A notable state transition occurs (entering/leaving flow)

Labels are stored in a database and indexed for later retrieval via search-labels and interactive commands.

7. Real-Time Streaming

npx neuroskill listen --seconds 30 --json
npx neuroskill listen --seconds 5 --json | jq '[.[] | select(.event == "scores")]'

Streams live WebSocket events (EXG, PPG, IMU, scores, labels) for the specified duration. Requires WebSocket connection (not available with --http). Use this for continuous monitoring scenarios or to observe metric changes in real-time during a protocol.

8. UMAP Visualization

npx neuroskill umap --json                      # auto: last 2 sessions
npx neuroskill umap --a-start <UTC> --a-end <UTC> --b-start <UTC> --b-end <UTC> --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)
< 0.5 → Similar brain states across both sessions

9. Proactive State Awareness

Session Start Check

At the beginning of a session, optionally run a status check if the user mentions they’re wearing their device or asks about their state:

npx neuroskill status --json

Inject a brief state summary:

“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.30 sustained)
User is about to do something cognitively demanding and asks for readiness

Do NOT interrupt flow state to report metrics. If 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 < 0.40, TBR > 1.5 → Theta-Beta Neurofeedback Anchor or Box Breathing
Relaxation < 0.30, stress_index high → Cardiac Coherence or 4-7-8 Breathing
Cognitive Load > 0.70 sustained → Cognitive Load Offload (mind dump)
Drowsiness > 0.60 → Ultradian Reset or Wake Reset
FAA < 0 (negative) → FAA Rebalancing
Flow State (focus > 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

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

​Skill metadata

​Reference: full SKILL.md

​NeuroSkill BCI Integration

​Prerequisites

​Verify Setup

​CLI Reference: npx neuroskill <command>

​Global Flags

​1. Checking Current State

​Get Live Metrics

​Key Fields in the Response

​Interpreting the Output

​2. Session Analysis

​Single Session Breakdown

​List All Sessions

​3. Historical Search

​Neural Similarity Search

​Semantic Label Search

​Cross-Modal Graph Search

​4. Session Comparison

​5. Sleep Data

​6. Labeling Moments

​7. Real-Time Streaming

​8. UMAP Visualization

​9. Proactive State Awareness

​Session Start Check

​When to Proactively Mention State

​10. Suggesting Protocols

​11. Additional Tools

​Focus Timer

​Calibration

​OS Notifications

​Raw JSON Passthrough

​Error Handling

​Example Interactions

​References

Skill metadata

Reference: full SKILL.md

NeuroSkill BCI Integration

Prerequisites

Verify Setup

CLI Reference: `npx neuroskill <command>`

Global Flags

1. Checking Current State

Get Live Metrics

Key Fields in the Response

Interpreting the Output

2. Session Analysis

Single Session Breakdown

List All Sessions

3. Historical Search

Neural Similarity Search

Semantic Label Search

Cross-Modal Graph Search

4. Session Comparison

5. Sleep Data

6. Labeling Moments

7. Real-Time Streaming

8. UMAP Visualization

9. Proactive State Awareness

Session Start Check

When to Proactively Mention State

10. Suggesting Protocols

11. Additional Tools

Focus Timer

Calibration

OS Notifications

Raw JSON Passthrough

Error Handling

Example Interactions

References