Recipes

import asyncio, json import websockets async def stream(): async with websockets.connect("ws://localhost:8375") as ws: async for raw in ws:
            msg  = json.loads(raw) if msg["event"] != "eeg-bands": continue p     = msg["payload"]
            focus = p["focus_score"]
            faa   = p["faa"]
            af7_a = p["channels"][1]["rel_alpha"] # AF7 print(f"focus={focus:.0f}  FAA={faa:+.3f}  AF7α={af7_a:.3f}")

asyncio.run(stream())

import WebSocket from 'ws'; const ws = new WebSocket('ws://localhost:8375');

ws.on('open', () => console.log('connected to NeuroSkill™'));

ws.on('message', (raw) => { const { event, payload: p } = JSON.parse(raw); if (event !== 'eeg-bands') return; const { focus_score, faa, channels } = p;
  console.log(`focus=${focus_score.toFixed(0)}  FAA=${faa.toFixed(3)}  AF7α=${channels[1].rel_alpha.toFixed(3)}`);
});

ws.on('error', (err) => console.error('NeuroSkill™ not running?', err.message));

import asyncio, json import websockets async def label(text: str): async with websockets.connect("ws://localhost:8375") as ws: await ws.send(json.dumps({ "command": "label", "params":  {"label": text},
        }))
        resp = json.loads(await ws.recv())
        ts   = resp["payload"]["timestamp"] print(f"labeled '${text}' at t=${ts}") # Example: mark stimulus onset in an experiment asyncio.run(label("stimulus onset — trial 1"))

# Label a single moment skill label "meditation start" # Label with auto-generated timestamp in the message skill label "task begin — $(date -u +%FT%TZ)" # Label multiple events in a loop for i in 1 2 3 4 5; do skill label "trial $i start" sleep 30 done

import asyncio, json import websockets async def search(query: str, k: int = 5): async with websockets.connect("ws://localhost:8375") as ws: await ws.send(json.dumps({ "command": "search", "params":  {"query": query, "k": k},
        }))
        resp    = json.loads(await ws.recv())
        results = resp["payload"]["results"] print(f"Top ${k} matches for '${query}':") for r in results: print(f"  ${r['rank']}  ${r['timestamp']}  similarity=${r['similarity']:.4f}")

asyncio.run(search("calm, focused, low anxiety", k=5))

# Print top-3 matches with timestamp and similarity npx neuroskill search "deep focus" --k 3 --json \
  | jq '.results[] | {rank, ts: .timestamp, sim: .similarity}' # Save full result set to a file npx neuroskill search "pre-sleep drowsiness" --k 20 --json > search_results.json

# Full status as pretty JSON skill status --json | jq . # Just battery + quality summary skill status --json | jq '{
  battery:  .battery_percent,
  quality:  [.channels[] | {ch: .channel, q: .quality}],
  focus:    .focus_score,
  relax:    .relaxation_score
}' # Exit non-zero if any channel is not "Good" skill status --json \
  | jq -e 'all(.channels[].quality == "Good")' \
  && echo "all channels good" \
  || echo "signal quality issue"

# Print sleep summary to terminal skill sleep --session latest # Export as JSON skill sleep --session latest --json | jq '{
  efficiency:   .efficiency,
  total_min:    .total_minutes,
  rem_pct:      .rem_percent,
  n3_pct:       .n3_percent,
  onset_min:    .sleep_onset_minutes
}' # Save report with date-stamped filename skill sleep --session latest --json \
  > "sleep_$(date +%Y-%m-%d).json"

import asyncio, json, subprocess import websockets

THRESHOLD  = 35 # focus score 0–100 EPOCHS_LOW = 3 # consecutive epochs before alerting async def monitor():
    low_streak = 0 async with websockets.connect("ws://localhost:8375") as ws: async for raw in ws:
            msg = json.loads(raw) if msg["event"] != "eeg-bands": continue focus = msg["payload"]["focus_score"] if focus < THRESHOLD:
                low_streak += 1 else:
                low_streak = 0 if low_streak == EPOCHS_LOW:
                subprocess.run([ "osascript", "-e", f'display notification "Focus dropped to {focus:.0f}" with title "Skill"',
                ])

asyncio.run(monitor())

#!/usr/bin/env bash set -euo pipefail
DURATION=3600 # seconds # Wait for all channels to be Good echo "Waiting for signal quality…" until skill status --json \
  | jq -e 'all(.channels[].quality == "Good")' >/dev/null 2>&1; do sleep 5 done echo "Recording for $DURATION s…" skill label "session start" sleep "$DURATION" skill label "session end" # Export report OUT="report_$(date +%Y-%m-%dT%H-%M).json" skill sleep --session latest --json > "$OUT" echo "Report saved to $OUT"

# Colourised human-readable output npx neuroskill status # Key metrics as a compact JSON object npx neuroskill status --json | jq '{
  battery: .device.battery,
  focus:   .scores.focus,
  relax:   .scores.relaxation,
  hr:      .scores.hr,
  streak:  .history.current_streak_days
}' # Watch focus score live every 10 seconds (macOS/Linux) watch -n 10 'npx neuroskill status --json | jq ".scores.focus"'

