SpikeAgent

An AI-powered assistant for spike sorting and neural data analysis

Website

SpikeAgent is a web-based AI assistant designed to help neuroscience laboratories analyze neural electrophysiology data. It provides an intuitive interface for spike sorting workflows, data curation, and neural data analysis, powered by state-of-the-art language models (OpenAI, Anthropic, and Google's Gemini).

SpikeAgent automates and streamlines the spike sorting pipeline, from raw neural recordings to curated spike trains. It leverages AI to assist with:

• Spike sorting: Automated detection and classification of action potentials
• Data curation: AI-assisted quality control and unit validation
• Visual analysis: Vision-language models for analyzing spike sorting outputs
• Workflow guidance: Interactive assistance throughout the analysis pipeline

The tool integrates with SpikeInterface, a unified framework for spike sorting, providing a seamless experience for analyzing neural data from various recording systems.

1. Docker - Make sure Docker Desktop is installed and running (for Docker installation)
   • OR Python 3.11+ (for pip installation)
2. One API Key - Choose one of these:
   • OpenAI API Key (required for VLM curation) - OR -
   • Anthropic API Key - OR -
   • Google API Key

Tested on: Linux (Ubuntu) and macOS (Intel/Apple Silicon).

SpikeAgent offers two ways to install and run:

# Install from source
git clone https://github.com/SpikeAgent/SpikeAgent.git
cd SpikeAgent
pip install -e ".[app]"

Create a .env file in the SpikeAgent folder with at least one API key:

OPENAI_API_KEY=sk-...       # required for VLM curation
ANTHROPIC_API_KEY=sk-ant-...
GOOGLE_API_KEY=...

Run the application:

spikeagent
# or
python -m spikeagent.app.main

Optional: Spike sorters and other tools are not bundled by default. Install only what you need:

pip install kilosort          # Kilosort4 (requires GPU)
pip install mountainsort5     # MountainSort5
pip install herdingspikes     # HerdingSpikes
pip install MEArec            # Synthetic data generation

SpikeAgent offers two ways to run with Docker:

• CPU Version - Works on any computer, easiest to set up
• GPU Version - For systems with NVIDIA GPUs (needed for some spike sorters like Kilosort4)

Step 1: Create a .env file

Create a file named .env in your working directory with your API keys. You need at least one of these:

# Create the .env file
touch .env

Then add your API keys to the .env file. Here are examples:

Example 1: Using OpenAI (Standard)

OPENAI_API_KEY=sk-your-actual-key-here (required for VLM curation)

Example 2: Using OpenAI (Custom/Institutional Endpoint)

OPENAI_API_KEY=your_institution_key_here
OPENAI_API_BASE=https://your-institution-endpoint.com/v1

Example 3: Using Anthropic

ANTHROPIC_API_KEY=sk-ant-your-actual-key-here

Example 4: Using Google/Gemini

GOOGLE_API_KEY=your-google-api-key-here

You only need ONE of these options - choose the provider you prefer!

Important Notes: VLM curation currently requires OpenAI (OPENAI_API_KEY). Anthropic/Google can be used for other LLM features

• If using a custom or institutional OpenAI endpoint, include both OPENAI_API_KEY and OPENAI_API_BASE
• If using standard OpenAI, you only need OPENAI_API_KEY (no OPENAI_API_BASE needed)
• The .env file should be in the same directory where you run the Docker commands

Step 2: Run SpikeAgent

Option A: Using the automated script (Easiest):

# Run without volume mounts (if you don't need to access local data)
./run-spikeagent.sh

# Run with volume mounts (to access your data directories)
./run-spikeagent.sh /path/to/your/data /path/to/results

Volume Mounts (Recommended):

If you need SpikeAgent to access your local data files, you should mount your data directories when running the script:

# Mount a single data directory
./run-spikeagent.sh /path/to/your/raw/data

# Mount multiple directories (e.g., raw data and results folder)
./run-spikeagent.sh /path/to/raw/data /path/to/processed/results

# Mount relative paths (automatically converted to absolute)
./run-spikeagent.sh ./data ./results

Why mount volumes?

• SpikeAgent needs access to your raw electrophysiology data files
• You may want to save processed results to a specific location
• Config files (YAML) and other data should be accessible to the container

What paths should you mount?

• Raw data directory: Where your experimental data files are stored (e.g., .rhd, SpikeGLX files, etc.)
• Results/output directory: Where you want processed data and results saved
• Config directory: If you have YAML configuration files (optional)

The script will:

• Pull the latest image from GitHub
• Mount your specified directories (if provided)
• Start the container
• Wait for the application to be ready
• Open your browser automatically

Option B: Manual Docker commands:

# Pull the latest CPU image
docker pull ghcr.io/spikeagent/spikeagent-cpu:latest

# Quick start (no data mounts)
# Runs the app, but it can’t access files on your computer unless you mount them.
docker run --rm -p 8501:8501 --env-file .env ghcr.io/spikeagent/spikeagent-cpu:latest

# With data mounts (recommended)
# Mount your local data/results folders so SpikeAgent can read inputs and save outputs on your machine.
docker run --rm -p 8501:8501 --env-file .env \
  -v /path/to/your/data:/path/to/your/data \
  -v /path/to/results:/path/to/results \
  ghcr.io/spikeagent/spikeagent-cpu:latest

Once the container is running, open your browser and go to:
http://localhost:8501

That's it! You're ready to use SpikeAgent.

GPU Version (Build Locally):

The GPU version is not yet available as a pre-built package. You need to build it locally:

# Build the GPU image
docker build -f dockerfiles/Dockerfile.gpu -t spikeagent:gpu .

# Quick start (no data mounts)
# Runs the app, but it can’t access files on your computer unless you mount them.
docker run --rm --gpus all -p 8501:8501 --env-file .env spikeagent:gpu

# With data mounts (recommended)
# Mount your local data/results folders so SpikeAgent can read inputs and save outputs on your machine.
docker run --rm --gpus all -p 8501:8501 --env-file .env \
  -v /path/to/your/data:/path/to/your/data \
  -v /path/to/results:/path/to/results \
  spikeagent:gpu

Adding Volume Mounts After Startup:

If you need to access a data path that wasn't mounted when you started the container:

# Add mounts to existing container (preserves existing mounts)
./run-spikeagent.sh --add /path/to/new/data

# You can add multiple paths at once
./run-spikeagent.sh --add /path/to/data1 /path/to/data2

# Or restart with new mounts only (replaces existing mounts)
./run-spikeagent.sh --restart /path/to/data

The --add option will:

• Stop the current container
• Preserve all existing volume mounts
• Add your new paths
• Restart the container

Note: Docker containers cannot mount new volumes at runtime - a restart is required.

Troubleshooting:

• Port already in use? Make sure port 8501 is free, or stop any existing containers: docker stop spikeagent
• Can't pull image? The image is public, so no authentication needed. If you have issues, make sure Docker is running.
• ARM64/Apple Silicon (M1/M2/M3 Mac)? If you get "no matching manifest for linux/arm64" error, the run script will automatically detect this and build the image locally for you. The first build may take 10-20 minutes. Once multi-arch images are available, this will no longer be necessary.
• API connection errors? Double-check your .env file has the correct API keys and is in the same directory as your Docker command.

You can test SpikeAgent with open datasets such as Neuropixels 2.0 chronic recordings in mice and AutoSort flexible electrode recordings.

tutorials/VLM_curation_tutorial.ipynb: A programmatic example for users who want to use only the VLM curation and merge analysis modules of the agent. Demonstrates how to classify units as "Good" or "Noise" using Vision-Language Models. Shows how to identify and resolve oversplit units through AI-driven merge analysis. Ideal for users who want to integrate SpikeAgent's AI curation directly into their existing Python workflows without using the full chat interface.

spikeagent/
├── src/spikeagent/                      # Main source code package
│   ├── app/                            # Application code
│   └── curation/                       # Curation and VLM analysis tools
├── dockerfiles/                        # Docker configuration files
│   ├── Dockerfile.cpu                  # CPU Docker image
│   └── Dockerfile.gpu                  # GPU Docker image
├── docs/                               # Documentation
│   └── img/                            # Documentation images
├── tutorials/                         # Jupyter notebook tutorials
│   ├── vlm_curation_and_merging_tutorial.ipynb # VLM curation and merge analysis tutorial
└── tests/                              # Test suite

Comprehensive documentation is available in the docs/ directory:

Documenation Website

• User Guide: How to use SpikeAgent for spike sorting and curation
• API Reference: Programmatic API documentation for custom workflows
• VLM Guide: In-depth guide to VLM curation and prompt customization

For detailed information and troubleshooting:

• Review the Quick Start section above for installation
• Check the User Guide for workflows and common tasks
• See the VLM Guide for AI curation details and prompt customization
• Explore the Jupyter notebook tutorials in tutorials/
• Ensure your .env file contains the required API keys

If you find SpikeAgent useful for your work, please cite:

SpikeAgent: Lin, Z., Marin-Llobet, A. et al. Spike sorting AI agent (2025). Preprint at bioRxiv: https://doi.org/10.1101/2025.02.11.637754

SpikeInterface: Buccino, A. P., Hurwitz, C. L., Garcia, S., Magland, J., Siegle, J. H., Hurwitz, R., & Hennig, M. H. (2020). SpikeInterface, a unified framework for spike sorting. Elife, 9, e61834.