PiEEG Agent

Natural language EEG lab notebook. Train pattern classifiers, analyze connectivity, compare sessions — all by talking to an AI copilot that reads your live brain signals.

The same toolset can be served to an external host with pieeg-agent mcp. That process does not load a model. See MCP.

Requires: PiEEG-server running with --lsl

Install

# One-line remote install
curl -sSL https://raw.githubusercontent.com/pieeg-club/PiEEG-agent/main/install.sh | bash
 
# Or clone manually
git clone https://github.com/pieeg-club/PiEEG-agent.git
cd PiEEG-agent && chmod +x setup.sh && ./setup.sh

No Node.js required — the React frontend is prebuilt and bundled.

Quick Start

# Terminal 1 — start PiEEG server with LSL output
pieeg-server --lsl
 
# Terminal 2 — launch agent
pieeg-agent web

Open http://localhost:8000 (opens in a new tab). On first launch, a setup wizard prompts for an LLM provider and API key. Configuration is saved to ~/.pieeg-agent/config.json.

What It Can Do

1. Real-Time Spectral & Signal Quality Monitoring

you > how's my signal?
copilot > All channels read "good", quality 0.98 — trustworthy signal.

you > what are my band powers right now?
copilot > Alpha is dominant (relative power 0.87, 8–13 Hz) and Beta/Theta ratio is low (0.31).

Available tools: get_neural_state, get_band_powers, get_channel_quality, get_recent_events, find_artifacts

2. Pattern Training

Train custom condition classifiers by conversation:

you > train a pattern called "eyes-closed-alpha"
copilot > Starting pattern training for "eyes-closed-alpha"…
          First, sit normally with eyes open.
          Ready to record 'rest' for 4 seconds? (say yes when ready)

you > yes
copilot > ✓ Captured 32 frames, quality 0.94.
          Now close your eyes for the active condition.

[repeats 3 reps]

copilot > Pattern "eyes-closed-alpha" trained:
          - Balanced accuracy: 0.89 (leave-one-rep-out CV)
          - Top cue: Alpha power increase in O1/O2
          - Channel importance: O1★★★ O2★★★ C3★ C4★

Pattern classifiers use L2 + group-lasso regularization (spatial sparsity) and leave-one-rep-out cross-validation to prevent temporal leakage. Balanced accuracy is reported so class imbalance cannot inflate scores.

3. Spectral Analysis

you > analyze my alpha rhythm
copilot > Individual alpha peak (IAF): 10.2 Hz
          Alpha power: 0.73 (dominant)
          1/f slope: -1.1 (typical healthy EEG)
          Spectral entropy: 0.68
          Frontal alpha asymmetry: -0.05 (balanced)

4. Connectivity Analysis

you > show connectivity in the alpha band
copilot > Mean correlation: 0.34
          Strongest pair: C3↔C4 (r=0.72) — motor cortex synchrony
          Most connected: C3 (6 strong links)

5. Session Recording & Comparison

you > record a session called "eyes-closed" for 60 seconds
[later]
you > compare eyes-closed vs eyes-open
copilot > Alpha power: +0.92 SD (eyes-closed higher)
          Beta power: -0.54 SD (eyes-closed lower)
          — effect sizes are within-session Cohen's d

6. Jupyter Notebook Generation

you > create a notebook analyzing my eyes-closed alpha pattern
copilot > ✓ Created: eyes_closed_alpha_analysis.ipynb
          Includes: pattern ROC curve, feature importance, band power evolution

CLI Commands

pieeg-agent streams     # Discover available LSL streams
pieeg-agent monitor     # Live state monitor (no LLM)
pieeg-agent ask "what is my alpha band power?"   # One-shot question
pieeg-agent chat        # Interactive terminal chat
pieeg-agent web         # Web interface (recommended)
pieeg-agent mcp         # Same tools, for an external MCP host (no built-in LLM)

Device Control

# Preview mode — shows what the agent would do
pieeg-agent web --allow-actions
 
# Execute mode — actually controls the device
pieeg-agent web --allow-actions --execute

All actions pass through a safety gate: allowlist → cooldown → dry-run → audit log.

pieeg-agent mcp uses the same flags and the same gate. Device tools are not advertised unless --allow-actions is set.

MCP

