* 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.
7 KiB
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).
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.
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.
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:
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:
hex commands init
~/.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
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.