Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/tinkerer9/collabokeys/llms.txt

Use this file to discover all available pages before exploring further.

CollaboKeys can be run directly from source for development or packaged into a distributable macOS .app bundle and .dmg installer using electron-builder. Both paths require compiling a small C helper that performs the low-level keyboard emulation through the macOS ApplicationServices framework.

​
Prerequisites

Before building, make sure the following are available on your system:
  • Node.js — provides npm and the JavaScript runtime that runs both the server and the Electron app
  • Xcode Command Line Tools — required for clang to compile the C keyboard helper; install with: 
    xcode-select --install
  • macOS — the host-side server and packaged app target darwin only; the client webpage runs in any browser on any platform

​
Clone and install

1

Clone the repository

git clone https://github.com/tinkerer9/CollaboKeys.git && cd CollaboKeys
2

Install dependencies

npm install
This installs all packages declared in package.json:
PackageTypePurpose
socket.ioRuntimeReal-time WebSocket communication between server and players
winstonRuntimeStructured logging to files and the admin page
electronDevWraps the Node.js server in a desktop app window
electron-builderDevPackages the Electron app into a .app bundle and .dmg
3

Compile the C keyboard helper

npm run compile
This runs the following clang command directly from package.json:
clang src/emulate/helper.c -framework ApplicationServices -arch arm64 -arch x86_64 -O3 -o src/emulate/helper
The flags produce a universal binary — a single executable that runs natively on both Apple Silicon (arm64) and Intel (x86_64) Macs. The compiled binary is written to src/emulate/helper and is used at runtime to forward keypress events to the active application.
You must recompile the helper any time src/emulate/helper.c changes. The npm run build script runs compile automatically before packaging, so a manual compile step is only needed for local development with npm start or npm test.

​
Run modes

CollaboKeys supports three modes depending on your goal: 
npm start          # Electron app mode — full desktop app with splash screen and admin dashboard
npm test           # Headless server mode — Node.js only, no Electron window
npm run build      # Package as distributable — compiles helper then builds .app and .dmg into dist/
npm run release    # Package and publish — compiles helper then builds and uploads to GitHub Releases
CommandEntry pointUse case
npm startelectron . → src/main.jsLocal development or hosting a session with the full desktop UI
npm testnode src/server.jsHeadless testing or running on a machine without a display
npm run buildnpm run compile && electron-builderProducing a distributable for others to download
npm run releasenpm run compile && electron-builder --publish alwaysBuilding and publishing the app directly to GitHub Releases
npm test runs the server via Node.js directly, bypassing Electron entirely. The app.* settings in src/config.json (splash screen time, display sleep prevention, DevTools) are ignored in this mode.

​
Packaging details

The electron-builder.yml file at the project root controls how the app is packaged. The key configuration values are:
electron-builder.yml
appId: com.collabokeys.app
productName: CollaboKeys
mac:
    icon: images/icon.icns
    target: dmg
    category: public.app-category.utilities
    identity: null
extraResources:
  - from: src/emulate/helper
    to: helper
files:
  - node_modules/**
  - "!node_modules/**/README*"
  - "!node_modules/**/*.md"
  - "!node_modules/**/*.map"
  - src/**
  - package.json
  - LICENSE
  • The build target is dmg, producing both a .app bundle and a .dmg disk image in the dist/ folder
  • The compiled C helper at src/emulate/helper is copied into the app bundle as an extra resource under the name helper
  • README files, markdown, and source map files inside node_modules are excluded to keep the bundle size down
  • The identity: null field means the app is not code-signed through Apple’s Developer Program
  • The "os": ["darwin"] field in package.json declares macOS as the only supported build target
Because CollaboKeys is not signed or notarized, macOS Gatekeeper will block it from launching when the .dmg is downloaded from the internet. Users will see a message saying the app is “damaged and can’t be opened.” To fix this, they must remove the quarantine attribute from Terminal:
xattr -dr com.apple.quarantine /Applications/CollaboKeys.app
See the Installation page for the full first-launch instructions.

​
Contributing

Before opening a pull request, discuss the change you want to make via a GitHub Issue or another channel with the repository owners. Then follow these steps to keep the repository clean:
  • Remove build artifacts — delete the dist/ folder before committing; generated binaries and installers should not be checked into source control
  • Update the README — document any interface changes, including new configuration options, new CLI commands, new exposed ports, or changed file locations
  • Increment the version — bump the version field in package.json following semver to reflect the scope of changes in the pull request
See CONTRIBUTING.md on GitHub for the full contribution guide, including the code of conduct and the complete pull request process.

Build docs developers (and LLMs) love

Get started for freeTalk to us