mirror of
https://github.com/anomalyco/hex.git
synced 2026-11-22 21:23:02 +01:00
* reload personal config when imported .js files change * watch and load the same config file kinds the watcher skipped foo.d.js, foo.d.mjs, and foo.d.json because it treated every .d stem as a declaration file, while the loader ran any file imported by its exact name as javascript even though edits to it never reloaded. both now use one predicate: ts, js, mjs, mts, and json in any case, excluding only .d.ts and .d.mts declarations. the loader refuses other extensions when a config imports them.
176 lines
7 KiB
Markdown
176 lines
7 KiB
Markdown
# Personal Commands
|
||
|
||
**Status:** Personal commands, typed capture descriptors, dictation control
|
||
phrases, and text transformations are implemented on macOS; Windows and Linux
|
||
use the transformations. This document records the shipped contract. Hex runs
|
||
configs in embedded QuickJS ([quickjs.md](quickjs.md)).
|
||
|
||
## What Users Can Configure
|
||
|
||
Personal commands live in `~/.config/hex/hex.config.ts` (or `hex.config.js`).
|
||
The config defines
|
||
ordinary commands, capture descriptors, named text transformations, and optional
|
||
dictation control phrases. Rust validates and matches the grammar and retains
|
||
wake, sleep, cancellation, and dictation lifecycle behavior. Meeting lifecycle
|
||
commands are native and developer-only.
|
||
|
||
Spoken commands and dictation control phrases require the persisted Commands
|
||
opt-in, which defaults off. Creating a config does not enable it. Selected mode
|
||
transformations can run with Commands off; hotkey dictation does not require
|
||
voice commands.
|
||
|
||
```ts
|
||
import { defineHexConfig, openUrl } from "@hex/commands"
|
||
|
||
export default defineHexConfig({
|
||
commands: {
|
||
"open-training": {
|
||
phrases: ["open training"],
|
||
group: "Websites",
|
||
description: "Open the training site",
|
||
action: openUrl("https://example.com/training"),
|
||
},
|
||
},
|
||
})
|
||
```
|
||
|
||
Command keys are stable IDs. A command may be global or match one exact
|
||
application or browser host. Browser-host context currently comes from Brave
|
||
Browser. More-specific commands may specialize ordinary global commands;
|
||
commands that can coexist at equal specificity may not share a phrase.
|
||
|
||
Available actions are `openUrl`, `openApplication`, `openPath`, `press`, and
|
||
`typeText`. A handler returns an action, a list of actions, or nothing, and may
|
||
also queue actions through its `hex` argument; Hex validates them all and runs
|
||
them in order after the handler returns. Handlers are plain TypeScript or
|
||
JavaScript and may import other files in the config folder, but not npm
|
||
packages, Effect, or Node APIs.
|
||
|
||
Commands may use a trailing `{name}` placeholder for normalized text, or a
|
||
`captures` schema built with `digit`, `letter`, `choice`, `union`, and trailing
|
||
`text`. Schema-bearing commands bind every declared capture exactly once in
|
||
every phrase alias and require a `run` handler. Rust matches these commands
|
||
only on completed command transcripts, not partial updates.
|
||
|
||
`openUrl` accepts absolute web URLs and app deep links, for example
|
||
`openUrl("slack://channel?team=T_EXAMPLE&id=C_EXAMPLE")`. The URL is passed
|
||
unchanged to macOS, which requires an installed handler for its scheme. Use
|
||
`openApplication("Slack")` to launch an app by name or path, not to navigate a
|
||
deep link. The API spelling is `openUrl`, not `openURL`. File URLs and inline
|
||
script/data URLs remain unsupported; use `openPath` for filesystem paths.
|
||
|
||
## Dictation Transformations
|
||
|
||
The config may register named string transformations. Select them in a mode's
|
||
Transformations section to run them in displayed order after that mode's
|
||
corrections and optional OpenCode rewrite. This pipeline applies to Paste and
|
||
Send, not Voice Action or meetings. If the transformation stage fails, Hex
|
||
keeps the text from before that stage, not partially transformed output.
|
||
Each transformation receives the focused app's context and `source`:
|
||
`"dictation"` for spoken dictation, or `"typed-text"` for Labs › Transform
|
||
typed text, which runs the same mode steps on text already in the field.
|
||
`source` is absent from command-handler context.
|
||
|
||
```ts
|
||
import { defineHexConfig } from "@hex/commands"
|
||
|
||
export default defineHexConfig({
|
||
transformations: {
|
||
"trim-whitespace": {
|
||
name: "Trim whitespace",
|
||
description: "Remove leading and trailing whitespace",
|
||
transform: (text) => text.trim(),
|
||
},
|
||
},
|
||
commands: {},
|
||
})
|
||
```
|
||
|
||
Do not reuse the built-in transformation IDs `lowercase`, `spongebob-case`, or
|
||
`no-trailing-punctuation`; those IDs execute Rust's built-ins rather than a
|
||
registered script function.
|
||
|
||
Each dictation selects one complete mode. The required Global mode applies
|
||
unless a more specific application or browser-host mode matches. A mode owns
|
||
its corrections, optional AI rewrite, and selected custom transformations;
|
||
contextual modes do not inherit hidden processing from Global.
|
||
|
||
## Trust Boundary
|
||
|
||
The config runs inside Hex's process in QuickJS with no filesystem, network,
|
||
environment, process, or timer API, and imports only `@hex/commands` and files
|
||
in the config folder. What it can do is limited to the actions it returns,
|
||
which run with the user's permissions, so review agent changes before enabling
|
||
commands. Each call has a one-second limit and the engine a 64 MiB limit.
|
||
|
||
Invalid config never replaces the last valid registry. Rust validates schema,
|
||
stable IDs, protected phrases, context predicates, and overlaps before
|
||
activation. Dictation remains available when the config fails.
|
||
|
||
## Dictation Control Phrases
|
||
|
||
The optional `dictation` section replaces the native voice-dictation phrases,
|
||
not the native capture lifecycle:
|
||
|
||
```ts
|
||
import { defineHexConfig } from "@hex/commands"
|
||
|
||
export default defineHexConfig({
|
||
dictation: {
|
||
start: ["begin note"],
|
||
stop: ["finish note"],
|
||
send: ["send note"],
|
||
cancel: ["discard note"],
|
||
},
|
||
commands: {},
|
||
})
|
||
```
|
||
|
||
`start` matches an utterance prefix while Hex listens. `stop`, `send`, and
|
||
`cancel` match suffixes during active voice dictation. Each list must contain at
|
||
least one phrase. Omitting the section uses the native protocol.
|
||
|
||
## Workspace
|
||
|
||
Choose Create Config in the Commands pane, Set up in Modes' Transformations, or
|
||
run:
|
||
|
||
```sh
|
||
hex commands init
|
||
```
|
||
|
||
```text
|
||
~/.config/hex/
|
||
├── hex.config.ts the user's; created only when no config exists
|
||
├── hex.d.ts types for @hex/commands; Hex rewrites it when it changes
|
||
├── AGENTS.md agent notes; Hex rewrites it when it changes
|
||
└── tsconfig.json created only when missing, for editors and `tsc`
|
||
```
|
||
|
||
Nothing is installed. Folders from the Bun era keep working once their config
|
||
avoids Effect and npm packages; their `package.json`, `bun.lock`,
|
||
`node_modules`, `.hex-sdk`, and `.agents` can be deleted.
|
||
|
||
Hex reloads the config about a third of a second after any `.ts`, `.js`,
|
||
`.mjs`, `.mts`, or `.json` file in the folder changes, in any case, but not
|
||
declaration files (`.d.ts`, `.d.mts`), `node_modules`, `.git`, or symlink
|
||
targets. It activates valid changes and reports the last load error with its
|
||
file, line, and column in Modes' Transformations section. `hex commands check`
|
||
(macOS) loads the config as Hex would and prints what it registers or why it
|
||
fails. Type checking is optional: `npx -y -p typescript tsc` in the folder.
|
||
|
||
## Runtime Boundary
|
||
|
||
```text
|
||
hex.config.ts -> type erasure -> QuickJS on one worker thread -> registration
|
||
-> native Rust resolver -> handler call -> actions -> native executor
|
||
```
|
||
|
||
The script engine never runs in the partial-transcript recognition path.
|
||
Request queues, actions per call, and status files are bounded. A failed load
|
||
preserves native commands and the last valid runtime snapshot.
|
||
|
||
## Remaining Work
|
||
|
||
- Add listing, reload, and log inspection to the CLI when the Commands pane
|
||
is insufficient.
|