alter

Files (2)

• SKILL.md
• hotkey-audit.py · scripts/

SKILL.md (first lines)

# 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:

```json
{"access": "systemGlobal", "carbonKeyCode": 15, "carbonModifiers": 768}
```

- `access` is `systemGlobal` (fires anywhere) or `appLocal` (only while Alter is
  focused). **Only `systemGlobal` can collide with other apps.**
- `carbonModifiers` is a bitmask: cmd 256, shift 512, opt 2048, ctrl 4096. So
  768 is cmd+shift.
- `carbonKeyCode` is 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.

```sh
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:

```sh
osascript -e 'quit app "Alter"'; sleep 3      # 1
```

```python
# 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"))
```

```sh
killall cfprefsd; sleep 1                     # 3
open -a Alter                                 # 4
```

Why each step, because skipping any one makes the edit look like it failed:

1. A running app holds its preferences in memory and rewrites them on quit,
   discarding an external edit.
2. 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.
3. `cfprefsd` caches preferences. Without this, macOS keeps serving the old
   value and can write its cache back over the file.

From vanducng/skills, MIT.

More from vanducng/skills