8.8 KiB
Hex transforms
Transforms are JavaScript or TypeScript functions that change dictated text before Hex pastes it. This page is written for coding agents; it is the whole API. Served at https://anoma.ly/hex/docs/transforms.
Where they live
- The config is
~/.config/hex/hex.config.ts(orhex.config.js; keep one). Runhex commands initto create it withhex.d.ts(types),AGENTS.md, andtsconfig.json. Typecheck withnpx -y -p typescript tscin that folder. - Hex runs it in an embedded JavaScript engine (QuickJS, ES2023 modules) and reloads it about a third of a second after a file in the folder changes. A config that fails to load keeps the previous one; the error shows in Hex.
- TypeScript works by erasing types. Enums, namespaces, constructor parameter
properties, and
import x = require()are rejected. - Imports:
@hex/commands,node:child_process,node:util, and files in the folder by relative path (./lib.ts,./data.json). No npm packages. Imports load with the config; dynamicimport()later is refused. - A transform runs only where the person selects it: Hex's Output pane lists
the steps, and
hex settings set dictation_processing.default_mode '<json>'(ordictation_processing.modes) chooses them by id.
Config shape
import { defineHexConfig } from "@hex/commands"
export default defineHexConfig({
transformations: {
"trim-whitespace": {
name: "Trim whitespace", // shown in Hex
description: "Remove leading and trailing whitespace",
timeout: 1000, // optional, milliseconds, 1 to 60000
transform: (text, context) => text.trim(),
},
},
})
transform(text, context) returns a string or a promise of one. context
describes the foreground app, each field present only when known:
{ application?: string, browserHost?: string, browserUrl?: string, windowTitle?: string, source?: 'dictation' | 'typed-text' }
source is "dictation" for spoken dictation and "typed-text" for Labs ›
Transform typed text (Linux), which runs the same steps on text already typed.
Selected transforms run in order after the mode's word replacements and
optional AI rewrite. Don't reuse the built-in ids lowercase,
spongebob-case, or no-trailing-punctuation.
What a script has
- Plain JavaScript built-ins,
console.log(to Hex's log),setTimeout,clearTimeout,queueMicrotask,AbortController,AbortSignal(abort,timeout,any), andDOMException. fetch,Headers, andResponse(below).node:child_process(exec,execFile) andnode:util(promisify).- No filesystem, environment,
process,require,setInterval,URL,TextEncoder,FormData,Blob, or streams. Read files with a program throughexecFileif you must. - 64 MiB of memory for the config.
fetch
The WHATWG shape, with a subset:
const response = await fetch(url, { method, headers, body, signal })
response.ok; response.status; response.statusText; response.url
response.headers.get(name); response.headers.has(name); [...response.headers.entries()]
await response.text(); await response.json(); await response.arrayBuffer()
urlis an absolutehttp:orhttps:URL. Redirects are followed.bodyis a string (JSON.stringify(...)for JSON); not allowed with GET or HEAD. A string body without acontent-typeheader getstext/plain;charset=UTF-8.headersis an object, an array of pairs, orHeaders.- The response is read whole before
fetchresolves (16 MiB at most); there is no streaming,FormData, orBlob. - HTTP error statuses resolve normally (
response.okis false). Network errors reject withTypeError: fetch failed: …; an abortedsignalrejects with its reason (AbortError, orTimeoutErrorforAbortSignal.timeout). - TLS uses the operating system's certificates.
Example, a local model through Ollama:
import { defineHexConfig } from "@hex/commands"
export default defineHexConfig({
transformations: {
"ollama-tidy": {
name: "Tidy with Ollama",
timeout: 20000,
transform: async (text) => {
const response = await fetch("http://localhost:11434/api/generate", {
method: "POST",
headers: { "content-type": "application/json" },
body: JSON.stringify({
model: "llama3.2",
prompt: `Fix punctuation and capitalization. Reply with the text only.\n\n${text}`,
stream: false,
}),
})
if (!response.ok) throw new Error(`Ollama answered ${response.status}`)
const data: { response: string } = await response.json()
return data.response.trim()
},
},
},
})
node:child_process
Node's exec and execFile, with callbacks and util.promisify:
import { exec, execFile } from "node:child_process"
import { promisify } from "node:util"
const run = promisify(execFile) // resolves { stdout, stderr }
const { stdout } = await run("pandoc", ["-t", "plain"], { input: text })
execFile(file, args, options, (error, stdout, stderr) => {})
exec(command, options, (error, stdout, stderr) => {})
execFile(file, args, options, callback)runs the program with an argument array and no shell. Use it for anything involving dictated text; never build a shell command out of the text.exec(command, options, callback)runs/bin/sh -c commandon macOS and Linux,cmd.exe /d /s /c "command"on Windows, as Node does.- Options:
cwd(default: the config folder),env(added to a minimal environment ofPATH,HOME, user, locale, and temp variables; Hex's own environment is not passed on; on macOSPATHalso has/opt/homebrew/binand/usr/local/bin),timeout(ms, then SIGTERM),maxBuffer(bytes per stream, default 1 MiB, at most 16 MiB),signal, and Hex's additioninput: a string written to stdin, which is then closed. Withoutinput, stdin is empty. stdoutandstderrare strings (UTF-8). There is noencoding,shell,uid,killSignal,spawn,fork, or sync variants.- Errors follow Node: a non-zero exit gives
Error: Command failed: <cmd>withcode(exit code),killed,signal, andcmd; a missing program givescode: "ENOENT"; atimeoutgiveskilled: true, signal: "SIGTERM"; too much output gives aRangeErrorwithcode: "ERR_CHILD_PROCESS_STDIO_MAXBUFFER"; an abortedsignalgives anAbortError. Promisified errors also carrystdoutandstderr. - The returned child has only
kill()(SIGTERM to the program and its children) andkilled; there is nopidor stream access.
Example, piping the text through a script:
import { defineHexConfig } from "@hex/commands"
import { execFile } from "node:child_process"
import { promisify } from "node:util"
const run = promisify(execFile)
export default defineHexConfig({
transformations: {
"house-style": {
name: "House style",
transform: async (text) => {
const { stdout } = await run("python3", ["./house_style.py"], { input: text })
return stdout.trimEnd()
},
},
},
})
Trust prompt
The first time a config uses fetch or node:child_process, Hex asks the
person in its Output pane, listing the hosts and programs it can see written
literally in the source (fetch("https://…"), execFile("pandoc", …)),
otherwise just the capability. The approval is pinned to a hash of every file
the config loaded: any edit asks again. Until it is allowed, fetch rejects
and exec/execFile call back with an error saying so, and the transform
falls back. A config can't approve itself; the approval is stored in Hex's
own data folder.
On a managed Mac, an organization can turn transforms off
(DisableTransforms) or keep fetch on this computer with no programs
(RestrictTransformsToLoopback); see https://anoma.ly/hex/docs/admin.
Timeouts, limits, and fallback
- Each transform has
timeoutmilliseconds: 1000 by default, 30000 when the config usesfetchornode:child_process, 60000 at most. That limit covers everything the transform waits for. - When a transform finishes or runs out of time, Hex abandons its requests and ends every program it started, with the program's children (a process group on macOS and Linux, a job object on Windows). Quitting Hex does the same. Fire-and-forget work does not outlive the transform.
- At most 8 requests and 4 programs run at once; more wait their turn.
- If a transform throws, returns something other than a string, or runs out of time, Hex pastes the text it had before the transforms and logs why. It never blocks dictation; the microphone keeps working while it waits.
- Input and output text are each limited to 48 KiB.
- Hex logs the host or program, status or exit code, duration, and byte counts, never the text, request or response bodies, arguments, or environment values.