AEA (Automated EEG Analysis) is a library of EEG analysis skills and recipes with MNE-Python as its main execution backend. An agent reads the skills, writes analysis code, runs it in your Python environment, and records the results in a study directory. The skills are instructions for the agent; they are not shell commands or a standalone EEG application.
Choose a starting point:
Both routes need Git and Conda or Miniconda. The shared Python environment below runs the numerical analysis; model access is only needed for the agent route.
This guide describes main. See versions and changes
to choose the fixed v0.3.2 snapshot or update an existing checkout.
Run these commands in a terminal:
git clone https://github.com/dengzhe-hou/auto-eeg-analysis.git
cd auto-eeg-analysis
conda env create -f environment.yml
conda activate aeais
On Linux x86_64, replace the environment creation command with
conda env create -f tools/env/environment-pinned.yml to use the tested package versions.
This snapshot has been rebuilt in a separate Linux environment; it is not a
cross-platform lock. Other platforms can use environment.yml, then capture the
installed environment with their saved analysis.
Run commands from the AEA repository root. For the agent route, keep the client’s
working directory there too: skills refer to tools/, templates/, and recipes/.
Put each study in its own directory, such as projects/my-study/, and pass that
path to the skill.
On macOS or Linux, from the activated aeais environment:
bash tools/env/check_env.sh
On Windows PowerShell:
powershell -ExecutionPolicy Bypass -File tools/env/check_env.ps1
The probe writes ENVIRONMENT.json in the repository root. Check that MNE is
available. Missing optional packages are listed separately; install the packages
needed by your chosen analysis, then rerun the probe. The default environment
includes MNE, mne-icalabel with ONNX Runtime, AutoReject, Pycrostates,
mne-connectivity, and pyprep. MATLAB, EEGLAB, FieldTrip, and FreeSurfer are optional.
See platform setup for details.
This small check exercises the documented library calls on synthetic data:
conda run -n aeais python -m pytest tools/tests/test_skill_apis.py -q
It needs no EEG download or model call. Checks requiring absent optional packages are skipped. This verifies the installed library interfaces, not your study’s scientific results. For the full repository checks, run:
conda run -n aeais python -m pytest tools/tests/ recipes/
Data-dependent tests can skip when their datasets are absent. The MNE sample
regression tests download data only when AEA_FETCH_DATA=1 is explicitly set;
reuse an existing dataset cache before opting into that download.
For either N400 figure route, install and check Arial or Helvetica before starting. The fixed tutorial checks this before processing EEG.
To run the fixed Python tutorial, continue directly to the N400 data and run instructions. The remaining steps below are for analysis with an agent.
Skip this section for the fixed Python tutorial. For agent-led analysis, install and sign in to Codex CLI or Claude Code using its own setup instructions. The client needs local file access and command execution. AEA does not install a client, supply model access or configure credentials. Model subscription or API access is separate from the Python environment.
Make the skills visible using the command for your client:
python tools/install_skills.py --agent codex
python tools/install_skills.py --agent claude
Use --agent both if you use both clients. The installer creates repository-local
links from .agents/skills/ for Codex or .claude/skills/ for Claude Code to the
original skills/ directories. These are the clients’ documented discovery
locations; both support linked skill directories. See the official
Codex skill documentation and
Claude Code skill documentation.
The installer leaves an existing link to the same skill unchanged. If a destination already contains a different directory or link, it reports the conflict and leaves that item intact. Move the conflicting item before retrying. Links track edits and updates to existing skills automatically; rerun the installer after pulling a version that adds new skills.
On Windows, creating directory links requires symlink permission, for example with Developer Mode enabled or an appropriately privileged terminal. Alternatively, run the checkout, environment, installer, and client together inside WSL. A failed link installation reports an error and does not silently copy the skills.
For ERP CORE N400, use the copy-ready brief and approval prompt. They keep the official nested raw-data directory unchanged and separate it from projects/n400-agent/. Skip the header-scanner command below for that layout; it scans only the top level.
For recordings stored directly in raw/, create a directory with this layout:
projects/my-study/
raw/
subject-01.edf
subject-02.edf
The header scanner reads .bdf, .edf, .set, .fif, and .vhdr files directly
inside raw/. Keep companion files together, such as BrainVision .eeg and
.vmrk files or an EEGLAB .fdt file. For nested or BIDS data, tell the agent the
existing layout so it can use the appropriate reader and create the dataset brief.
Existing raw data can be linked into the study rather than duplicated.
You can inspect headers before opening an agent:
python tools/auto_brief.py --raw-dir projects/my-study/raw/ --out projects/my-study/DATASET_BRIEF.md --json projects/my-study/auto_brief_scan.json
Review the resulting DATASET_BRIEF.md. You must supply the experiment’s meaning:
condition and event-code mapping, subject/group design, hypotheses, and any
parameters the headers cannot establish. The agent uses this brief and an agreed
ANALYSIS_PLAN.md to run the study.
Start codex or claude from the repository root in the activated environment.
In Codex CLI, use /skills or type $ to select an AEA skill. In Claude Code,
type / followed by the skill name. Enter the following examples inside the
client, not in your terminal shell. If newly installed skills do not appear,
restart the client from the repository root. These invocation forms are documented
by OpenAI and
Anthropic.
For compatible N400 semantic-priming data, in Codex CLI:
$eeg-recipe n400-semantic --data projects/my-study
In Claude Code:
/eeg-recipe n400-semantic --data projects/my-study
Choose a recipe matching your paradigm from the recipe library. The skill checks the required channels, sampling rate, events, and trial counts, asks about missing information, and waits for confirmation before running the pipeline. A recipe’s certified reference configuration may differ from its full analysis workflow; read its numerical-specification note when reproducing benchmark values. The N400 example shows the research request, approved choices and saved outputs from a recorded agent run.
Use eeg-pipeline for projects/my-study. Read the raw data headers, help me fill
DATASET_BRIEF.md, and draft ANALYSIS_PLAN.md for my attention experiment.
Use MNE-Python and wait for me to approve the plan before running the analysis.
Describe your paradigm, event meanings, hypotheses, and group design. The plan determines which analysis branches and statistics run.
Use eeg-audit on projects/my-study in adversarial reviewer mode.
This workflow reads the existing plan, statistical JSON, findings, report, captions,
and backend logs. Its independent model review requires a separately configured
reviewer connection. The default is a fresh, read-only Codex CLI process. Complete
the setup below before W1’s default audit or W3. Existing configured MCP and
llm-chat connections remain alternatives.
Install Codex CLI on the machine running the analysis agent, even if that agent is Claude Code. In your terminal, check the installation and sign in:
codex --version
codex login
codex login status
Use an account with access to the selected reviewer model, currently gpt-6-astra.
The audit uses a model call and consumes that account’s usage. This setup needs no
MCP registration. Keep Codex on the command path available to your analysis agent.
Do not put credentials into a study directory or commit them to the repository.
Then ask your analysis agent:
Use eeg-audit on projects/my-study with reviewer: codex-cli.
Build the audit bundle, then use a fresh codex exec process with gpt-6-astra,
max effort, and a read-only sandbox. Save the prompt, response, event log,
and exit status in audit-stage, and write the audit report from that response.
The skill’s invocation instructions
give the exact command and output files. It closes stdin, waits for completion,
and checks the exit code and JSON before reporting a verdict. On native Windows,
the agent can launch the same command through Python with stdin=subprocess.DEVNULL;
Bash/WSL uses < /dev/null. If authentication, model access, or execution fails,
the audit remains incomplete and the error log explains the next setup step.
See OpenAI’s non-interactive mode documentation
for authentication and output handling.
You can give an agent the source file directly when it does not have a compatible skill selector:
Read skills/eeg-recipe/SKILL.md and follow it for n400-semantic with
--data projects/my-study. Keep the AEA repository as the working directory.
Read the referenced child SKILL.md files when a stage calls for them.
Use the aeais environment for Python commands.
The client still needs local file access, command execution, and a configured reviewer for the audit stage. This entry point does not establish that the client has been evaluated end-to-end.
Use the tasks in your approved plan. This table is a starting point; each linked skill specifies its required inputs, full parameters and output files. Record the resolved choices in the dataset brief and analysis plan before execution.
| Task | Skills | Choices to supply or approve | Main outputs |
|---|---|---|---|
| Clean recordings and inspect quality | Preprocessing, ICA, QC | Filters, reference, bad-channel/artifact policy, ICA exclusions and QC gates | Cleaned EEG, processing summaries and qc-stage/ reports |
| Measure event-related potentials | Epoching, ERP | Event-to-condition mapping, epoch/baseline windows, rejection, ROI, component window and measurement | Epochs, participant averages and erp-stage/component_measures.csv |
| Examine power over time | Time-frequency | Conditions, frequencies, method/cycles, baseline window and normalization | tfr-stage/ power and inter-trial coherence HDF5 files |
| Measure spectral power | Spectral | Frequency bands, estimator, segment length, taper, overlap and any aperiodic-fit range | spectral-stage/ arrays and parameter/summary JSON |
| Estimate connectivity | Connectivity | Metric, sensor/source space, channel/ROI pairs, bands, time range and trial matching | connectivity-stage/ matrices and requested graph summaries |
| Test a planned contrast | Statistics | Observation unit and pairing, contrast, ROI/window, test/tail, correction, permutations and seed | stats-stage/ statistical JSON, arrays and findings |
| Prepare figures and a report | Figures, Report | Figure plan, data sources, units, uncertainty bands and output layout | SVG/PNG figures, captions and report-stage/ HTML/Markdown |
ERP and time-frequency tasks read cleaned epochs; statistics and figures read the matching participant-level outputs. The pipeline arranges these dependencies. See worked examples for a complete case and how to adapt its brief and plan to another study. The coverage page records which outputs have numerical evidence.
Analysis outputs belong to the study directory: stage-specific folders such as
preprocess-stage/, erp-stage/, stats-stage/, figure-stage/, report-stage/,
and audit-stage/. The plan and run logs record what was requested and completed.
For a repeatable run, retain the generated program and configuration using the saved-analysis replay workflow. It captures installed versions and runs the saved code without another model call. The archived external-use protocol explains how to record an independent run on your own data.
MNE is the main execution and certification reference backend. EEGLAB and FieldTrip provide cross-toolbox comparisons and selectable paths for the capabilities listed in the backend registry. Availability, API tests, and numerical certification describe different evidence. See certification coverage and the benchmark record for the measured configurations and tolerances.
| Symptom | Next step |
|---|---|
| Skills do not appear in the client | Install the links, then restart the client from the AEA repository root. |
| Windows cannot create skill links | Enable symlink permission or run the full setup inside WSL; see skill installation. |
| A requested package or backend is missing | Check the active environment, install the selected analysis’s dependencies and rerun the environment probe. See optional packages. |
| Windows crashes during LAPACK/SVD | Activate the environment or use conda run; see Windows environment activation. |
| Raw files are not found or cannot be read | The header scanner expects files directly in raw/; retain companion files and describe nested/BIDS layouts as in study preparation. |
| The audit fails at login or model access | Check codex login status, model access and the command path in reviewer setup. Keep the failed audit’s error log. |
| The fixed N400 tutorial stops or refuses the existing run directory | Keep the failed directory and error; correct the problem, then rerun in a fresh directory. --replay recomputes saved group statistics; it does not resume an interrupted run. |
| Replay refuses an existing output directory | Choose a new empty output directory and keep the captured bundle unchanged; see capture and execute. |
| The N400 figure exporter requests a font | Install Arial or Helvetica as described in the N400 example. |
If the problem persists, open an issue with the command, error, environment and minimal shareable example listed in Contributing.