| name | neuroskill-bci |
| description | 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/S or OpenBCI) and the NeuroSkill desktop app running locally.
|
| version | 1.0.0 |
| author | Gauss Agent + Nous Research |
| license | MIT |
| metadata | {"gauss":{"tags":["BCI","neurofeedback","health","focus","EEG","cognitive-state","biometrics","neuroskill"],"category":"health","related_skills":[]}} |
NeuroSkill BCI Integration
Connect Gauss 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
npx neuroskill status
npx neuroskill status --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,
"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,
"faa": 0.042,
"tar": 0.56,
"bar": 0.53,
"tbr": 1.06,
"apf": 10.1,
"coherence": 0.614,
"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
npx neuroskill session 1 --json
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
3. Historical Search
Neural Similarity Search
npx neuroskill search --json
npx neuroskill search --k 10 --json
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
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."
npx neuroskill compare --json | jq '.insights.deltas | to_entries | sort_by(.value.pct) | reverse'
5. Sleep Data
npx neuroskill sleep --json
npx neuroskill sleep 0 --json
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"
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
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
