neuroskill-bci

name neuroskill-bci description Use live BCI cognitive and mood state from NeuroSkill. platforms ["linux","macos","windows"] version 1.0.0 author Hermes Agent + Nous Research license MIT metadata {"hermes":{"tags":["BCI","neurofeedback","health","focus","EEG","cognitive-state","biometrics","neuroskill"],"category":"health","related_skills":[]}} 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 <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. 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 <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