NeuroSkill CLI Reference: Hermes Integration for Real-Time BCI Metrics

This document describes how to connect Hermes to a NeuroSkill instance for reading real-time brain and body metrics from a BCI wearable. The integration enables cognitively-aware responses, intervention suggestions, and mental performance tracking.

Overview

NeuroSkill is an open-source research tool that provides live metrics from EEG, PPG, and IMU sensors via a BCI headband. The CLI commands documented here allow you to query current cognitive state, analyze sessions, search historical data, stream real-time events, and trigger actions like calibration or focus timers.

Important: NeuroSkill is NOT a medical device and is NOT cleared by FDA, CE, or any regulatory body. Never use its metrics for clinical diagnosis or treatment.

Prerequisites

Before using any commands, ensure the following:

• Node.js 20+ is installed. Verify with node --version (must show 20.x or higher).
• The NeuroSkill desktop app is running with a connected BCI device (Muse 2, Muse S, or OpenBCI).
• The BCI device is powered on and connected via Bluetooth.
• Run npx neuroskill status to get a full system snapshot and confirm no errors.

node --version                    # Must be 20+
npx neuroskill status             # Full system snapshot
npx neuroskill status --json      # Machine-parseable JSON

If you see command not found: npx, install Node.js 20+ first.

Common Parameters

All commands support the following optional parameters:

• --json — Raw JSON output, pipe-safe. Always use this for reliable parsing.
• --full — Human summary plus colorized JSON.
• --port <port> — Override server port (default is auto-discovered, usually 8375).
• --ws — Force WebSocket transport.
• --http — Force HTTP transport.

Additional parameters specific to certain commands are documented in their respective sections.

Checking Current State (Live Metrics)

Use this when the user asks about their current cognitive state, reports difficulty concentrating, or when a critical threshold is crossed (e.g., drowsiness > 0.70, focus < 0.30 sustained).

npx neuroskill status --json

Parse the JSON response, focusing on the scores object. Never report raw numbers alone — always translate them into natural language with meaning.

The scores object contains these metrics:

{
  "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
    }
  }
}

Use these key interpretation thresholds:

• Focus > 0.70 = flow state
• Focus < 0.40 = suggest break
• Drowsiness > 0.60 = fatigue warning
• Relaxation < 0.30 = stress intervention
• Cognitive Load > 0.70 sustained = mind dump/break
• TBR > 1.5 = theta-dominant
• FAA < 0 = withdrawal/negative affect
• SNR < 3 dB = unreliable signal

Proactive state awareness: If the user mentions wearing the device or asks about their state, run npx neuroskill status --json and inject a brief state summary (focus, relaxation, FAA, etc.). Only mention state when the user asks, reports difficulty, a critical threshold is crossed, or the user asks for readiness. Do NOT interrupt flow state (focus > 0.75) — silence is the correct response.

Session Management

Analyzing a Single Session

Use this when the user wants to understand how a specific session evolved. The session [N] command lets you specify a session index, where N starts at 0 for the most recent session.

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}'

The session index N starts at 0 for the most recent session. Examine the returned metrics and first-half vs. second-half trends (values "up", "down", or "flat"). Describe how the session evolved, for example: "focus started at X and climbed to Y."

Listing All Sessions

Use this when the user wants to compare mental states across sessions or days.

npx neuroskill sessions --json
npx neuroskill sessions --trends      # show per-session metric trends

The --trends flag adds per-session metric trends to the output.

Comparing Two Sessions

Use this when the user wants to compare mental states between two time periods.

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 (absolute change, percentage change, direction), insights.improved[] and insights.declined[] arrays, sleep staging, and a UMAP job ID. Interpret with context — mention trends, not just deltas.

# Sort metrics by improvement percentage
npx neuroskill compare --json | jq '.insights.deltas | to_entries | sort_by(.value.pct) | reverse'

Search Capabilities

Neural Similarity Search

Use this to find historically similar brain states based on neural embeddings.

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

The --k parameter sets the number of nearest neighbors. Use --start and --end to restrict the search to a time range. Returns distance statistics, temporal distribution, and top matching days.

Semantic Label Search

Use this to search past labels by text similarity. The search-labels "query" command accepts a text query to find semantically similar labels.

npx neuroskill search-labels "deep focus" --k 10 --json
npx neuroskill search-labels "stress" --json | jq '[.results[].EXG_metrics.tbr]'

Returns matching labels with associated EXG metrics at the time of labeling. The --k parameter controls how many results to return.

Cross-Modal Graph Search

Use this for a 4-layer graph search that connects text, EXG, and labels. The interactive "query" command performs an interactive graph search.

npx neuroskill interactive "deep focus" --json
npx neuroskill interactive "deep focus" --dot | dot -Tsvg > graph.svg

The --dot flag outputs Graphviz DOT format, which can be piped to dot -Tsvg to generate an SVG graph. Tune the search with --k-text, --k-EXG, and --reach parameters.

