A command-line interface for the NeuroSkill real-time EEG analysis API. WebSocket & HTTP transport, 20+ EEG indices, sleep staging, GPU-accelerated HNSW search.
⚠ Research Use Only — not a clinical tool, not FDA/CE-cleared.
npm install -g neuroskill npx neuroskill <command> Getting Started
Install via npm or build from source. Requires a locally running NeuroSkill server — NeuroSkill™ auto-discovers the port via mDNS or lsof.
# Install globally
npm install -g neuroskill
# Or run from source
git clone https://github.com/NeuroSkill-com/neuroskill neuroskill && cd neuroskill
npm install && npm run build
# First command: full snapshot
neuroskill status
# Pipe scores to jq
neuroskill status --json | jq '.scores.focus'
# Live neurological correlates
neuroskill neurological
# Stream events for 10 seconds
neuroskill listen--port <n> flag — skips all discovery_skill._tcp — 5 s timeoutlsof / pgrep fallback — probes TCP LISTEN ports--json raw JSON · pipe-safe--full summary + colorized JSON--dot Graphviz DOT (interactive only)Architecture
From raw EEG µV to semantic brain-state search — the full signal processing pipeline.
Muse BLE (256 Hz raw µV)
│
▼
High-pass filter (0.5 Hz — removes DC drift)
│
▼
Low-pass filter (50 Hz — removes high-freq noise)
│
▼
Notch filter (50/60 Hz + harmonics — powerline)
│
▼
GPU overlap-save convolution (gpu-fft, ~125 ms latency)
│
▼
Hann-windowed FFT (512-sample window, ≈2 s epoch)
│
▼
Band-power integration (Welch-style per-band PSD)
│
▼
ZUNA encoder → 128-dim EEG embedding (5-sec epochs)
│
▼
HNSW index (approximate nearest-neighbor search)
│
▼
All indices, ratios, composite scores, WebSocket/HTTPMuse 2 / Muse S — 4 dry electrodes, 256 Hz BLE streaming.
CH1 TP9 CH2 AF7 CH3 AF8 CH4 TP10 Dual transport — NeuroSkill™ picks the best one automatically.
Full-duplex, low-latency. Live event streaming. Auto-selected when server is reachable.
POST to http://127.0.0.1:<port>/. curl-friendly. No streaming.
GPU-accelerated deep neural encoder. Converts each 5-second EEG epoch into a 128-dimensional vector.
Hierarchical Navigable Small World graph for approximate nearest-neighbor search over millions of embeddings.
cosine (0=identical)sub-millisecondeeg.sqlite per dayGPU UMAP (fast-umap)Cross-modal search combining semantic text embeddings with EEG similarity in a directed graph.
# 4-layer cross-modal graph search
neuroskill interactive "deep focus" --k-text 5 --k-eeg 5 --k-labels 3
# Layer 0: query embedding
# Layer 1: semantically similar text labels
# Layer 2: EEG moments from label time windows
# Layer 3: labels discovered near those EEG moments
# Get the graph as JSON
neuroskill interactive "focus" --json | jq '.nodes | length'
# Extract found labels from layer 3
neuroskill interactive "meditation" --json \
| jq '[.nodes[] | select(.kind == "found_label") | .text]'
# Render as SVG with graphviz
neuroskill interactive "anxiety" --dot | dot -Tsvg > graph.svg# ANN similarity search: find past moments like now
neuroskill search # auto: last session, k=5
neuroskill search --k 20 # more neighbors
neuroskill search --start 1740412800 --end 1740415500
# Search over 14,000+ embeddings in milliseconds
# Results include distance, timestamp, and metrics:
# {
# "distance": 0.0231,
# "timestamp_unix": 1740320040,
# "metrics": { "focus": 0.73, "hr": 66.2 }
# }
# Search labels semantically
neuroskill search-labels "meditation" --mode both --k 10
# Available modes: text | context | bothCLI Reference
All commands work over WebSocket and HTTP. Use --json for pipe-safe output.
neuroskill status Full device / session / scores snapshot
neuroskill neurological EEG correlate indices + consciousness metrics (0–100)
neuroskill session [index] All metrics + trends for one session (0 = latest)
neuroskill sessions List all recording sessions across all days
neuroskill label "text" Create a timestamped annotation on the current moment
neuroskill search-labels "query" Semantic vector search across all your EEG annotations
neuroskill interactive "keyword" Cross-modal 4-layer graph search (labels → EEG → labels)
neuroskill search ANN EEG-similarity search (auto: last session, k=5)
neuroskill compare Side-by-side A/B metrics (auto: last 2 sessions)
neuroskill sleep [index] Sleep staging — index selects session (0 = latest)
neuroskill umap 3D UMAP projection with GPU acceleration + live progress
neuroskill listen Stream broadcast events (EEG packets, scores, labels)
neuroskill calibrate Open calibration window and start immediately
neuroskill timer Open focus-timer window and start work phase
neuroskill notify "title" Show a native OS notification
neuroskill say "text" Speak text aloud via on-device TTS
neuroskill raw '{"command":"..."}' Send arbitrary JSON and print full response
| command | description | category |
|---|---|---|
neuroskill status | Full device / session / scores snapshot | core |
neuroskill neurological | EEG correlate indices + consciousness metrics (0–100) | core |
neuroskill session [index] | All metrics + trends for one session (0 = latest) | core |
neuroskill sessions | List all recording sessions across all days | core |
neuroskill label "text" | Create a timestamped annotation on the current moment | annotation |
neuroskill search-labels "query" | Semantic vector search across all your EEG annotations | search |
neuroskill interactive "keyword" | Cross-modal 4-layer graph search (labels → EEG → labels) | search |
neuroskill search | ANN EEG-similarity search (auto: last session, k=5) | search |
neuroskill compare | Side-by-side A/B metrics (auto: last 2 sessions) | analysis |
neuroskill sleep [index] | Sleep staging — index selects session (0 = latest) | analysis |
neuroskill umap | 3D UMAP projection with GPU acceleration + live progress | analysis |
neuroskill listen | Stream broadcast events (EEG packets, scores, labels) | stream |
neuroskill calibrate | Open calibration window and start immediately | control |
neuroskill timer | Open focus-timer window and start work phase | control |
neuroskill notify "title" | Show a native OS notification | control |
neuroskill say "text" | Speak text aloud via on-device TTS | control |
neuroskill raw '{"command":"..."}' | Send arbitrary JSON and print full response | dev |
--port <n> Connect to explicit port (skips mDNS)--ws Force WebSocket transport--http Force HTTP REST transport--json Raw JSON only — no summary, no colors--full Human-readable + colorized JSON below--dot Graphviz DOT to stdout (interactive only)--k <n> Number of nearest neighbors--k-text <n> (interactive) k for text-label search--k-eeg <n> (interactive) k for EEG-similarity search--k-labels <n> (interactive) k for label-proximity--reach <n> (interactive) temporal reach in minutes--mode <m> search-labels: text | context | both--poll <n> (status) Re-poll every N seconds--seconds <n> (listen) Duration in seconds--no-color Disable ANSI colorsSignal Science
Every metric is derived from peer-reviewed neuroscience research. Each 5-second epoch is processed at ~4 Hz update rate.
| score | formula | what it measures |
|---|---|---|
Focus β / (α + θ) | β / (α + θ) | Cognitive engagement and attentional control. The foundational biocybernetics engagement index. |
Relaxation α / (β + θ) | α / (β + θ) | Alpha dominance. High = calm restful waking state. Inverse of focus. |
Engagement β / (α + θ) | β / (α + θ) | General mental involvement across tasks. Same ratio as focus, different context. |
Meditation α/β · stillness · HRV | α/β · stillness · HRV | Convergence of alpha elevation, physical stillness, and parasympathetic HRV. |
Cognitive Load θ_frontal / α_temporal | θ_frontal / α_temporal | Frontal theta rises systematically with working memory load. |
Drowsiness TAR + TBR + (1−BAR) | TAR + TBR + (1−BAR) | Sleep-onset EEG hallmarks. > 60 = significant fatigue and impairment risk. |
Mood 50 + 50·tanh(FAA·k) | 50 + 50·tanh(FAA·k) | Rescaled FAA. > 60 = approach/positive, < 40 = withdrawal/negative. |
Drowsiness, mind-wandering, inward attention. > 1.5 = theta dominant.
Alert vs. relaxed. High = engaged cognition, Low = drowsy.
Most replicated ADHD biomarker in research. > 3 = elevated.
Approach (positive) vs. withdrawal (negative) motivation and emotional valence.
Uniformity of power distribution. Near 1 = white noise, Low = dominant frequency.
Cognitive speed marker. ~10 Hz typical; slows with age, fatigue, pathology.
Time-domain complexity. Higher = more irregular (awake). Lower = sleep/anesthesia.
θ–γ coupling: working memory encoding mechanism. Strong during demanding tasks.
Long-range temporal correlations. α≈0.6–0.9 = healthy waking EEG.
Ordinal complexity. High = maximal irregularity. Consciousness marker.
Phase sync between hemispheres. High = bilateral coordination, meditation.
Frequency below which 95% of power lies. Decreases with drowsiness.
From the Muse forehead PPG sensor (64 Hz, red + infrared LEDs). IBI series extracted via peak detection.
| metric | unit | formula | interpretation |
|---|---|---|---|
| Heart Rate | bpm | 60000 / mean(IBI_ms) | Instantaneous heart rate from PPG inter-beat intervals. Normal: 50–100 bpm. |
| RMSSD | ms | √(Σ(IBI_{i+1}−IBI_i)²/(N−1)) | Primary vagal tone metric. > 50 ms = good parasympathetic activity. |
| SDNN | ms | std(IBI) | Overall HRV from all physiological sources. Global autonomic variability. |
| pNN50 | % | count(|ΔIBI| > 50ms) / N | Percentage of beat-to-beat changes exceeding 50ms. Parasympathetic marker. |
| LF/HF | ratio | Power[0.04–0.15] / Power[0.15–0.4] | Sympatho-vagal balance. > 2 = sympathetic dominance (stress). < 0.5 = parasympathetic. |
| SpO₂ | % | f(R) Beer-Lambert estimate | Estimated blood oxygen saturation. Normal: 95–100%. |
| Baevsky SI | a.u. | AMo / (2·MxDMn·Mo) | Sympathetic activity proxy from IBI histogram. Normal resting: 50–150. |
Simplified AASM heuristics applied per 5-second epoch. Auto-generated for sessions ≥ 30 minutes.
P_α > P_θ and BAR > 0.8TAR > 1.0, SEF95 < 15 HzP_θ dominant; P_δ rising; P_β lowP_δ > P_θ + P_α; DTR > 2P_θ high; P_δ low; BAR moderateDeveloper Reference
Every NeuroSkill™ command maps directly to a JSON API. Use the CLI, HTTP POST, or WebSocket — all return the same payload.
# Every command works over plain HTTP POST
curl -s -X POST http://127.0.0.1:8375/ \
-H "Content-Type: application/json" \
-d '{"command":"status"}' | jq '.scores.focus'
# Neurological indices
curl -s -X POST http://127.0.0.1:8375/ \
-H "Content-Type: application/json" \
-d '{"command":"neurological"}' | jq '.neurological'
# Search labels
curl -s -X POST http://127.0.0.1:8375/ \
-H "Content-Type: application/json" \
-d '{"command":"search_labels","query":"deep focus","k":5}'
# Interactive graph search
curl -s -X POST http://127.0.0.1:8375/ \
-H "Content-Type: application/json" \
-d '{
"command": "interactive_search",
"query": "deep focus",
"k_text": 5,
"k_eeg": 5,
"k_labels": 3,
"reach_minutes": 10
}'// WebSocket — full duplex, low latency
const ws = new WebSocket('ws://127.0.0.1:8375');
ws.onopen = () => {
ws.send(JSON.stringify({ command: 'status' }));
};
ws.onmessage = (event) => {
const data = JSON.parse(event.data);
console.log('Focus:', data.scores?.focus);
};
// Stream live events
ws.send(JSON.stringify({ command: 'listen' }));
// wscat from terminal:
// wscat -c ws://127.0.0.1:8375
// > {"command":"status"}status response shape{
"command": "status",
"ok": true,
"device": {
"state": "connected",
"name": "Muse-A1B2",
"battery": 73,
"firmware": "1.3.4"
},
"session": {
"start_utc": 1740412800,
"duration_secs": 1847,
"n_epochs": 369
},
"signal_quality": {
"tp9": 0.95, "af7": 0.88,
"af8": 0.91, "tp10": 0.97
},
"scores": {
"focus": 0.70,
"relaxation": 0.40,
"engagement": 0.60,
"meditation": 0.52,
"mood": 0.55,
"cognitive_load": 0.33,
"drowsiness": 0.10,
"hr": 68.2,
"snr": 14.3,
"stillness": 0.88,
"bands": {
"rel_delta": 0.28,
"rel_theta": 0.18,
"rel_alpha": 0.32,
"rel_beta": 0.17,
"rel_gamma": 0.05
},
"faa": 0.042,
"tar": 0.56,
"bar": 0.53,
"tbr": 1.06,
"apf": 10.1,
"coherence": 0.614
}
}# Poll focus every 5 seconds
while true; do
neuroskill status --json | jq '.scores.focus'
sleep 5
done
# Alert when focus drops below 40%
while true; do
FOCUS=$(neuroskill status --json | jq '.scores.focus')
if (( $(echo "$FOCUS < 0.4" | bc -l) )); then
neuroskill notify "Focus dropped" "Current: $FOCUS"
fi
sleep 10
done
# Label then immediately search
neuroskill label "deep work block"
neuroskill search-labels "deep work" --mode both
# Render interactive graph as SVG
neuroskill interactive "focus" --dot | dot -Tsvg > graph.svg
# Compare last two sessions
neuroskill compare --json | jq '.insights.deltas.focus'
# Sleep staging for last night
neuroskill sleep 0 --json | jq '.summary'.scores.focus — Current focus score (0–1).scores.bands.rel_alpha — Relative alpha power (0–1).scores.faa — Frontal Alpha Asymmetry.scores.tbr — Theta/Beta Ratio (ADHD proxy).device.battery — Battery percentage.session.n_epochs — Number of 5-s epochs recorded.signal_quality.af7 — AF7 channel quality (0–1).neurological.adhd_index — ADHD correlate (0–100).consciousness.lzc — Lempel-Ziv complexity proxy.sleep.n3_epochs — Deep sleep epoch count.history.current_streak_days — Recording streak in days.embeddings.total — Total embeddings in databaseUse Cases
neuroskill status --json | jq '.scores.focus'neuroskill label "focus block start"neuroskill search-labels "deep work"neuroskill compare --json | jq '.insights.improved'neuroskill neurological --json | jq '.neurological.anxiety_index'neuroskill status --json | jq '.scores.{"bar":.scores.bar}'neuroskill label "feeling stressed"neuroskill interactive "anxiety"neuroskill sleep 0 --json | jq '.summary'neuroskill sleep --json | jq '.analysis.efficiency_pct'neuroskill session 0 --json | jq '.metrics.drowsiness'neuroskill umap # visualize sleep vs wakeneuroskill status --json | jq '.scores.meditation'neuroskill neurological --json | jq '.consciousness'neuroskill label "meditation start"neuroskill search-labels "meditation" --mode bothneuroskill status --json | jq '.scores.cognitive_load'neuroskill neurological --json | jq '.neurological.adhd_index'neuroskill session 0 --json | jq '.trends.cognitive_load'neuroskill compare --json | jq '.insights.deltas.tbr'neuroskill status --json | jq '.scores.focus'neuroskill notify "Focus Alert" "Low focus detected"neuroskill timer # start focus timerneuroskill raw '{"command":"status"}'Install NeuroSkill™, connect your Muse headset, and get EEG data straight in your terminal in under a minute.