pieeg-agent mcp is the other door into the same tool collections ask and chat use (neural state, decode, docs, web, utility, and gated actuators when asked). The host is the agent. This process does not call an LLM provider and does not need an API key. A saved key in ~/.pieeg-agent/config.json is not sent. Stream selection follows PIEEG_LSL_NAME, PIEEG_LSL_TYPE, and PIEEG_RING_SECONDS (defaults: PiEEG, EEG, 60 s).

Neural tools are read-only. Pattern tools record and score the live signal. Device tools, if present, may preview an action instead of performing it.

The server is the official MCP Python SDK v2 (MCPServer, mcp>=2,<3). It is the mcp extra, which also pulls websockets so --allow-actions can reach the PiEEG-server control plane.

The one-line installer (setup.sh, install.cmd) installs .[web,dev]. The dev extra currently includes that SDK, so a machine installed that way already has it. A bare pip install -e . does not. If the extra is missing, the command prints the install line and exits 2:

pip install -e ".[mcp]"

# Terminal 1 — LSL stream (hardware, or mock)
pieeg-server --lsl
# pieeg-server --mock --lsl
 
# Terminal 2 — leave this running
pieeg-agent mcp

Default endpoint: http://127.0.0.1:8765/mcp.

Transport is streamable HTTP, stateless: each host call is its own session. The server does not push elicitation or sampling back to the client.

A page on chatgpt.com or claude.ai cannot reach 127.0.0.1. Use a desktop or CLI host on this machine.

Host config

Start the LSL stream first in every case. Then either paste a URL (you already started the server) or let the host spawn stdio (do not start the server yourself).

URL shape (streamable-http):

{
  "mcpServers": {
    "pieeg": { "url": "http://127.0.0.1:8765/mcp" }
  }
}

VS Code Copilot uses a different file (.vscode/mcp.json):

{
  "servers": {
    "pieeg": {
      "type": "http",
      "url": "http://127.0.0.1:8765/mcp"
    }
  }
}

stdio shape. The host owns the process:

{
  "mcpServers": {
    "pieeg": {
      "command": "pieeg-agent",
      "args": ["mcp", "--transport", "stdio"]
    }
  }
}

If that app cannot find pieeg-agent, use the full path to the executable (the venv script, or pieeg-agent.cmd from the Windows installer).

Any other host: URL field http://127.0.0.1:8765/mcp after the server is up, or command pieeg-agent with args mcp --transport stdio if the host only accepts a local process. The app has to run on this computer.

On connect, the server prints a host-config snippet to stderr, including the URL or the stdio command for the transport you actually started.

A connected host should call a tool (get_neural_state, get_channel_quality, list_patterns, and the rest of the copilot toolset) and answer from that result. A numeric answer with no tool call means the server is not connected. Device tools stay hidden unless the server was started with --allow-actions.

If it does not connect:

• The pieeg-agent mcp terminal is still running (URL hosts only).
• The URL ends in /mcp, not the bare port. SSE hosts need /sse and --transport sse.
• stdio hosts: pieeg-agent is on that app's PATH, or the config uses the full path.
• A website in the browser cannot reach 127.0.0.1.

LLM Providers

# Non-interactive / Docker / CI
export PIEEG_LLM_PROVIDER=anthropic
export ANTHROPIC_API_KEY=sk-ant-...
pieeg-agent web

Architecture

PiEEG Agent solves the rate mismatch between LLMs (~1 Hz) and EEG (250–500 Hz) using a perception cascade:

The LLM pulls state via tools — it is never streamed raw data. An MCP host pulls the same tools. Raw samples stay in this process either way. The ingestion thread runs independently of the caller so no samples are lost.

Honest Metrics

• Band-power ratio indices (focus, relax, engagement) are shorthand names for spectral band-power ratios (such as β / (α + θ) and α / (α + β)) normalized to a rolling 10-minute within-session window. They indicate whether a band ratio is high or low relative to your recent baseline, not an absolute or validated measure of cognitive focus, relaxation, or emotion (and can shift with eyes open/closed or cranial muscle tension).
• A ~ prefix marks the warm-up period before enough variance is established.
• Pattern CV scores are leave-one-rep-out balanced accuracy — honest at the data scale you have.
• Session comparisons report within-session Cohen's d with explicit caveats — not a generalization claim.

Environment Variables