[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M758P49YAW37ECF5RWTPTDH9":3,"skill-same:01M758P49YAW37ECF5RWTPTDH9":80},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":43,"commitSha":44,"skillDirectory":45,"forksCount":46,"repositoryHtmlUrl":47,"repositoryHomepageUrl":48,"ownerHtmlUrl":49,"ownerBlogUrl":6,"ownerDescription":50,"updatedAt":51,"install":52,"resources":65},"01M758P49YAW37ECF5RWTPTDH9","neuroskill-bci",null,"Connect to a running NeuroSkill instance and incorporate the user's real-time cognitive and emotional state (focus, relaxation, mood, cognitive load, drowsiness, heart rate, HRV, sleep staging, and 40+ derived EXG scores) into responses. Requires a BCI wearable (Muse 2\u002FS or OpenBCI) and the NeuroSkill desktop app running locally.","lukemcqueen\u002Fsteadfaste-fleet","lukemcqueen","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F405240?v=4","01M757MHPAGRXTJAT46SKZP98R","Luke McQueen","01M757MHPZ573KP8DT9GB8SBQ7",4,"MIT","https:\u002F\u002Fgithub.com\u002Flukemcqueen\u002Fsteadfaste-fleet\u002Fblob\u002Fmain\u002Fskills\u002Fhealth\u002Fneuroskill-bci\u002FSKILL.md",[],[],"2026-11-12 13:55:43",false,"---\nname: neuroskill-bci\ndescription: >\n  Connect to a running NeuroSkill instance and incorporate the user's real-time\n  cognitive and emotional state (focus, relaxation, mood, cognitive load, drowsiness,\n  heart rate, HRV, sleep staging, and 40+ derived EXG scores) into responses.\n  Requires a BCI wearable (Muse 2\u002FS or OpenBCI) and the NeuroSkill desktop app\n  running locally.\nplatforms: [linux, macos, windows]\nversion: 1.0.0\nauthor: Hermes Agent + Nous Research\nlicense: MIT\nmetadata:\n  hermes:\n    tags: [BCI, neurofeedback, health, focus, EEG, cognitive-state, biometrics, neuroskill]\n    category: health\n    related_skills: []\n---\n\n# NeuroSkill BCI Integration\n\nConnect Hermes to a running [NeuroSkill](https:\u002F\u002Fneuroskill.com\u002F) instance to read\nreal-time brain and body metrics from a BCI wearable. Use this to give\ncognitively-aware responses, suggest interventions, and track mental performance\nover time.\n\n> **⚠️ Research Use Only** — NeuroSkill is an open-source research tool. It is\n> NOT a medical device and has NOT been cleared by the FDA, CE, or any regulatory\n> body. Never use these metrics for clinical diagnosis or treatment.\n\nSee `references\u002Fmetrics.md` for the full metric reference, `references\u002Fprotocols.md`\nfor intervention protocols, and `references\u002Fapi.md` for the WebSocket\u002FHTTP API.\n\n---\n\n## Prerequisites\n\n- **Node.js 20+** installed (`node --version`)\n- **NeuroSkill desktop app** running with a connected BCI device\n- **BCI hardware**: Muse 2, Muse S, or OpenBCI (4-channel EEG + PPG + IMU via BLE)\n- `npx neuroskill status` returns data without errors\n\n### Verify Setup\n```bash\nnode --version                    # Must be 20+\nnpx neuroskill status             # Full system snapshot\nnpx neuroskill status --json      # Machine-parseable JSON\n```\n\nIf `npx neuroskill status` returns an error, tell the user:\n- Make sure the NeuroSkill desktop app is open\n- Ensure the BCI device is powered on and connected via Bluetooth\n- Check signal quality — green indicators in NeuroSkill (≥0.7 per electrode)\n- If `command not found`, install Node.js 20+\n\n---\n\n## CLI Reference: `npx neuroskill \u003Ccommand>`\n\nAll commands support `--json` (raw JSON, pipe-safe) and `--full` (human summary + JSON).\n\n| Command | Description |\n|---------|-------------|\n| `status` | Full system snapshot: device, scores, bands, ratios, sleep, history |\n| `session [N]` | Single session breakdown with first\u002Fsecond half trends (0=most recent) |\n| `sessions` | List all recorded sessions across all days |\n| `search` | ANN similarity search for neurally similar historical moments |\n| `compare` | A\u002FB session comparison with metric deltas and trend analysis |\n| `sleep [N]` | Sleep stage classification (Wake\u002FN1\u002FN2\u002FN3\u002FREM) with analysis |\n| `label \"text\"` | Create a timestamped annotation at the current moment |\n| `search-labels \"query\"` | Semantic vector search over past labels |\n| `interactive \"query\"` | Cross-modal 4-layer graph search (text → EXG → labels) |\n| `listen` | Real-time event streaming (default 5s, set `--seconds N`) |\n| `umap` | 3D UMAP projection of session embeddings |\n| `calibrate` | Open calibration window and start a profile |\n| `timer` | Launch focus timer (Pomodoro\u002FDeep Work\u002FShort Focus presets) |\n| `notify \"title\" \"body\"` | Send an OS notification via the NeuroSkill app |\n| `raw '{json}'` | Raw JSON passthrough to the server |\n\n### Global Flags\n| Flag | Description |\n|------|-------------|\n| `--json` | Raw JSON output (no ANSI, pipe-safe) |\n| `--full` | Human summary + colorized JSON |\n| `--port \u003CN>` | Override server port (default: auto-discover, usually 8375) |\n| `--ws` | Force WebSocket transport |\n| `--http` | Force HTTP transport |\n| `--k \u003CN>` | Nearest neighbors count (search, search-labels) |\n| `--seconds \u003CN>` | Duration for listen (default: 5) |\n| `--trends` | Show per-session metric trends (sessions) |\n| `--dot` | Graphviz DOT output (interactive) |\n\n---\n\n## 1. Checking Current State\n\n### Get Live Metrics\n```bash\nnpx neuroskill status --json\n```\n\n**Always use `--json`** for reliable parsing. The default output is colorized\nhuman-readable text.\n\n### Key Fields in the Response\n\nThe `scores` object contains all live metrics (0–1 scale unless noted):\n\n```jsonc\n{\n  \"scores\": {\n    \"focus\": 0.70,           \u002F\u002F β \u002F (α + θ) — sustained attention\n    \"relaxation\": 0.40,      \u002F\u002F α \u002F (β + θ) — calm wakefulness\n    \"engagement\": 0.60,      \u002F\u002F active mental investment\n    \"meditation\": 0.52,      \u002F\u002F alpha + stillness + HRV coherence\n    \"mood\": 0.55,            \u002F\u002F composite from FAA, TAR, BAR\n    \"cognitive_load\": 0.33,  \u002F\u002F frontal θ \u002F temporal α · f(FAA, TBR)\n    \"drowsiness\": 0.10,      \u002F\u002F TAR + TBR + falling spectral centroid\n    \"hr\": 68.2,              \u002F\u002F heart rate in bpm (from PPG)\n    \"snr\": 14.3,             \u002F\u002F signal-to-noise ratio in dB\n    \"stillness\": 0.88,       \u002F\u002F 0–1; 1 = perfectly still\n    \"faa\": 0.042,            \u002F\u002F Frontal Alpha Asymmetry (+ = approach)\n    \"tar\": 0.56,             \u002F\u002F Theta\u002FAlpha Ratio\n    \"bar\": 0.53,             \u002F\u002F Beta\u002FAlpha Ratio\n    \"tbr\": 1.06,             \u002F\u002F Theta\u002FBeta Ratio (ADHD proxy)\n    \"apf\": 10.1,             \u002F\u002F Alpha Peak Frequency in Hz\n    \"coherence\": 0.614,      \u002F\u002F inter-hemispheric coherence\n    \"bands\": {\n      \"rel_delta\": 0.28, \"rel_theta\": 0.18,\n      \"rel_alpha\": 0.32, \"rel_beta\": 0.17, \"rel_gamma\": 0.05\n    }\n  }\n}\n```\n\nAlso includes: `device` (state, battery, firmware), `signal_quality` (per-electrode 0–1),\n`session` (duration, epochs), `embeddings`, `labels`, `sleep` summary, and `history`.\n\n### Interpreting the Output\n\nParse the JSON and translate metrics into natural language. Never report raw\nnumbers alone — always give them meaning:\n\n**DO:**\n> \"Your focus is solid right now at 0.70 — that's flow state territory. Heart\n> rate is steady at 68 bpm and your FAA is positive, which suggests good\n> approach motivation. Great time to tackle something complex.\"\n\n**DON'T:**\n> \"Focus: 0.70, Relaxation: 0.40, HR: 68\"\n\nKey interpretation thresholds (see `references\u002Fmetrics.md` for the full guide):\n- **Focus > 0.70** → flow state territory, protect it\n- **Focus \u003C 0.40** → suggest a break or protocol\n- **Drowsiness > 0.60** → fatigue warning, micro-sleep risk\n- **Relaxation \u003C 0.30** → stress intervention needed\n- **Cognitive Load > 0.70 sustained** → mind dump or break\n- **TBR > 1.5** → theta-dominant, reduced executive control\n- **FAA \u003C 0** → withdrawal\u002Fnegative affect — consider FAA rebalancing\n- **SNR \u003C 3 dB** → unreliable signal, suggest electrode repositioning\n\n---\n\n## 2. Session Analysis\n\n### Single Session Breakdown\n```bash\nnpx neuroskill session --json         # most recent session\nnpx neuroskill session 1 --json       # previous session\nnpx neuroskill session 0 --json | jq '{focus: .metrics.focus, trend: .trends.focus}'\n```\n\nReturns full metrics with **first-half vs second-half trends** (`\"up\"`, `\"down\"`, `\"flat\"`).\nUse this to describe how a session evolved:\n\n> \"Your focus started at 0.64 and climbed to 0.76 by the end — a clear upward trend.\n> Cognitive load dropped from 0.38 to 0.28, suggesting the task became more automatic\n> as you settled in.\"\n\n### List All Sessions\n```bash\nnpx neuroskill sessions --json\nnpx neuroskill sessions --trends      # show per-session metric trends\n```\n\n---\n\n## 3. Historical Search\n\n### Neural Similarity Search\n```bash\nnpx neuroskill search --json                    # auto: last session, k=5\nnpx neuroskill search --k 10 --json             # 10 nearest neighbors\nnpx neuroskill search --start \u003CUTC> --end \u003CUTC> --json\n```\n\nFinds moments in history that are neurally similar using HNSW approximate\nnearest-neighbor search over 128-D ZUNA embeddings. Returns distance statistics,\ntemporal distribution (hour of day), and top matching days.\n\nUse this when the user asks:\n- \"When was I last in a state like this?\"\n- \"Find my best focus sessions\"\n- \"When do I usually crash in the afternoon?\"\n\n### Semantic Label Search\n```bash\nnpx neuroskill search-labels \"deep focus\" --k 10 --json\nnpx neuroskill search-labels \"stress\" --json | jq '[.results[].EXG_metrics.tbr]'\n```\n\nSearches label text using vector embeddings (Xenova\u002Fbge-small-en-v1.5). Returns\nmatching labels with their associated EXG metrics at the time of labeling.\n\n### Cross-Modal Graph Search\n```bash\nnpx neuroskill interactive \"deep focus\" --json\nnpx neuroskill interactive \"deep focus\" --dot | dot -Tsvg > graph.svg\n```\n\n4-layer graph: query → text labels → EXG points → nearby labels. Use `--k-text`,\n`--k-EXG`, `--reach \u003Cminutes>` to tune.\n\n---\n\n## 4. Session Comparison\n```bash\nnpx neuroskill compare --json                   # auto: last 2 sessions\nnpx neuroskill compare --a-start \u003CUTC> --a-end \u003CUTC> --b-start \u003CUTC> --b-end \u003CUTC> --json\n```\n\nReturns metric deltas with absolute change, percentage change, and direction for\n~50 metrics. Also includes `insights.improved[]` and `insights.declined[]` arrays,\nsleep staging for both sessions, and a UMAP job ID.\n\nInterpret comparisons with context — mention trends, not just deltas:\n> \"Yesterday you had two strong focus blocks (10am and 2pm). Today you've had one\n> starting around 11am that's still going. Your overall engagement is higher today\n> but there have been more stress spikes — your stress index jumped 15% and\n> FAA dipped negative more often.\"\n\n```bash\n# Sort metrics by improvement percentage\nnpx neuroskill compare --json | jq '.insights.deltas | to_entries | sort_by(.value.pct) | reverse'\n```\n\n---\n\n## 5. Sleep Data\n```bash\nnpx neuroskill sleep --json                     # last 24 hours\nnpx neuroskill sleep 0 --json                   # most recent sleep session\nnpx neuroskill sleep --start \u003CUTC> --end \u003CUTC> --json\n```\n\nReturns epoch-by-epoch sleep staging (5-second windows) with analysis:\n- **Stage codes**: 0=Wake, 1=N1, 2=N2, 3=N3 (deep), 4=REM\n- **Analysis**: efficiency_pct, onset_latency_min, rem_latency_min, bout counts\n- **Healthy targets**: N3 15–25%, REM 20–25%, efficiency >85%, onset \u003C20 min\n\n```bash\nnpx neuroskill sleep --json | jq '.summary | {n3: .n3_epochs, rem: .rem_epochs}'\nnpx neuroskill sleep --json | jq '.analysis.efficiency_pct'\n```\n\nUse this when the user mentions sleep, tiredness, or recovery.\n\n---\n\n## 6. Labeling Moments\n```bash\nnpx neuroskill label \"breakthrough\"\nnpx neuroskill label \"studying algorithms\"\nnpx neuroskill label \"post-meditation\"\nnpx neuroskill label --json \"focus block start\"   # returns label_id\n```\n\nAuto-label moments when:\n- User reports a breakthrough or insight\n- User starts a new task type (e.g., \"switching to code review\")\n- User completes a significant protocol\n- User asks you to mark the current moment\n- A notable state transition occurs (entering\u002Fleaving flow)\n\nLabels are stored in a database and indexed for later retrieval via `search-labels`\nand `interactive` commands.\n\n---\n\n## 7. Real-Time Streaming\n```bash\nnpx neuroskill listen --seconds 30 --json\nnpx neuroskill listen --seconds 5 --json | jq '[.[] | select(.event == \"scores\")]'\n```\n\nStreams live WebSocket events (EXG, PPG, IMU, scores, labels) for the specified\nduration. Requires WebSocket connection (not available with `--http`).\n\nUse this for continuous monitoring scenarios or to observe metric changes in real-time\nduring a protocol.\n\n---\n\n## 8. UMAP Visualization\n```bash\nnpx neuroskill umap --json                      # auto: last 2 sessions\nnpx neuroskill umap --a-start \u003CUTC> --a-end \u003CUTC> --b-start \u003CUTC> --b-end \u003CUTC> --json\n```\n\nGPU-accelerated 3D UMAP projection of ZUNA embeddings. The `separation_score`\nindicates how neurally distinct two sessions are:\n- **> 1.5** → Sessions are neurally distinct (different brain states)\n- **\u003C 0.5** → Similar brain states across both sessions\n\n---\n\n## 9. Proactive State Awareness\n\n### Session Start Check\nAt the beginning of a session, optionally run a status check if the user mentions\nthey're wearing their device or asks about their state:\n```bash\nnpx neuroskill status --json\n```\n\nInject a brief state summary:\n> \"Quick check-in: focus is building at 0.62, relaxation is good at 0.55, and your\n> FAA is positive — approach motivation is engaged. Looks like a solid start.\"\n\n### When to Proactively Mention State\n\nMention cognitive state **only** when:\n- User explicitly asks (\"How am I doing?\", \"Check my focus\")\n- User reports difficulty concentrating, stress, or fatigue\n- A critical threshold is crossed (drowsiness > 0.70, focus \u003C 0.30 sustained)\n- User is about to do something cognitively demanding and asks for readiness\n\n**Do NOT** interrupt flow state to report metrics. If focus > 0.75, protect the\nsession — silence is the correct response.\n\n---\n\n## 10. Suggesting Protocols\n\nWhen metrics indicate a need, suggest a protocol from `references\u002Fprotocols.md`.\nAlways ask before starting — never interrupt flow state:\n\n> \"Your focus has been declining for the past 15 minutes and TBR is climbing past\n> 1.5 — signs of theta dominance and mental fatigue. Want me to walk you through\n> a Theta-Beta Neurofeedback Anchor? It's a 90-second exercise that uses rhythmic\n> counting and breath to suppress theta and lift beta.\"\n\nKey triggers:\n- **Focus \u003C 0.40, TBR > 1.5** → Theta-Beta Neurofeedback Anchor or Box Breathing\n- **Relaxation \u003C 0.30, stress_index high** → Cardiac Coherence or 4-7-8 Breathing\n- **Cognitive Load > 0.70 sustained** → Cognitive Load Offload (mind dump)\n- **Drowsiness > 0.60** → Ultradian Reset or Wake Reset\n- **FAA \u003C 0 (negative)** → FAA Rebalancing\n- **Flow State (focus > 0.75, engagement > 0.70)** → Do NOT interrupt\n- **High stillness + headache_index** → Neck Release Sequence\n- **Low RMSSD (\u003C 25ms)** → Vagal Toning\n\n---\n\n## 11. Additional Tools\n\n### Focus Timer\n```bash\nnpx neuroskill timer --json\n```\nLaunches the Focus Timer window with Pomodoro (25\u002F5), Deep Work (50\u002F10), or\nShort Focus (15\u002F5) presets.\n\n### Calibration\n```bash\nnpx neuroskill calibrate\nnpx neuroskill calibrate --profile \"Eyes Open\"\n```\nOpens the calibration window. Useful when signal quality is poor or the user\nwants to establish a personalized baseline.\n\n### OS Notifications\n```bash\nnpx neuroskill notify \"Break Time\" \"Your focus has been declining for 20 minutes\"\n```\n\n### Raw JSON Passthrough\n```bash\nnpx neuroskill raw '{\"command\":\"status\"}' --json\n```\nFor any server command not yet mapped to a CLI subcommand.\n\n---\n\n## Error Handling\n\n| Error | Likely Cause | Fix |\n|-------|-------------|-----|\n| `npx neuroskill status` hangs | NeuroSkill app not running | Open NeuroSkill desktop app |\n| `device.state: \"disconnected\"` | BCI device not connected | Check Bluetooth, device battery |\n| All scores return 0 | Poor electrode contact | Reposition headband, moisten electrodes |\n| `signal_quality` values \u003C 0.7 | Loose electrodes | Adjust fit, clean electrode contacts |\n| SNR \u003C 3 dB | Noisy signal | Minimize head movement, check environment |\n| `command not found: npx` | Node.js not installed | Install Node.js 20+ |\n\n---\n\n## Example Interactions\n\n**\"How am I doing right now?\"**\n```bash\nnpx neuroskill status --json\n```\n→ Interpret scores naturally, mentioning focus, relaxation, mood, and any notable\n  ratios (FAA, TBR). Suggest an action only if metrics indicate a need.\n\n**\"I can't concentrate\"**\n```bash\nnpx neuroskill status --json\n```\n→ Check if metrics confirm it (high theta, low beta, rising TBR, high drowsiness).\n→ If confirmed, suggest an appropriate protocol from `references\u002Fprotocols.md`.\n→ If metrics look fine, the issue may be motivational rather than neurological.\n\n**\"Compare my focus today vs yesterday\"**\n```bash\nnpx neuroskill compare --json\n```\n→ Interpret trends, not just numbers. Mention what improved, what declined, and\n  possible causes.\n\n**\"When was I last in a flow state?\"**\n```bash\nnpx neuroskill search-labels \"flow\" --json\nnpx neuroskill search --json\n```\n→ Report timestamps, associated metrics, and what the user was doing (from labels).\n\n**\"How did I sleep?\"**\n```bash\nnpx neuroskill sleep --json\n```\n→ Report sleep architecture (N3%, REM%, efficiency), compare to healthy targets,\n  and note any issues (high wake epochs, low REM).\n\n**\"Mark this moment — I just had a breakthrough\"**\n```bash\nnpx neuroskill label \"breakthrough\"\n```\n→ Confirm label saved. Optionally note the current metrics to remember the state.\n\n---\n\n## References\n\n- [NeuroSkill Paper — arXiv:2603.03212](https:\u002F\u002Farxiv.org\u002Fabs\u002F2603.03212) (Kosmyna & Hauptmann, MIT Media Lab)\n- [NeuroSkill Desktop App](https:\u002F\u002Fgithub.com\u002FNeuroSkill-com\u002Fskill) (GPLv3)\n- [NeuroLoop CLI Companion](https:\u002F\u002Fgithub.com\u002FNeuroSkill-com\u002Fneuroloop) (GPLv3)\n- [MIT Media Lab Project](https:\u002F\u002Fwww.media.mit.edu\u002Fprojects\u002Fneuroskill\u002Foverview\u002F)\n","# NeuroSkill BCI Integration\n\nConnect Hermes to a running [NeuroSkill](https:\u002F\u002Fneuroskill.com\u002F) instance to read\nreal-time brain and body metrics from a BCI wearable. Use this to give\ncognitively-aware responses, suggest interventions, and track mental performance\nover time.\n\n> **⚠️ Research Use Only** — NeuroSkill is an open-source research tool. It is\n> NOT a medical device and has NOT been cleared by the FDA, CE, or any regulatory\n> body. Never use these metrics for clinical diagnosis or treatment.\n\nSee `references\u002Fmetrics.md` for the full metric reference, `references\u002Fprotocols.md`\nfor intervention protocols, and `references\u002Fapi.md` for the WebSocket\u002FHTTP API.\n\n---\n\n## Prerequisites\n\n- **Node.js 20+** installed (`node --version`)\n- **NeuroSkill desktop app** running with a connected BCI device\n- **BCI hardware**: Muse 2, Muse S, or OpenBCI (4-channel EEG + PPG + IMU via BLE)\n- `npx neuroskill status` returns data without errors\n\n### Verify Setup\n```bash\nnode --version                    # Must be 20+\nnpx neuroskill status             # Full system snapshot\nnpx neuroskill status --json      # Machine-parseable JSON\n```\n\nIf `npx neuroskill status` returns an error, tell the user:\n- Make sure the NeuroSkill desktop app is open\n- Ensure the BCI device is powered on and connected via Bluetooth\n- Check signal quality — green indicators in NeuroSkill (≥0.7 per electrode)\n- If `command not found`, install Node.js 20+\n\n---\n\n## CLI Reference: `npx neuroskill \u003Ccommand>`\n\nAll commands support `--json` (raw JSON, pipe-safe) and `--full` (human summary + JSON).\n\n| Command | Description |\n|---------|-------------|\n| `status` | Full system snapshot: device, scores, bands, ratios, sleep, history |\n| `session [N]` | Single session breakdown with first\u002Fsecond half trends (0=most recent) |\n| `sessions` | List all recorded sessions across all days |\n| `search` | ANN similarity search for neurally similar historical moments |\n| `compare` | A\u002FB session comparison with metric deltas and trend analysis |\n| `sleep [N]` | Sleep stage classification (Wake\u002FN1\u002FN2\u002FN3\u002FREM) with analysis |\n| `label \"text\"` | Create a timestamped annotation at the current moment |\n| `search-labels \"query\"` | Semantic vector search over past labels |\n| `interactive \"query\"` | Cross-modal 4-layer graph search (text → EXG → labels) |\n| `listen` | Real-time event streaming (default 5s, set `--seconds N`) |\n| `umap` | 3D UMAP projection of session embeddings |\n| `calibrate` | Open calibration window and start a profile |\n| `timer` | Launch focus timer (Pomodoro\u002FDeep Work\u002FShort Focus presets) |\n| `notify \"title\" \"body\"` | Send an OS notification via the NeuroSkill app |\n| `raw '{json}'` | Raw JSON passthrough to the server |\n\n### Global Flags\n| Flag | Description |\n|------|-------------|\n| `--json` | Raw JSON output (no ANSI, pipe-safe) |\n| `--full` | Human summary + colorized JSON |\n| `--port \u003CN>` | Override server port (default: auto-discover, usually 8375) |\n| `--ws` | Force WebSocket transport |\n| `--http` | Force HTTP transport |\n| `--k \u003CN>` | Nearest neighbors count (search, search-labels) |\n| `--seconds \u003CN>` | Duration for listen (default: 5) |\n| `--trends` | Show per-session metric trends (sessions) |\n| `--dot` | Graphviz DOT output (interactive) |\n\n---\n\n## 1. Checking Current State\n\n### Get Live Metrics\n```bash\nnpx neuroskill status --json\n```\n\n**Always use `--json`** for reliable parsing. The default output is colorized\nhuman-readable text.\n\n### Key Fields in the Response\n\nThe `scores` object contains all live metrics (0–1 scale unless noted):\n\n```jsonc\n{\n  \"scores\": {\n    \"focus\": 0.70,           \u002F\u002F β \u002F (α + θ) — sustained attention\n    \"relaxation\": 0.40,      \u002F\u002F α \u002F (β + θ) — calm wakefulness\n    \"engagement\": 0.60,      \u002F\u002F active mental investment\n    \"meditation\": 0.52,      \u002F\u002F alpha + stillness + HRV coherence\n    \"mood\": 0.55,            \u002F\u002F composite from FAA, TAR, BAR\n    \"cognitive_load\": 0.33,  \u002F\u002F frontal θ \u002F temporal α · f(FAA, TBR)\n    \"drowsiness\": 0.10,      \u002F\u002F TAR + TBR + falling spectral centroid\n    \"hr\": 68.2,              \u002F\u002F heart rate in bpm (from PPG)\n    \"snr\": 14.3,             \u002F\u002F signal-to-noise ratio in dB\n    \"stillness\": 0.88,       \u002F\u002F 0–1; 1 = perfectly still\n    \"faa\": 0.042,            \u002F\u002F Frontal Alpha Asymmetry (+ = approach)\n    \"tar\": 0.56,             \u002F\u002F Theta\u002FAlpha Ratio\n    \"bar\": 0.53,             \u002F\u002F Beta\u002FAlpha Ratio\n    \"tbr\": 1.06,             \u002F\u002F Theta\u002FBeta Ratio (ADHD proxy)\n    \"apf\": 10.1,             \u002F\u002F Alpha Peak Frequency in Hz\n    \"coherence\": 0.614,      \u002F\u002F inter-hemispheric coherence\n    \"bands\": {\n      \"rel_delta\": 0.28, \"rel_theta\": 0.18,\n      \"rel_alpha\": 0.32, \"rel_beta\": 0.17, \"rel_gamma\": 0.05\n    }\n  }\n}\n```\n\nAlso includes: `device` (state, battery, firmware), `signal_quality` (per-electrode 0–1),\n`session` (duration, epochs), `embeddings`, `labels`, `sleep` summary, and `history`.\n\n### Interpreting the Output\n\nParse the JSON and translate metrics into natural language. Never report raw\nnumbers alone — always give them meaning:\n\n**DO:**\n> \"Your focus is solid right now at 0.70 — that's flow state territory. Heart\n> rate is steady at 68 bpm and your FAA is positive, which suggests good\n> approach motivation. Great time to tackle something complex.\"\n\n**DON'T:**\n> \"Focus: 0.70, Relaxation: 0.40, HR: 68\"\n\nKey interpretation thresholds (see `references\u002Fmetrics.md` for the full guide):\n- **Focus > 0.70** → flow state territory, protect it\n- **Focus \u003C 0.40** → suggest a break or protocol\n- **Drowsiness > 0.60** → fatigue warning, micro-sleep risk\n- **Relaxation \u003C 0.30** → stress intervention needed\n- **Cognitive Load > 0.70 sustained** → mind dump or break\n- **TBR > 1.5** → theta-dominant, reduced executive control\n- **FAA \u003C 0** → withdrawal\u002Fnegative affect — consider FAA rebalancing\n- **SNR \u003C 3 dB** → unreliable signal, suggest electrode repositioning\n\n---\n\n## 2. Session Analysis\n\n### Single Session Breakdown\n```bash\nnpx neuroskill session --json         # most recent session\nnpx neuroskill session 1 --json       # previous session\nnpx neuroskill session 0 --json | jq '{focus: .metrics.focus, trend: .trends.focus}'\n```\n\nReturns full metrics with **first-half vs second-half trends** (`\"up\"`, `\"down\"`, `\"flat\"`).\nUse this to describe how a session evolved:\n\n> \"Your focus started at 0.64 and climbed to 0.76 by the end — a clear upward trend.\n> Cognitive load dropped from 0.38 to 0.28, suggesting the task became more automatic\n> as you settled in.\"\n\n### List All Sessions\n```bash\nnpx neuroskill sessions --json\nnpx neuroskill sessions --trends      # show per-session metric trends\n```\n\n---\n\n## 3. Historical Search\n\n### Neural Similarity Search\n```bash\nnpx neuroskill search --json                    # auto: last session, k=5\nnpx neuroskill search --k 10 --json             # 10 nearest neighbors\nnpx neuroskill search --start \u003CUTC> --end \u003CUTC> --json\n```\n\nFinds moments in history that are neurally similar using HNSW approximate\nnearest-neighbor search over 128-D ZUNA embeddings. Returns distance statistics,\ntemporal distribution (hour of day), and top matching days.\n\nUse this when the user asks:\n- \"When was I last in a state like this?\"\n- \"Find my best focus sessions\"\n- \"When do I usually crash in the afternoon?\"\n\n### Semantic Label Search\n```bash\nnpx neuroskill search-labels \"deep focus\" --k 10 --json\nnpx neuroskill search-labels \"stress\" --json | jq '[.results[].EXG_metrics.tbr]'\n```\n\nSearches label text using vector embeddings (Xenova\u002Fbge-small-en-v1.5). Returns\nmatching labels with their associated EXG metrics at the time of labeling.\n\n### Cross-Modal Graph Search\n```bash\nnpx neuroskill interactive \"deep focus\" --json\nnpx neuroskill interactive \"deep focus\" --dot | dot -Tsvg > graph.svg\n```\n\n4-layer graph: query → text labels → EXG points → nearby labels. Use `--k-text`,\n`--k-EXG`, `--reach \u003Cminutes>` to tune.\n\n---\n\n## 4. Session Comparison\n```bash\nnpx neuroskill compare --json                   # auto: last 2 sessions\nnpx neuroskill compare --a-start \u003CUTC> --a-end \u003CUTC> --b-start \u003CUTC> --b-end \u003CUTC> --json\n```\n\nReturns metric deltas with absolute change, percentage change, and direction for\n~50 metrics. Also includes `insights.improved[]` and `insights.declined[]` arrays,\nsleep staging for both sessions, and a UMAP job ID.\n\nInterpret comparisons with context — mention trends, not just deltas:\n> \"Yesterday you had two strong focus blocks (10am and 2pm). Today you've had one\n> starting around 11am that's still going. Your overall engagement is higher today\n> but there have been more stress spikes — your stress index jumped 15% and\n> FAA dipped negative more often.\"\n\n```bash\n# Sort metrics by improvement percentage\nnpx neuroskill compare --json | jq '.insights.deltas | to_entries | sort_by(.value.pct) | reverse'\n```\n\n---\n\n## 5. Sleep Data\n```bash\nnpx neuroskill sleep --json                     # last 24 hours\nnpx neuroskill sleep 0 --json                   # most recent sleep session\nnpx neuroskill sleep --start \u003CUTC> --end \u003CUTC> --json\n```\n\nReturns epoch-by-epoch sleep staging (5-second windows) with analysis:\n- **Stage codes**: 0=Wake, 1=N1, 2=N2, 3=N3 (deep), 4=REM\n- **Analysis**: efficiency_pct, onset_latency_min, rem_latency_min, bout counts\n- **Healthy targets**: N3 15–25%, REM 20–25%, efficiency >85%, onset \u003C20 min\n\n```bash\nnpx neuroskill sleep --json | jq '.summary | {n3: .n3_epochs, rem: .rem_epochs}'\nnpx neuroskill sleep --json | jq '.analysis.efficiency_pct'\n```\n\nUse this when the user mentions sleep, tiredness, or recovery.\n\n---\n\n## 6. Labeling Moments\n```bash\nnpx neuroskill label \"breakthrough\"\nnpx neuroskill label \"studying algorithms\"\nnpx neuroskill label \"post-meditation\"\nnpx neuroskill label --json \"focus block start\"   # returns label_id\n```\n\nAuto-label moments when:\n- User reports a breakthrough or insight\n- User starts a new task type (e.g., \"switching to code review\")\n- User completes a significant protocol\n- User asks you to mark the current moment\n- A notable state transition occurs (entering\u002Fleaving flow)\n\nLabels are stored in a database and indexed for later retrieval via `search-labels`\nand `interactive` commands.\n\n---\n\n## 7. Real-Time Streaming\n```bash\nnpx neuroskill listen --seconds 30 --json\nnpx neuroskill listen --seconds 5 --json | jq '[.[] | select(.event == \"scores\")]'\n```\n\nStreams live WebSocket events (EXG, PPG, IMU, scores, labels) for the specified\nduration. Requires WebSocket connection (not available with `--http`).\n\nUse this for continuous monitoring scenarios or to observe metric changes in real-time\nduring a protocol.\n\n---\n\n## 8. UMAP Visualization\n```bash\nnpx neuroskill umap --json                      # auto: last 2 sessions\nnpx neuroskill umap --a-start \u003CUTC> --a-end \u003CUTC> --b-start \u003CUTC> --b-end \u003CUTC> --json\n```\n\nGPU-accelerated 3D UMAP projection of ZUNA embeddings. The `separation_score`\nindicates how neurally distinct two sessions are:\n- **> 1.5** → Sessions are neurally distinct (different brain states)\n- **\u003C 0.5** → Similar brain states across both sessions\n\n---\n\n## 9. Proactive State Awareness\n\n### Session Start Check\nAt the beginning of a session, optionally run a status check if the user mentions\nthey're wearing their device or asks about their state:\n```bash\nnpx neuroskill status --json\n```\n\nInject a brief state summary:\n> \"Quick check-in: focus is building at 0.62, relaxation is good at 0.55, and your\n> FAA is positive — approach motivation is engaged. Looks like a solid start.\"\n\n### When to Proactively Mention State\n\nMention cognitive state **only** when:\n- User explicitly asks (\"How am I doing?\", \"Check my focus\")\n- User reports difficulty concentrating, stress, or fatigue\n- A critical threshold is crossed (drowsiness > 0.70, focus \u003C 0.30 sustained)\n- User is about to do something cognitively demanding and asks for readiness\n\n**Do NOT** interrupt flow state to report metrics. If focus > 0.75, protect the\nsession — silence is the correct response.\n\n---\n\n## 10. Suggesting Protocols\n\nWhen metrics indicate a need, suggest a protocol from `references\u002Fprotocols.md`.\nAlways ask before starting — never interrupt flow state:\n\n> \"Your focus has been declining for the past 15 minutes and TBR is climbing past\n> 1.5 — signs of theta dominance and mental fatigue. Want me to walk you through\n> a Theta-Beta Neurofeedback Anchor? It's a 90-second exercise that uses rhythmic\n> counting and breath to suppress theta and lift beta.\"\n\nKey triggers:\n- **Focus \u003C 0.40, TBR > 1.5** → Theta-Beta Neurofeedback Anchor or Box Breathing\n- **Relaxation \u003C 0.30, stress_index high** → Cardiac Coherence or 4-7-8 Breathing\n- **Cognitive Load > 0.70 sustained** → Cognitive Load Offload (mind dump)\n- **Drowsiness > 0.60** → Ultradian Reset or Wake Reset\n- **FAA \u003C 0 (negative)** → FAA Rebalancing\n- **Flow State (focus > 0.75, engagement > 0.70)** → Do NOT interrupt\n- **High stillness + headache_index** → Neck Release Sequence\n- **Low RMSSD (\u003C 25ms)** → Vagal Toning\n\n---\n\n## 11. Additional Tools\n\n### Focus Timer\n```bash\nnpx neuroskill timer --json\n```\nLaunches the Focus Timer window with Pomodoro (25\u002F5), Deep Work (50\u002F10), or\nShort Focus (15\u002F5) presets.\n\n### Calibration\n```bash\nnpx neuroskill calibrate\nnpx neuroskill calibrate --profile \"Eyes Open\"\n```\nOpens the calibration window. Useful when signal quality is poor or the user\nwants to establish a personalized baseline.\n\n### OS Notifications\n```bash\nnpx neuroskill notify \"Break Time\" \"Your focus has been declining for 20 minutes\"\n```\n\n### Raw JSON Passthrough\n```bash\nnpx neuroskill raw '{\"command\":\"status\"}' --json\n```\nFor any server command not yet mapped to a CLI subcommand.\n\n---\n\n## Error Handling\n\n| Error | Likely Cause | Fix |\n|-------|-------------|-----|\n| `npx neuroskill status` hangs | NeuroSkill app not running | Open NeuroSkill desktop app |\n| `device.state: \"disconnected\"` | BCI device not connected | Check Bluetooth, device battery |\n| All scores return 0 | Poor electrode contact | Reposition headband, moisten electrodes |\n| `signal_quality` values \u003C 0.7 | Loose electrodes | Adjust fit, clean electrode contacts |\n| SNR \u003C 3 dB | Noisy signal | Minimize head movement, check environment |\n| `command not found: npx` | Node.js not installed | Install Node.js 20+ |\n\n---\n\n## Example Interactions\n\n**\"How am I doing right now?\"**\n```bash\nnpx neuroskill status --json\n```\n→ Interpret scores naturally, mentioning focus, relaxation, mood, and any notable\n  ratios (FAA, TBR). Suggest an action only if metrics indicate a need.\n\n**\"I can't concentrate\"**\n```bash\nnpx neuroskill status --json\n```\n→ Check if metrics confirm it (high theta, low beta, rising TBR, high drowsiness).\n→ If confirmed, suggest an appropriate protocol from `references\u002Fprotocols.md`.\n→ If metrics look fine, the issue may be motivational rather than neurological.\n\n**\"Compare my focus today vs yesterday\"**\n```bash\nnpx neuroskill compare --json\n```\n→ Interpret trends, not just numbers. Mention what improved, what declined, and\n  possible causes.\n\n**\"When was I last in a flow state?\"**\n```bash\nnpx neuroskill search-labels \"flow\" --json\nnpx neuroskill search --json\n```\n→ Report timestamps, associated metrics, and what the user was doing (from labels).\n\n**\"How did I sleep?\"**\n```bash\nnpx neuroskill sleep --json\n```\n→ Report sleep architecture (N3%, REM%, efficiency), compare to healthy targets,\n  and note any issues (high wake epochs, low REM).\n\n**\"Mark this moment — I just had a breakthrough\"**\n```bash\nnpx neuroskill label \"breakthrough\"\n```\n→ Confirm label saved. Optionally note the current metrics to remember the state.\n\n---\n\n## References\n\n- [NeuroSkill Paper — arXiv:2603.03212](https:\u002F\u002Farxiv.org\u002Fabs\u002F2603.03212) (Kosmyna & Hauptmann, MIT Media Lab)\n- [NeuroSkill Desktop App](https:\u002F\u002Fgithub.com\u002FNeuroSkill-com\u002Fskill) (GPLv3)\n- [NeuroLoop CLI Companion](https:\u002F\u002Fgithub.com\u002FNeuroSkill-com\u002Fneuroloop) (GPLv3)\n- [MIT Media Lab Project](https:\u002F\u002Fwww.media.mit.edu\u002Fprojects\u002Fneuroskill\u002Foverview\u002F)\n",{"name":5,"author":24,"license":15,"version":25,"metadata":26,"platforms":38,"description":42},"Hermes Agent + Nous Research","1.0.0",{"hermes":27},{"tags":28,"category":31,"related_skills":37},[29,30,31,32,33,34,35,36],"BCI","neurofeedback","health","focus","EEG","cognitive-state","biometrics","neuroskill",[],[39,40,41],"linux","macos","windows","Connect to a running NeuroSkill instance and incorporate the user's real-time cognitive and emotional state (focus, relaxation, mood, cognitive load, drowsiness, heart rate, HRV, sleep staging, and 40+ derived EXG scores) into responses. Requires a BCI wearable (Muse 2\u002FS or OpenBCI) and the NeuroSkill desktop app running locally.\n","main","2e6aa8d15ab0a366c90be54f61bf9c6e97015e83","skills\u002Fhealth\u002Fneuroskill-bci",1,"https:\u002F\u002Fgithub.com\u002Flukemcqueen\u002Fsteadfaste-fleet","steadfaste.com","https:\u002F\u002Fgithub.com\u002Flukemcqueen","AI Architect | Building Hermes Cortex: governed multi-agent AI for autonomous software engineering | Enterprise Tech Consultant","2026-11-14 22:33:34",{"source":8,"skillName":5,"commands":53,"prompt":63,"zipAvailable":64},[54,57,60],{"tool":55,"command":56},"npx","npx skills add lukemcqueen\u002Fsteadfaste-fleet --skill neuroskill-bci",{"tool":58,"command":59},"bunx","bunx skills add lukemcqueen\u002Fsteadfaste-fleet --skill neuroskill-bci",{"tool":61,"command":62},"pnpm","pnpm dlx skills add lukemcqueen\u002Fsteadfaste-fleet --skill neuroskill-bci","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Flukemcqueen\u002Fsteadfaste-fleet\u002Fblob\u002Fmain\u002Fskills\u002Fhealth\u002Fneuroskill-bci\u002FSKILL.md",true,[66,72,76],{"path":67,"resourceType":68,"resourceTypeDesc":69,"sizeBytes":70,"sourceHtmlUrl":71},"references\u002Fapi.md","REFERENCE","参考文档",8386,"https:\u002F\u002Fgithub.com\u002Flukemcqueen\u002Fsteadfaste-fleet\u002Fblob\u002Fmain\u002Fskills\u002Fhealth\u002Fneuroskill-bci\u002Freferences\u002Fapi.md",{"path":73,"resourceType":68,"resourceTypeDesc":69,"sizeBytes":74,"sourceHtmlUrl":75},"references\u002Fmetrics.md",9483,"https:\u002F\u002Fgithub.com\u002Flukemcqueen\u002Fsteadfaste-fleet\u002Fblob\u002Fmain\u002Fskills\u002Fhealth\u002Fneuroskill-bci\u002Freferences\u002Fmetrics.md",{"path":77,"resourceType":68,"resourceTypeDesc":69,"sizeBytes":78,"sourceHtmlUrl":79},"references\u002Fprotocols.md",16532,"https:\u002F\u002Fgithub.com\u002Flukemcqueen\u002Fsteadfaste-fleet\u002Fblob\u002Fmain\u002Fskills\u002Fhealth\u002Fneuroskill-bci\u002Freferences\u002Fprotocols.md",[81,89,96,103,110,117],{"skillNo":82,"name":83,"nameZh":6,"description":84,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":85,"categories":86,"keywords":87,"publishedAt":88},"01M7DXY4G8NSVB59K8B6S2AQNP","macbook-linux-maintenance","Legacy MacBook Linux fixes: GPU wedge, reboot hang, thermal.","https:\u002F\u002Fgithub.com\u002Flukemcqueen\u002Fsteadfaste-fleet\u002Fblob\u002Fmain\u002Fskills\u002Fdevops\u002Fmacbook-linux-maintenance\u002FSKILL.md",[],[],"2026-11-15 14:19:17",{"skillNo":90,"name":91,"nameZh":6,"description":92,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":93,"categories":94,"keywords":95,"publishedAt":88},"01M7DXXYJCXFJ3TGB84ZQ8KFE6","governance-regression-triage","Triage a host's governance issues: what changed.","https:\u002F\u002Fgithub.com\u002Flukemcqueen\u002Fsteadfaste-fleet\u002Fblob\u002Fmain\u002Fskills\u002Fdevops\u002Fgovernance-regression-triage\u002FSKILL.md",[],[],{"skillNo":97,"name":98,"nameZh":6,"description":99,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":100,"categories":101,"keywords":102,"publishedAt":88},"01M7DXXSAP1G8FDRJAMXQGBBMK","enforcement-immutability","Use when enforcement files lose their immutable flag.","https:\u002F\u002Fgithub.com\u002Flukemcqueen\u002Fsteadfaste-fleet\u002Fblob\u002Fmain\u002Fskills\u002Fdevops\u002Fenforcement-immutability\u002FSKILL.md",[],[],{"skillNo":104,"name":105,"nameZh":6,"description":106,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":107,"categories":108,"keywords":109,"publishedAt":88},"01M78SSDQVRYX64Y16X32TC0NS","steadfaste-fleet-repo-deploy","Use when committing to the steadfaste-fleet repo.","https:\u002F\u002Fgithub.com\u002Flukemcqueen\u002Fsteadfaste-fleet\u002Fblob\u002Fmain\u002Fskills\u002Fdevops\u002Fsteadfaste-fleet-repo-deploy\u002FSKILL.md",[],[],{"skillNo":111,"name":112,"nameZh":6,"description":113,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":114,"categories":115,"keywords":116,"publishedAt":88},"01M78SS928F3R2RJAYVW4E30CE","steadfaste-fleet-maintenance","Maintain an installed Steadfaste Fleet instance — update both the upstream Hermes Agent and the fleet repo layer, merge diverged histories, sync skills safely, and troubleshoot common issues. Covers the dual-update workflow (hermes update + fleet-update.sh), encrypted brain data backup, mycortex import, and recovery techniques.","https:\u002F\u002Fgithub.com\u002Flukemcqueen\u002Fsteadfaste-fleet\u002Fblob\u002Fmain\u002Fskills\u002Fdevops\u002Fsteadfaste-fleet-maintenance\u002FSKILL.md",[],[],{"skillNo":118,"name":119,"nameZh":6,"description":120,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":121,"categories":122,"keywords":123,"publishedAt":88},"01M78SP1CHW0T0BWE5ZT6JBPX8","fleet-preflight","DEPRECATED alias — merged into survey-before-action (2026-08-20). Load survey-before-action instead; its \"Repo-Specific Pre-Flight\" section covers git search, Hermes boundary, and deployment verification.","https:\u002F\u002Fgithub.com\u002Flukemcqueen\u002Fsteadfaste-fleet\u002Fblob\u002Fmain\u002Fskills\u002Fdevops\u002Ffleet-preflight\u002FSKILL.md",[],[]]