NeuralCompose is a privacy-oriented macOS research prototype for EEG-driven communication, signal visualization, semantic composition, and sleep-cycle experimentation.
A Muse headband can feed four-channel EEG into a Swift pipeline for acquisition, windowing, signal-quality checks, intent classification, semantic visualization, text generation, and speech. The repository also includes deterministic synthetic and playback modes, offline evaluation tools, and experimental dialectical dialogue loops.
Research prototype: NeuralCompose is not a medical device and must not be used for diagnosis, treatment, safety-critical communication, or clinical decisions.
| Component | Default location |
|---|---|
| SwiftUI application and visualization | Mac |
| EEG acquisition and preprocessing | Mac |
| Core ML classifiers and embeddings | Mac / Apple Neural Engine when available |
| MLX models | Mac / Apple Silicon GPU when configured |
| Ollama generation | Configured Ollama server, commonly the same Mac |
| Claude generation | Anthropic through the locally installed Claude Code CLI |
| Interaction logs and research artifacts | Local filesystem |
Most of the application can run without hardware, model weights, Ollama, Claude, or BrainFlow. The synthetic stream and deterministic fallbacks are the recommended first launch.
Cloud generation is opt-in. Selecting the Claude runtime sends prompt text through the authenticated Claude Code CLI. NeuralCompose records the requested and resolved runtime identity so local and cloud execution are not presented as interchangeable.
The committed golden recording contains TP9, AF7, AF8, and TP10 data from a Muse S. It supports deterministic regression tests of playback, windowing, feature extraction, channel health, and visualization behavior. See Recordings/golden/README.md.
- macOS 14 or newer
- Apple Silicon recommended
- Git
- Swift 6 toolchain
- Xcode Command Line Tools
Install the command-line tools when necessary:
xcode-select --installConfirm the toolchain:
BCICore— pure-Swift models, protocols, FSMs, buffers. No third-party deps.BCIBridge— Obj-C++ shim for BrainFlow (stub by default, gated byBCI_BRAINFLOW_AVAILABLE).BCIEEG—BrainFlowService,SyntheticEEGStream,PlaybackEEGStream,EEGScalpPlotterView,NeuralWorkspaceView.BCIClassifier— Core ML wrapper + deterministic mock (also the CI classifier); also hostsCoreMLSentenceEmbedder+WordPieceTokenizerfor real semantic embeddings.BCILLM— MLX-Swift linked only here. Adapter + stub + tokenizer.NeuralComposeApp— SwiftUI views, Phase B debug window, menu-bar UI.EmbeddingBench— sibling executable (not part of the app) that benchmarks anySentenceEmbedderconformer; knows nothing about Core ML or MLX.
The app talks to BCILLM through NextWordPredicting, so there's exactly
one MLX runtime copy in the linked binary.
Related architecture notes:
- Three Orthogonal Concerns separates Science, Engineering, and Computation.
- Engineering Runtime scopes bounded implementation backends.
- Julia Science Workspace keeps Julia as an offline scientific laboratory, not an app runtime.
- NeuralComposeEEG defines a separate, shadow-only four-channel Muse encoder benchmark with complete-session splits; it has no Swift or live-control dependency.
- EEG Mathematics, Physics, and Methods Scope keeps the current encoder work grounded in the necessary linear-algebra, signal-processing, and evaluation foundations while deferring forward models and policy/control theory to later falsifiable experiments.
- State Reconstruction Goal 0 and Trajectory Analysis Goal 1 turn soak telemetry into falsifiable science artifacts.
- Sobolev and ZPD Hypotheses places smooth dynamics and proximal intervention as falsifiable research claims.
- Symbolic Systems as Hypothesis Sources keeps traditions like geomancy as testable abstractions, not runtime modes.
- Semantic-to-Prosody Boundary separates what text is generated from how it is spoken.
- Prosody Feature Contract defines the cadence fields that Engineering can measure and Science can model.
- Prosody MVP Experiment preregisters the first cadence hypothesis: reflective_prosody_v1.
Rust/prosody_features is the first deterministic measurement crate.
It is not wired into the Swift runtime. It measures mono audio into
prosody features that can later feed telemetry contracts:
cd Rust/prosody_features
cargo testThe codebase is organized into four layers, named for role (not current contents) so they remain meaningful as the platform grows:
┌─────────────────────────────────────────────────────┐
│ Interface │
│ SwiftUI · SceneKit · Plotters · Channel-health UI │
└────────────────────────▲────────────────────────────┘
│ depends on
┌────────────────────────┴────────────────────────────┐
│ Intelligence │
│ DSP · Features · Classifier · Embeddings · Project │
└────────────────────────▲────────────────────────────┘
│ depends on
┌────────────────────────┴────────────────────────────┐
│ Runtime │
│ EEGStreaming · AsyncMulticastChannel · Supervisors │
│ Recording · Diagnostics │
└────────────────────────▲────────────────────────────┘
│ depends on
┌────────────────────────┴────────────────────────────┐
│ External Systems │
│ Muse · BrainFlow · OSC · Playback · Synthetic │
└─────────────────────────────────────────────────────┘
▼ data flows downward
Install the full Xcode application when using MLX GPU execution, Metal kernels, app signing, or Xcode-based builds.
After installing Xcode:
sudo xcode-select -s /Applications/Xcode.app/Contents/Developer
sudo xcodebuild -license accept
xcodebuild -versionOptional external systems:
- BrainFlow for direct Muse acquisition
- Ollama for local HTTP generation
- Claude Code CLI for the opt-in Anthropic runtime
- Converted Core ML and MLX model artifacts under
Models/
git clone https://github.com/aurascoper/NeuralCompose.git
cd NeuralComposeThe commands below assume the repository root is the current directory.
Synthetic mode needs no Muse, BrainFlow installation, external model weights, Ollama daemon, or Claude login.
./Scripts/build.sh
./Scripts/run-synthetic.shrun-synthetic.sh launches the SwiftPM executable with:
NEURALCOMPOSE_BOARD_PROFILE=synthetic
You can also launch it directly:
NEURALCOMPOSE_BOARD_PROFILE=synthetic \
swift run -c debug NeuralCompose./Scripts/build.shEquivalent SwiftPM command:
swift build -c debugBare executable:
.build/debug/NeuralCompose./Scripts/build.sh --releaseBare executable:
.build/release/NeuralComposeswift package clean
rm -rf .build
./Scripts/build.shRemoving .build also removes cached dependencies and packaged application bundles, so the next build takes longer.
A bare SwiftPM executable is sufficient for synthetic development. Bluetooth, microphone, and speech-recognition paths should run through the packaged .app, because macOS privacy services read their usage descriptions from the bundle’s Info.plist.
Build and package a debug application:
./Scripts/build.sh
./Scripts/package-app-bundle.shThe resulting executable is:
APP_BIN="$PWD/.build/NeuralCompose.app/Contents/MacOS/NeuralCompose"Verify it:
test -x "$APP_BIN" && echo "NeuralCompose app executable is ready"
codesign --verify --deep --strict "$PWD/.build/NeuralCompose.app"Launch the packaged app directly so environment variables reach the process:
NEURALCOMPOSE_BOARD_PROFILE=synthetic "$APP_BIN"Do not use open NeuralCompose.app when testing environment-selected runtimes; Launch Services does not reliably preserve shell environment variables.
./Scripts/build.sh --release
./Scripts/package-app-bundle.sh --release
APP_BIN="$PWD/.build/NeuralCompose.app/Contents/MacOS/NeuralCompose"
"$APP_BIN"The packaging script applies an ad-hoc signature. Distribution outside the development Mac requires an Apple Developer signing, notarization, and release workflow that is not provided by the local script.
Set APP_BIN after packaging:
APP_BIN="$PWD/.build/NeuralCompose.app/Contents/MacOS/NeuralCompose"Prerequisites:
claude --version
claude loginLaunch:
env \
NEURALCOMPOSE_RUNTIME=claude \
NEURALCOMPOSE_MODEL=claude-sonnet-5 \
"$APP_BIN"This is a cloud path. The executable is local, but generation is brokered through the authenticated Claude Code service. If Claude is configured but cannot generate, the runtime fails closed rather than silently switching providers.
Install and start Ollama using its normal macOS installation, then pull the requested model:
ollama pull qwen2.5:0.5b
ollama listLaunch:
env \
NEURALCOMPOSE_RUNTIME=ollama \
NEURALCOMPOSE_MODEL=qwen2.5:0.5b \
"$APP_BIN"The runtime performs a bounded readiness check and requires the requested model to be available. A missing model disables the loop; it does not substitute Claude.
Check the executable and dependencies first:
printf 'APP_BIN=%s\n' "$APP_BIN"
test -x "$APP_BIN"
claude --version 2>/dev/null || true
ollama list 2>/dev/null || trueRun the packaged process from a terminal to retain stderr and structured runtime diagnostics.
The ordinary SwiftPM build is sufficient for synthetic mode, deterministic tests, stub predictors, and most development. A real MLX GPU path needs Metal shaders compiled by the full Xcode toolchain.
Build with Xcode:
./Scripts/build-xcode-mlx.shBuild and run the MLX smoke path:
./Scripts/build-xcode-mlx.sh --smokeRelease configuration:
./Scripts/build-xcode-mlx.sh --releaseThe script writes Xcode products under:
.build/xcode/Build/Products/
After an Xcode MLX build, package the normal SwiftPM app again when you need .build/NeuralCompose.app. package-app-bundle.sh searches the Xcode products for mlx-swift_Cmlx.bundle and includes it when a compiled default.metallib is available.
If packaging reports:
no mlx-swift_Cmlx.bundle with a metallib found
the app still launches, but the affected MLX spectral path falls back to its stub.
The default build compiles the BrainFlow bridge in stub mode. Direct Muse acquisition requires a compatible BrainFlow checkout or installation.
The build script searches in this order:
--brainflow-path=<path>~/Developer/brainflowbrew --prefix brainflow
Example:
./Scripts/build.sh \
--with-brainflow \
--brainflow-path="$HOME/Developer/brainflow"
./Scripts/package-app-bundle.sh
APP_BIN="$PWD/.build/NeuralCompose.app/Contents/MacOS/NeuralCompose"Launch the provided Muse script when its assumptions match your installation:
./Scripts/run-muse-s.shBluetooth access must be granted to the packaged application. A bare executable can be terminated by macOS privacy enforcement before the application can surface a normal error.
See HARDWARE_SETUP.md for board setup and TROUBLESHOOTING.md for acquisition failures.
Launch a recorded session through the playback profile:
./Scripts/run-synthetic.sh \
--profile playback \
--recording Recordings/golden/golden_20260710-141352.eeg.csvAnalyze the golden recording:
python3 Scripts/analyze-eeg-session.py \
Recordings/golden/golden_20260710-141352.eeg.csvRun all Swift tests:
swift testRun the deterministic golden-recording regression:
swift test --filter GoldenRecordingRegressionTestsCreate a relocatable release bundle, then a drag-to-Applications disk image:
./Scripts/package-macos-app.sh
./Scripts/create-dmg.shThe artifacts are written to dist/NeuralCompose.app and
dist/NeuralCompose-<version>.dmg. The bundle includes the app metadata,
icon, SwiftPM resource bundles, and any dynamic libraries produced by a
BrainFlow-enabled build. Both scripts use ad-hoc signing by default for local
use; pass --sign 'Developer ID Application: ...' when preparing a signed
distribution. See each script's --help output for build and output options.
Before distributing beyond the development machine, launch the bundle itself
and manually confirm permissions, Personal Voice, model/resource discovery,
telemetry location, runtime selection, and neuralcompose:// routing.
swift test --filter NeuralComposeAppTests
swift test --filter BCICloudBridgeTests
swift test --filter DialecticSessionTestsList discovered tests when validating CI filters:
swift test listRun repository Python contracts when their dependencies are installed:
python3 -m pytest -q Tests/eval
python3 -m unittest discover -s NeuralComposeEEG/tests -t .Before committing:
git diff --check
swift buildSome MLX, Core ML, live network, hardware, and operator-attended tests are intentionally environment-dependent. A green deterministic suite does not prove Muse connectivity, provider authentication, microphone authorization, or real model execution.
| Variable | Purpose |
|---|---|
NEURALCOMPOSE_BOARD_PROFILE |
Selects synthetic, playback, OSC, or a supported live board profile |
NEURALCOMPOSE_PLAYBACK_PATH |
Recording used by playback mode |
NEURALCOMPOSE_RUNTIME |
Selects generation runtime, currently claude or ollama on the packaged runtime path |
NEURALCOMPOSE_MODEL |
Requested model identity |
NEURALCOMPOSE_INTERACTION_LOG |
Enables opt-in local interaction logging when supported by the selected path |
Environment variables configure a launch; they are not durable application preferences. Start a new process after changing them.
NeuralComposeApp
├── BCICore pure-Swift models, protocols, actors, FSMs, buffers
├── BCIEEG synthetic, playback, OSC, BrainFlow, health, visualization
├── BCIClassifier Core ML classifier and sentence-embedding implementations
├── BCILLM isolated MLX runtime and deterministic fallbacks
├── BCIVoice speech recognition and synthesis seams
├── BCICloudBridge explicit opt-in generation egress
└── WorldModelDemo synthetic-task research demo, separate from live EEG claims
Load-bearing boundaries:
BCICoreowns portable interfaces and deterministic mechanisms.- MLX imports are isolated to
BCILLM. - Cloud generation is isolated to
BCICloudBridge. - The interface consumes resolved runtime and pipeline state rather than inventing provider or locality claims.
- Synthetic research demos do not imply validation on physical EEG.
See:
docs/Architecture.mddocs/architecture/PRINCIPLES.mddocs/architecture/decision-log/docs/Math.mddocs/Research.md
NeuralCompose/
├── Sources/
│ ├── BCIBridge/
│ ├── BCICore/
│ ├── BCIEEG/
│ ├── BCIClassifier/
│ ├── BCILLM/
│ ├── BCIVoice/
│ ├── BCICloudBridge/
│ ├── NeuralComposeApp/
│ ├── DialecticSession/
│ └── WorldModelDemo/
├── Tests/
├── Scripts/
├── NeuralComposeEEG/
├── Evaluation/
├── Recordings/
├── Models/
├── WorldModel/
├── docs/
└── paper/
Established engineering capabilities include deterministic playback, synthetic-mode operation, local pipeline instrumentation, real Muse recording workflows, Core ML integration, and runtime provenance mechanisms.
The following remain research questions or environment-dependent capabilities:
- reliable decoding of intended communication from consumer EEG;
- research-grade sleep staging from four Muse channels;
- sustained behavioral differences among dialogue profiles;
- cognitive-incubation or dream-analysis benefits;
- generalization of synthetic world-model findings to physical EEG;
- production-quality accessibility or medical use.
Documentation and telemetry should preserve the difference between an implemented pipeline, a successful local run, and scientific evidence.
HARDWARE_SETUP.mdMODEL_SETUP.mdCALIBRATION.mdTROUBLESHOOTING.mdSLEEP_CYCLE_DESIGN.mdRecordings/golden/README.md
A paper draft is available under paper/. Suggested citation when published:
Kinder, H. (2026). An open-source, privacy-preserving platform for EEG-guided cognitive incubation and dream-report analysis using consumer-grade hardware. In preparation.
MIT. See LICENSE.
Research prototype code. Do not use NeuralCompose to make clinical or safety-critical decisions.
- BrainFlow for the unified biosensor acquisition API
- MLX-Swift for Apple Silicon model execution
- Apple Core ML and the Neural Engine
- The Muse developer community
- Open-source EEG and sleep-research communities

