neuroskill-com/neuroskill-status

NeuroSkill status Command

Full snapshot: device state, session, signal quality, scores, bands, embeddings, labels (with top texts all-time/24h/7d), app usage (top apps all-time/24h/7d), screenshots (counts + top OCR apps), hooks (with latest trigger), sleep summary, and recording history.

LLM Tool Calls

When calling this command via the LLM skill tool:

{"command": "status"}

The status response includes top apps and labels, so use it to answer questions like "what apps did I use today?" (check apps.top_24h) or "what labels did I create recently?" (check labels.recent and labels.top_24h).

Supported Devices

| Device | Channels | Sample Rate | Connection | |---|---|---|---| | Muse (S, 2, 2016) | 4 (TP9, AF7, AF8, TP10) | 256 Hz | BLE | | OpenBCI Ganglion | 4 | 200 Hz | BLE | | Neurable MW75 Neuro | 12 | 500 Hz | BLE + RFCOMM | | Hermes V1 | 8 (Fp1, Fp2, AF3, AF4, F3, F4, FC1, FC2) | 250 Hz | BLE GATT |

The DSP pipeline dynamically scales to the active channel count (4, 8, or 12).

npx neuroskill status
npx neuroskill status --json
npx neuroskill status --json | jq '.scores.focus'
npx neuroskill status --json | jq '.scores.bands'
npx neuroskill status --json | jq '.device.battery'
npx neuroskill status --json | jq '.signal_quality'
npx neuroskill status --json | jq '.sleep'
npx neuroskill status --json | jq '.history.current_streak_days'
npx neuroskill status --json | jq '.hooks'
npx neuroskill status --json | jq '.hooks.latest_trigger'

# Poll every N seconds (keeps connection open, re-prints a fresh snapshot each time):
npx neuroskill status --poll 5              # refresh every 5 s
npx neuroskill status --poll 10 --json     # JSON snapshot every 10 s

HTTP:

curl -s -X POST http://127.0.0.1:8375/ \
  -H "Content-Type: application/json" \
  -d '{"command":"status"}'

Full JSON Response

