ossrules.md

neuroskill-bci

Use live BCI cognitive and mood state from NeuroSkill.

  • BCI
  • neurofeedback
  • health
  • focus
  • EEG
  • cognitive-state
  • biometrics
  • neuroskill

Declared platforms: linux · macos · windows

Install
npx skills add 'https://github.com/NousResearch/hermes-agent/tree/main/optional-skills/health/neuroskill-bci'
Download bundle ↓
main · 24fd22b ↗Scanned 2026-09-15

Contributors

GitHub-linked commit authors for this SKILL.md at the saved revision. Co-authors and history before file renames are not included.

File history ↗

SKILL.md

SKILL.mdBrowse 4 files
View on GitHub
4,395 tokens

16,401 bytes
Token encoding: o200k_base
Snapshot 24fd22b

---name: neuroskill-bcidescription: "Use live BCI cognitive and mood state from NeuroSkill."platforms: [linux, macos, windows]version: 1.0.0author: Hermes Agent + Nous Researchlicense: MITmetadata:  hermes:    tags: [BCI, neurofeedback, health, focus, EEG, cognitive-state, biometrics, neuroskill]    category: health    related_skills: []--- # NeuroSkill BCI Integration Connect Hermes to a running [NeuroSkill](https://neuroskill.com/) instance to readreal-time brain and body metrics from a BCI wearable. Use this to givecognitively-aware responses, suggest interventions, and track mental performanceover 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```bashnode --version                    # Must be 20+npx neuroskill status             # Full system snapshotnpx 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```bashnpx neuroskill status --json``` **Always use `--json`** for reliable parsing. The default output is colorizedhuman-readable text. ### Key Fields in the Response The `scores` object contains all live metrics (0–1 scale unless noted): ```jsonc{  "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 rawnumbers 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```bashnpx neuroskill session --json         # most recent sessionnpx neuroskill session 1 --json       # previous sessionnpx 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```bashnpx neuroskill sessions --jsonnpx neuroskill sessions --trends      # show per-session metric trends``` --- ## 3. Historical Search ### Neural Similarity Search```bashnpx neuroskill search --json                    # auto: last session, k=5npx neuroskill search --k 10 --json             # 10 nearest neighborsnpx neuroskill search --start <UTC> --end <UTC> --json``` Finds moments in history that are neurally similar using HNSW approximatenearest-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```bashnpx neuroskill search-labels "deep focus" --k 10 --jsonnpx neuroskill search-labels "stress" --json | jq '[.results[].EXG_metrics.tbr]'``` Searches label text using vector embeddings (Xenova/bge-small-en-v1.5). Returnsmatching labels with their associated EXG metrics at the time of labeling. ### Cross-Modal Graph Search```bashnpx neuroskill interactive "deep focus" --jsonnpx 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```bashnpx neuroskill compare --json                   # auto: last 2 sessionsnpx 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." ```bash# Sort metrics by improvement percentagenpx neuroskill compare --json | jq '.insights.deltas | to_entries | sort_by(.value.pct) | reverse'``` --- ## 5. Sleep Data```bashnpx neuroskill sleep --json                     # last 24 hoursnpx neuroskill sleep 0 --json                   # most recent sleep sessionnpx 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 ```bashnpx 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```bashnpx 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```bashnpx neuroskill listen --seconds 30 --jsonnpx neuroskill listen --seconds 5 --json | jq '[.[] | select(.event == "scores")]'``` Streams live WebSocket events (EXG, PPG, IMU, scores, labels) for the specifiedduration. Requires WebSocket connection (not available with `--http`). Use this for continuous monitoring scenarios or to observe metric changes in real-timeduring a protocol. --- ## 8. UMAP Visualization```bashnpx neuroskill umap --json                      # auto: last 2 sessionsnpx 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 CheckAt the beginning of a session, optionally run a status check if the user mentionsthey're wearing their device or asks about their state:```bashnpx 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 thesession — 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```bashnpx neuroskill timer --json```Launches the Focus Timer window with Pomodoro (25/5), Deep Work (50/10), orShort Focus (15/5) presets. ### Calibration```bashnpx neuroskill calibratenpx neuroskill calibrate --profile "Eyes Open"```Opens the calibration window. Useful when signal quality is poor or the userwants to establish a personalized baseline. ### OS Notifications```bashnpx neuroskill notify "Break Time" "Your focus has been declining for 20 minutes"``` ### Raw JSON Passthrough```bashnpx 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?"**```bashnpx 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"**```bashnpx 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"**```bashnpx neuroskill compare --json```→ Interpret trends, not just numbers. Mention what improved, what declined, and  possible causes. **"When was I last in a flow state?"**```bashnpx neuroskill search-labels "flow" --jsonnpx neuroskill search --json```→ Report timestamps, associated metrics, and what the user was doing (from labels). **"How did I sleep?"**```bashnpx 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"**```bashnpx neuroskill label "breakthrough"```→ Confirm label saved. Optionally note the current metrics to remember the state. --- ## References - [NeuroSkill Paper — arXiv:2603.03212](https://arxiv.org/abs/2603.03212) (Kosmyna & Hauptmann, MIT Media Lab)- [NeuroSkill Desktop App](https://github.com/NeuroSkill-com/skill) (GPLv3)- [NeuroLoop CLI Companion](https://github.com/NeuroSkill-com/neuroloop) (GPLv3)- [MIT Media Lab Project](https://www.media.mit.edu/projects/neuroskill/overview/)
Discovery context

Discovered by repository scan. No exact path reference found in the snapshot’s root AGENTS.md.

← All Hermes Agent skillsProject instructions →