# List all sessions (colourised table) npx neuroskill sessions # Extract last session's start + end as shell variables SESSIONS=$(npx neuroskill sessions --json | jq '.sessions')
START=$(echo "$SESSIONS" | jq -r '.[0].start_utc')
END=$(echo  "$SESSIONS" | jq -r '.[0].end_utc')
echo "Last session: $START → $END" # Total recorded hours across all sessions npx neuroskill sessions --json \
  | jq '[.sessions[] | .end_utc - .start_utc] | add / 3600'

# Auto-select last session, k=5 neighbours (default) npx neuroskill search # More neighbours, explicit time window npx neuroskill search --k 20 --start 1740412800 --end 1740415500 # Extract neighbour timestamps as JSON array npx neuroskill search --json \
  | jq '[.result.results[].neighbors[].timestamp_unix]' # Show which days had the most matching brain states npx neuroskill search --k 50 --json \
  | jq '.result.analysis.top_days'

# Auto: compare last two sessions npx neuroskill compare # Explicit session ranges (copy from the "rerun:" line) npx neuroskill compare \
  --a-start 1740380100 --a-end 1740382665 \
  --b-start 1740412800 --b-end 1740415510 # What improved between the two sessions? npx neuroskill compare --json | jq '.insights.improved' # Full focus delta (value, percent, direction) npx neuroskill compare --json | jq '.insights.deltas.focus' # Side-by-side focus + HR for a quick summary npx neuroskill compare --json | jq '{
  focus_a: .a.focus, focus_b: .b.focus,
  hr_a:    .a.hr,    hr_b:    .b.hr
}'

# Run UMAP on last two sessions (shows progress bar) npx neuroskill umap # Specific session ranges npx neuroskill umap \
  --a-start 1740380100 --a-end 1740382665 \
  --b-start 1740412800 --b-end 1740415510 # Save all 3D points to a file for plotting in Python/R npx neuroskill umap --json | jq '.result.points' > umap_points.json # How well separated were the two sessions? npx neuroskill umap --json | jq '.result.analysis.separation_score'

# 5-second listen (default) — shows event-type counts npx neuroskill listen # 30-second capture → save raw events to file npx neuroskill listen --seconds 30 --json > events.json # Count events by type from a capture file jq 'group_by(.event) | map({event: .[0].event, count: length})' events.json # Live focus score from the stream (one per epoch) npx neuroskill listen --seconds 60 --json \
  | jq '.[] | select(.event=="eeg-bands") | .payload.focus_score'

# Status via raw command npx neuroskill raw '{"command":"status"}' # Search with exact parameters npx neuroskill raw \
  '{"command":"search","start_utc":1740412800,"end_utc":1740415500,"k":3}' \
  --json # Backdate a label (label_start_utc overrides current time) npx neuroskill raw \
  '{"command":"label","text":"eyes closed","label_start_utc":1740412900}' \
  --json # Export a date range as CSV npx neuroskill raw \
  '{"command":"export","start_utc":1740380100,"end_utc":1740415510,"format":"csv"}' \
  --json

#!/usr/bin/env bash set -euo pipefail # ── 1. Fetch session list ────────────────────────────── SESSIONS=$(npx neuroskill sessions --json | jq '.sessions')
N=$(echo "$SESSIONS" | jq 'length')

[ "$N" -lt 2 ] && { echo "Need ≥ 2 sessions"; exit 1; } # ── 2. Extract last two session ranges ──────────────── B_START=$(echo "$SESSIONS" | jq -r '.[0].start_utc')
B_END=$(echo   "$SESSIONS" | jq -r '.[0].end_utc')
A_START=$(echo "$SESSIONS" | jq -r '.[1].start_utc')
A_END=$(echo   "$SESSIONS" | jq -r '.[1].end_utc') # ── 3. Compare ──────────────────────────────────────── COMPARE=$(npx neuroskill compare \
  --a-start "$A_START" --a-end "$A_END" \
  --b-start "$B_START" --b-end "$B_END" \
  --json)

IMPROVED=$(echo "$COMPARE" | jq -r '.insights.improved | join(", ")')
DECLINED=$(echo "$COMPARE" | jq -r '.insights.declined | join(", ")')
FOCUS_D=$(echo  "$COMPARE" | jq   '.insights.deltas.focus.pct // 0 | round') # ── 4. Sleep summary ────────────────────────────────── SLEEP=$(npx neuroskill sleep --start "$A_START" --end "$B_END" --json)
EFF=$(echo "$SLEEP" | jq '.analysis.efficiency_pct') # ── 5. Print report ─────────────────────────────────── echo "=== Daily Report $(date +%F) ==="
echo "Focus change:  $FOCUS_D%"
echo "Improved:      $IMPROVED"
echo "Declined:      $DECLINED"
echo "Sleep efficiency: $EFF%"