{
  "command": "status",
  "ok": true,
  "device": {
    "state": "connected",          // "connected" | "connecting" | "disconnected"
    "name": "Muse-A1B2",          // or "MW75-Neuro-XXXX", "Hermes-XXXX", "Ganglion-XXXX"
    "battery": 73,                 // percent
    "firmware": "1.3.4",
    "eeg_samples": 195840,         // cumulative samples this run
    "ppg_samples": 30600,          // Muse only (PPG sensor)
    "imu_samples": 122400,
    "eeg_channels": 4              // 4 (Muse/Ganglion), 8 (Hermes), or 12 (MW75)
  },
  "session": {
    "start_utc": 1740412800,       // Unix seconds (UTC)
    "duration_secs": 1847,
    "n_epochs": 369                // 5-second embedding epochs computed so far
  },
  "signal_quality": {
    // Keys vary by device — Muse: tp9/af7/af8/tp10; Hermes: fp1/fp2/af3/af4/f3/f4/fc1/fc2
    // MW75: ft7/t7/tp7/cp5/p7/c5/ft8/t8/tp8/cp6/p8/c6
    "tp9": 0.95,                   // 0–1; >=0.9 = good, >=0.7 = acceptable
    "af7": 0.88,
    "af8": 0.91,
    "tp10": 0.97
  },
  "scores": {
    // Core scores (0–1 unless noted):
    "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,                    // bpm (from PPG)
    "snr": 14.3,                   // signal-to-noise ratio in dB
    "stillness": 0.88,             // 0–1; 1 = perfectly still
    // Band powers (relative, sum ~ 1):
    "bands": {
      "rel_delta": 0.28,
      "rel_theta": 0.18,
      "rel_alpha": 0.32,
      "rel_beta":  0.17,
      "rel_gamma": 0.05
    },
    // EEG ratios & spectral indices:
    "faa": 0.042,                  // Frontal Alpha Asymmetry (positive = approach)
    "tar": 0.56,                   // Theta/Alpha Ratio
    "bar": 0.53,                   // Beta/Alpha Ratio
    "tbr": 1.06,                   // Theta/Beta Ratio
    "apf": 10.1,                   // Alpha Peak Frequency (Hz)
    "coherence": 0.614,
    "mu_suppression": 0.031
  },
  "embeddings": {
    "today": 342,
    "total": 14820,
    "recording_days": 31
  },
  "labels": {
    "total": 58,
    "embedded": 55,
    "recent": [
      { "id": 42, "text": "meditation start", "created_at": 1740413100 }
    ],
    "top_all_time": [{ "text": "meditation start", "count": 12, "last_used": 1740413100 }],
    "top_24h":      [{ "text": "focus block", "count": 3, "last_used": 1740413050 }],
    "top_7d":       [{ "text": "meditation start", "count": 8, "last_used": 1740413100 }]
  },
  "apps": {
    "top_all_time": [{ "app_name": "VS Code", "switches": 142, "last_seen": 1740413050 }],
    "top_24h":      [{ "app_name": "Firefox", "switches": 23, "last_seen": 1740413000 }],
    "top_7d":       [{ "app_name": "VS Code", "switches": 87, "last_seen": 1740413050 }]
  },
  "screenshots": {
    "total": 2400,
    "with_embedding": 2100,
    "with_ocr": 2350,
    "with_ocr_embedding": 1800,
    "top_apps_all_time": [{ "app_name": "VS Code", "count": 800, "last_seen": 1740413050 }],
    "top_apps_24h":      [{ "app_name": "Firefox", "count": 45, "last_seen": 1740413000 }]
  },
  "sleep": {
    // Last 48 h sleep staging summary:
    "total_epochs": 1054,
    "wake_epochs": 134,
    "n1_epochs": 89,
    "n2_epochs": 421,
    "n3_epochs": 298,
    "rem_epochs": 112,
    "epoch_secs": 5
  },
  "hooks": {
    "total": 3,                    // total configured hooks
    "enabled": 2,                  // how many are enabled
    "latest_trigger": {            // most recent trigger across all hooks (null if never)
      "hook": "Deep Work Guard",   // hook name that fired
      "triggered_at_utc": 1740413100,
      "distance": 0.0892,          // cosine distance to matched reference
      "label_id": 7,
      "label_text": "focused reading session"
    }
  },
  "history": {
    "total_sessions": 63,
    "recording_days": 31,
    "current_streak_days": 7,
    "total_recording_hours": 94.2,
    "longest_session_min": 187,
    "avg_session_min": 89
  }
}

Hidden Fields (visible only with --full or --json)

| Hidden field | Type | Contents | |---|---|---| | scores.faa, scores.tar, scores.bar ... | numbers | EEG ratios and spectral indices not surfaced in the default summary | | calibration.actions[] | array | Full ordered list of calibration step objects | | labels.recent[] | array | Full label objects; summary only prints text + timestamp | | labels.top_all_time, top_24h, top_7d | array | Most frequent label texts with counts and last-used timestamps | | apps.top_all_time, top_24h, top_7d | array | Most-used apps by window switches with counts and last-seen timestamps | | screenshots.top_apps_all_time, top_apps_24h | array | Most-captured apps in screenshots with counts | | hooks.latest_trigger | object | Most recent hook trigger: hook name, timestamp, distance, label_id, label_text | | history.today_vs_avg | object | Per-metric today-vs-7-day-avg comparison table |

npx neuroskill status --json | jq '.history.today_vs_avg'
npx neuroskill status --json | jq '.calibration.actions'
npx neuroskill status --json | jq '.labels.recent'
npx neuroskill status --json | jq '.labels.top_24h'
npx neuroskill status --json | jq '.apps.top_24h'
npx neuroskill status --json | jq '.apps.top_7d'
npx neuroskill status --json | jq '.screenshots'
npx neuroskill status --json | jq '.hooks.latest_trigger'