LLMs that adapt in real time to your brain state. Your EEG is sampled 250 times a second, distilled into a live "focused / stressed / drowsy / flow" signal, and injected straight into the agent's prompt — so the model can shorten its reply when you fade, slow down when you're overloaded, or pause when you clench your jaw.
No hardware? Still works. Synthetic-board mode boots in ~5 seconds —
docker compose up --buildand you have a live dashboard athttp://localhost:7680/dashboard.
Runs on any of the 200+ EEG boards supported by BrainFlow (Galea, OpenBCI Cyton/Ganglion, Muse, Neurosity Crown, Emotiv, FreeEEG32, ...).
- Real-time EEG signal acquisition via BrainFlow SDK (supports 200+ boards, see docs/hardware.md)
- Synthetic board mode for development without hardware
- Frequency-domain feature extraction (Welch's method band powers)
- Heuristic and ML-based brain state classification (focused, relaxed, stressed, drowsy, meditative, active)
- Pause detection via jaw clench, drowsiness, and headset removal signals
- FastAPI HTTP server + optional WebSocket streaming
- Real-time web dashboard at
/dashboard(zero-dependency HTML) - Webhook notifications for state change events
- Session recording and replay
- CSV and EDF+ export for research-grade analysis
- Docker container for easy deployment
- OpenClaw plugin with
before_prompt_buildcontext injection - BCI SKILL.md for LLM brain state interpretation
A 3-component system that integrates with OpenClaw natively:
- Signal Processor + State Server (Python) -- BrainFlow data acquisition, DSP (Welch's method band powers), heuristic brain state classification, FastAPI HTTP server
- OpenClaw BCI Plugin (TypeScript) --
before_prompt_buildhook that injects brain state into LLM context - BCI SKILL.md -- Teaches the agent how to interpret and adapt to brain states
See docs/architecture.md for full details.
- Python 3.10+
- Node.js 20.19+
- pip and npm
docker compose up --build
# Signal processor now running on http://localhost:7680
# Open http://localhost:7680/dashboard to see the live brain state# 1. Start the signal processor (synthetic mode, no hardware needed)
cd signal-processor
pip install -e .
python -m src --synthetic
# 2. Install the OpenClaw plugin
cd openclaw-plugin
npm install
# Add to OpenClaw's plugin config
# 3. Copy skill/SKILL.md to your OpenClaw skills directory
# 4. Open the dashboard or run the demo
open http://localhost:7680/dashboard
./scripts/demo.shRecord a session, then export to CSV or EDF+ for analysis:
# CSV (no extra deps)
python -m src.exporter session.jsonl --format csv --output session.csv
# EDF+ (requires pip install ".[export]")
python -m src.exporter session.jsonl --format edf --output session.edf# Install Python dev + ML training dependencies
make install-all
# Install plugin dependencies
cd openclaw-plugin && npm install
# Run all tests (Python + TypeScript)
make test
# Run only Python tests
make test-python
# Run only plugin tests
make test-plugin
# Build the TypeScript plugin
make build-plugin
# Train an ML classifier (optional, uses synthetic data)
make trainAll configuration is via environment variables. Copy .env.example to .env and customize:
cp .env.example .envKey variables:
| Variable | Default | Description |
|---|---|---|
BCI_PORT |
7680 |
State server HTTP port |
BCI_HOST |
127.0.0.1 |
State server bind address |
BCI_SAMPLE_RATE |
250 |
EEG sample rate (Hz) |
BCI_WINDOW_SIZE_MS |
1000 |
DSP sliding window size |
BCI_MODEL_PATH |
None |
Path to trained ML model (.joblib) |
BCI_STATE_SERVER_URL |
http://127.0.0.1:7680 |
Plugin: state server URL |
BCI_USE_WEBSOCKET |
false |
Plugin: use WebSocket instead of HTTP polling |
See .env.example for the full list with defaults.
| Schema | Purpose |
|---|---|
bci_stream.schema.json |
Raw BCI packets from BrainFlow |
processed_features.schema.json |
Extracted frequency-domain features |
bci_state.schema.json |
LLM-readable brain state (injected via plugin) |
state_server_api.schema.json |
HTTP API contract (GET /state, GET /health) |
OpenClaw-BCI/
├── signal-processor/ # Python: BrainFlow + DSP + HTTP server
│ ├── src/ # Source modules
│ └── tests/ # pytest test suite
├── openclaw-plugin/ # TypeScript: OpenClaw plugin
│ ├── src/ # Plugin entry point
│ └── tests/ # vitest test suite
├── schemas/ # JSON Schema definitions
├── skill/ # BCI SKILL.md for LLM interpretation
├── scripts/ # Demo and utility scripts
└── docs/ # Architecture documentation
- Python: BrainFlow, FastAPI, NumPy, SciPy, Pydantic, scikit-learn
- TypeScript: OpenClaw Plugin SDK, Vitest
- Transport: HTTP/JSON + optional WebSocket (localhost)
This project is licensed under the GPL-3.0 License. See the LICENSE file for details.