Neutron AI

An Electron desktop app that lets an AI agent control your computer — screenshots, mouse, keyboard, text — to complete tasks you describe in plain language. Built on Anthropic and OpenAI models, with a local SQLite store and optional vector search.

---

Requirements

Platform	Minimum
macOS	12 Monterey, Apple Silicon or Intel
Windows	10 / 11, x64
Node.js	18+

macOS additional deps:

xcode-select --install       # Xcode CLT for node-gyp
brew install libomp           # required by faiss-node

Windows additional deps:

• Visual Studio Build Tools 2019+ with the Desktop development with C++ workload (for node-gyp)
• .NET SDK 8 — builds the ForegroundAppInfo helper that detects the frontmost window

---

Getting started

git clone https://github.com/JasonLeviGoodison/neutron
cd neutron

# Copy the env template and fill in your AI provider keys
cp example.env.json env.json
# edit env.json — add OPENAI_API_KEY and/or CLAUDE_API_KEY

npm install      # builds native modules; takes 1-3 min on first run
npm start

The first launch opens the permissions wizard. Grant Accessibility and Screen Recording in System Settings → Privacy & Security when prompted.

You can also enter your API keys in the app's settings after launch — no restart required.

Voice transcription uses a local Whisper model (downloaded on first use, ~77 MB) and requires no additional API key.

---

Project layout

src/                  Electron renderer + shared TypeScript
  agent.ts            Main agent loop — tool dispatch, streaming, screenshots
  ai/llm.ts           LLM provider bridge (Anthropic + OpenAI)
  computer.ts         Interface for OS control actions
  macos-computer.ts   macOS implementation (robotjs + Swift subprocess)
  windows-computer.ts Windows implementation (robotjs + PowerShell)
  components/         React UI
  contexts/           App-wide React contexts
  hooks/              Custom hooks including useDeepgram (local Whisper)

node-src/             Electron main process
  IPCHandlers.ts      All IPC channel registrations
  WindowService.ts    Window creation and lifecycle
  ScreenshotService.ts Screenshot capture
  StoreService.ts     Secure local storage (tokens, settings)

subprocess/           Native helpers spawned by the main process
  *.swift             macOS helper (keyboard monitoring, click capture, etc.)
  ForegroundAppInfo/  Windows C# helper (frontmost window detection)

shared/               Types shared between renderer and main
__tests__/            Jest unit tests

---

Development scripts

npm start               # dev build with hot reload
npm test                # jest unit tests
npm run lint            # ESLint
npm run build-swift     # recompile the macOS Swift subprocess
npm run build-win-native  # recompile the Windows C# helper
npm run reset:permissions # wipe macOS TCC grants for the app (useful during dev)
npm run reset:data        # delete local onboarding/token/settings files

---

Building and releasing

npm run make produces unsigned platform artifacts in out/make/.

For signed builds, set the environment variables in .env before running — see CI-CD-SETUP.md for the full list. The GitHub Actions workflow (.github/workflows/release.yml) triggers on v*.*.* tags:

npm run release          # bump version + tag (auto-detects patch/minor/major)
git push --follow-tags   # triggers CI

---

Contributing

See CONTRIBUTING.md.

Security

See SECURITY.md.

License

MIT