Sleep Data

Use this when the user asks about sleep quality or recovery. The sleep [N] command retrieves sleep data, where N is an optional session index.

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 staging (0=Wake, 1=N1, 2=N2, 3=N3, 4=REM) and analysis including efficiency percentage, onset latency in minutes, REM latency in minutes, and bout counts.

Healthy targets: N3 15-25%, REM 20-25%, efficiency >85%, onset <20 minutes.

npx neuroskill sleep --json | jq '.summary | {n3: .n3_epochs, rem: .rem_epochs}'
npx neuroskill sleep --json | jq '.analysis.efficiency_pct'

Real-Time Operations

Real-Time Streaming

Use this to stream live WebSocket events for a specified duration. The --seconds N parameter controls how many seconds to stream.

npx neuroskill listen --seconds 30 --json
npx neuroskill listen --seconds 5 --json | jq '[.[] | select(.event == "scores")]'

Streams EXG, PPG, IMU, scores, and label events. Requires a WebSocket connection — not available with --http. The default duration is 5 seconds.

Labeling a Moment

Use this to create timestamped annotations at the current moment. The label "text" command creates a label with the given text. Auto-label when the user reports a breakthrough or insight, starts a new task type, completes a protocol, asks to mark a moment, or a notable state transition occurs.

npx neuroskill label "breakthrough"
npx neuroskill label "studying algorithms"
npx neuroskill label "post-meditation"
npx neuroskill label --json "focus block start"   # returns label_id

The --json flag returns the label_id for programmatic use.

Visualization and Tools

Generating UMAP Visualization

Use this to create a 3D UMAP projection of session embeddings.

npx neuroskill umap --json                      # auto: last 2 sessions
npx neuroskill umap --a-start <UTC> --a-end <UTC> --b-start <UTC> --b-end <UTC> --json

Returns a separation_score: >1.5 means neurally distinct states, <0.5 means similar brain states.

Using the Focus Timer

Use this to launch a focus timer window with presets.

npx neuroskill timer --json

Launches the Focus Timer with Pomodoro (25/5), Deep Work (50/10), or Short Focus (15/5) presets.

Calibrating

Use this when signal quality is poor or the user wants a personalized baseline.

npx neuroskill calibrate
npx neuroskill calibrate --profile "Eyes Open"

Opens the calibration window. The --profile parameter specifies a profile name.

System Commands

Sending OS Notifications

Use this to send notifications via the NeuroSkill app. The notify "title" "body" command sends a notification with the given title and body text.

npx neuroskill notify "Break Time" "Your focus has been declining for 20 minutes"

Sends a notification with the given title and body.

Sending Raw JSON Passthrough

Use this for any server command not mapped to a CLI subcommand. The raw '{json}' command sends arbitrary JSON to the server.

npx neuroskill raw '{"command":"status"}' --json

Sends arbitrary JSON to the server.

Viewing Command History

Use this to review previously executed commands. The history command displays a list of past commands.

npx neuroskill history

Shows a list of previously run NeuroSkill commands with timestamps.

Protocol Suggestions

When metrics indicate a need, suggest a protocol from references/protocols.md. Always ask before starting, and never interrupt flow state.

Key triggers and suggested protocols:

• Focus < 0.40 or TBR > 1.5 → Theta-Beta Neurofeedback Anchor or Box Breathing
• Relaxation < 0.30 → Cardiac Coherence or 4-7-8 Breathing
• Cognitive Load > 0.70 sustained → Cognitive Load Offload
• Drowsiness > 0.60 → Ultradian Reset or Wake Reset
• FAA < 0 → 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

Failure Modes and Troubleshooting

Symptom	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 Workflows

User asks "How am I doing right now?" → Run npx neuroskill status --json, interpret scores naturally (focus, relaxation, mood, FAA, TBR), suggest action only if metrics indicate need.

User says "I can't concentrate" → Run npx neuroskill status --json, check if metrics confirm (high theta, low beta, rising TBR, high drowsiness). If confirmed, suggest a protocol from references/protocols.md. If metrics are fine, the issue may be motivational.

User asks "Compare my focus today vs yesterday" → Run npx neuroskill compare --json, interpret trends not just numbers, mention what improved/declined and possible causes.

User asks "When was I last in a flow state?" → Run npx neuroskill search-labels "flow" --json and npx neuroskill search --json, report timestamps, associated metrics, and what the user was doing (from labels).

User asks "How did I sleep?" → Run npx neuroskill sleep --json, report sleep architecture (N3%, REM%, efficiency), compare to healthy targets (N3 15-25%, REM 20-25%, efficiency >85%), note issues (high wake epochs, low REM).

User says "Mark this moment — I just had a breakthrough" → Run npx neuroskill label "breakthrough", confirm label saved, optionally note current metrics to remember the state.

Additional Reference Files

For detailed metric definitions, see references/metrics.md. For protocol descriptions, see references/protocols.md. For API documentation, see references/api.md.