Shared Mac Keyboard Setup with Karabiner, Goku, and Keyboard Maestro

One of the most useful ideas in keyboard automation is separating source config from generated or machine-local config.

That becomes even more important if you use multiple macOS user accounts on the same machine.

A practical shared setup can look like this:

one shared Goku config file
one shared Keyboard Maestro sync file
per-user generated Karabiner JSON

The architecture

A clean shared layout is:

/Users/Shared/keyboard/
  karabiner.edn
  Keyboard Maestro Macros.kmsync

The idea is simple:

keep the editable source files in a shared location
let each user account generate or consume what it needs locally
avoid making the wrong file the symlink target

Why this split matters

Karabiner works from karabiner.json, but Goku is much nicer to edit because it lets you define your config in karabiner.edn.

So the durable source of truth should be the Goku file, not the generated JSON file.

That gives you a better workflow:

edit one shared source file
run goku
let Karabiner reload the generated JSON

Shared Goku setup

A practical per-user link looks like this:

mkdir -p ~/.config
ln -sfn /Users/Shared/keyboard/karabiner.edn ~/.config/karabiner.edn

Then in each user account:

goku

That account reads the shared source but still generates its own local Karabiner JSON -- keeping the editable config shared and the output local.

What not to share directly

Avoid treating generated files as the main editable asset.

In practice, that means:

do not use karabiner.json as your real source of truth
prefer sharing the source .edn file instead
let each account generate its own JSON output

That keeps the setup easier to reason about and reduces weird reload behavior.

Shared Keyboard Maestro setup

Keyboard Maestro fits well into the same model.

Instead of copying macros manually between accounts, sync both accounts to the same .kmsync file in the shared folder.

That gives you:

one shared macro set
easier maintenance
simpler backup and recovery

The main caution is straightforward:

opening an existing sync file can overwrite local macros in that account

So export anything important before switching an existing account to shared sync.

When shared setup is the right choice

A shared setup is a good idea when:

the same person uses multiple macOS accounts
the workflow is similar in both accounts
you want one source of truth for keyboard behavior
you do not want to duplicate maintenance work

When per-user setup is better

A shared setup is not always the right answer.

Use per-user configs if:

the two accounts have very different workflows
the same keys should mean different things in each account
one account is experimental and the other is stable
you want full isolation between environments

In that case, keep separate karabiner.edn files per user and separate Keyboard Maestro sync sources, or stop syncing macros entirely.

The maintenance mindset

The real value of a shared setup is not only convenience. It is maintainability.

A good automation system should be:

easy to update
easy to inspect
easy to restore
obvious about what is shared versus local

That is why directory structure and symlink choices matter more than they first appear.

Share the human-edited source files. Keep generated files local. That split is what makes the whole thing maintainable — one place to make changes, each account consuming what it needs, no mysterious drift between users.