Alter
Alter is a native macOS AI assistant: actions, dictation, meeting recording and
transcription, with local model support. Official docs are at
https://docs.alterhq.com. This skill uses the preferences file for narrowly
scoped hotkey work and the GUI for everything else.
Privacy boundary, read this first
Alter records meetings and stores transcripts and conversation history locally. Some of that content sits in the same preferences plist as the hotkeys, not only in its databases.
Never dump the whole plist. A bare defaults read com.wearedevx.alter or a
broad plutil -p can splash an entire meeting transcript into the transcript of
your own session, including names and whatever the meeting was about.
- Read named keys only, never the whole domain.
- Never open
Alter.sqlite,Search.sqlite, or anything under the transcripts directory. - Never quote, summarize, or store what you see if it leaks anyway. Say that it leaked and move on.
- If the user wants transcript content, tell them to export it from the app.
This is the one hard rule in this skill. Everything below respects it.
Where things live
| What | Path |
|---|---|
| Hotkeys and settings | $HOME/Library/Preferences/com.wearedevx.alter.plist |
| Actions, history, transcripts | $HOME/Library/Application Support/Alter/ |
| Application | /Applications/Alter.app |
Hotkeys are the only part of that plist this skill touches.
Hotkey encoding
Every binding is a JSON string under a KeyboardShortcuts_<action> key:
{"access": "systemGlobal", "carbonKeyCode": 15, "carbonModifiers": 768}
accessissystemGlobal(fires anywhere) orappLocal(only while Alter is focused). OnlysystemGlobalcan collide with other apps.carbonModifiersis a bitmask: cmd 256, shift 512, opt 2048, ctrl 4096. So 768 is cmd+shift.carbonKeyCodeis a Carbon virtual keycode, which is layout independent and not ASCII. The letters are scattered: A 0, S 1, D 2, F 3, H 4, G 5, Z 6, X 7, C 8, V 9, B 11, Q 12, W 13, E 14, R 15, Y 16, T 17, O 31, U 32, I 34, P 35, L 37, J 38, K 40, N 45, M 46, Space 49.
Custom actions use a key of the form
KeyboardShortcuts_user_action_<action-uuid>. The UUID maps to a record inside
Alter's database, which is off limits, so you cannot name the action from the
plist alone. Ask the user what an action does rather than going to look.
Audit hotkeys
scripts/hotkey-audit.py reads hotkey-shaped keys from Alter and other common
macOS hotkey owners, decodes them, and reports collisions. It never prints
non-hotkey keys. Alter appLocal bindings appear in the inventory so they can
be avoided when choosing a replacement, but only systemGlobal bindings enter
cross-owner collision groups.
python3 scripts/hotkey-audit.py # all owners, human readable
python3 scripts/hotkey-audit.py --json # machine readable
python3 scripts/hotkey-audit.py --strict # exit 1 when anything collides
Two apps binding the same chord is not a warning in macOS, it is a silent failure. Carbon hands the chord to whichever app registers it first, and the loser gets no error. Symptom: a shortcut that "just stopped working" after a reboot, with nothing in any log. If both apps launch at login, the winner can change between boots.
Change a hotkey
Prefer the GUI when the user is at the machine. Editing the plist is for scripted or repeatable setups.
In the app: Settings with cmd+, then Shortcuts, or the Action Editor
at cmd+shift+E for an individual action's binding.
By file, all four steps matter:
osascript -e 'quit app "Alter"'; sleep 3 # 1
# 2. read, assert the current value, then write. The assert is the guard
# against stomping a binding that already moved.
import plistlib, json, os
p = os.path.expanduser("~/Library/Preferences/com.wearedevx.alter.plist")
KEY = "KeyboardShortcuts_user_action_<action-uuid>"
d = plistlib.load(open(p, "rb"))
before = json.loads(d[KEY])
assert before["carbonKeyCode"] == 15 and before["carbonModifiers"] == 768, before
after = dict(before); after["carbonKeyCode"] = 2 # R to D
d[KEY] = json.dumps(after)
plistlib.dump(d, open(p, "wb"))
killall cfprefsd; sleep 1 # 3
open -a Alter # 4
Why each step, because skipping any one makes the edit look like it failed:
- A running app holds its preferences in memory and rewrites them on quit, discarding an external edit.
- Load, verify, write. Modify one key and leave every other key untouched, so transcript data in the same file is never re-encoded or read.
cfprefsdcaches preferences. Without this, macOS keeps serving the old value and can write its cache back over the file.- Carbon registers hotkeys at launch. Until Alter restarts it holds its old chord and not the new one.
defaults write <domain> <key> -string '<json>' also works for these values,
since each is a plain string. plistlib is preferred here only because it
supports the read-verify-write guard.
Resolving a collision
- Run the audit. Confirm the collision is real and both sides are
systemGlobal.--strictchecks only those cross-owner collisions. - Ask which app should own the chord. Do not guess, and do not go read Alter's database to work out what its action does.
- Move the loser to a free chord. Check the full audit output for what is
taken, including Alter's
appLocalchords. - Prefer a replacement that avoids Alter's own
appLocalchords too, so the new binding does not collide inside Alter. - Re-run the audit and confirm zero collisions.
Frequent competitors for cmd+shift chords: launchers such as Raycast or
Tinycast, capture tools such as CleanShot, and tiling daemons driven by skhd.
Alter's documented defaults include QuickHub at cmd+shift+Space, Hub at
cmd+shift+H, new chat at opt+Space, dictation on Fn, meeting capture at
cmd+shift+M, live captions at cmd+shift+down, and live notepad at
cmd+shift+right. The Action Editor is cmd+shift+E; the Settings shortcut
editor is under Settings → Shortcuts. Treat defaults as starting points and
audit the live machine, since users remap.
Sources
- Settings guide - shortcut editor, permissions, voice and meeting settings.
- Alter Actions - Action Editor, action context, triggers and x-callback-url automation.
- Meetings - recording, transcription and meeting workflows.
- Core features - AppSense, Follow Mode and native app integrations.
Config portability
Alter has no text config. Its bindings live in the plist, so a dotfiles repository cannot stow them, and a rebuilt machine comes back with Alter's defaults. When a user has deliberately moved an Alter chord to make room for another app, record that in whatever script provisions the other app, or the collision returns silently on the next rebuild.
