hex/docs/plans/personal-commands.md
Dax 82ca73f945
reload personal config when imported .js files change (#1856)
* 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.
2026-11-15 10:46:47 -05:00

176 lines
7 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

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