Persona files

Persona files

Built-in personas ship with homebot. Your files go in $XDG_CONFIG_HOME/homebot/personas/<id>.toml (normally ~/.config/homebot/personas/<id>.toml). A local file with a built-in ID overrides that built-in. IDs are 1–32 ASCII characters: a lowercase letter followed by lowercase letters, digits or hyphens. none is reserved for turning the voice off. Run homebot persona ids for the current list of messages a persona may reword.

schema = 1
id = "tester" # optional; must match tester.toml
name = "Tester"
emoji = "🧪"
tagline = "A careful eye on the details"
extends = "neatpik" # optional; omitted means the embedded Neatpik
lang = "en" # optional

[colors]
accent = { light = "#31466B", dark = "#AFC4E9" }
ok = { light = "#245D38", dark = "#9DE0AF" }
muted = { light = 240, dark = 248 }

[lines]
"inbox.header.count" = ["{n:# thing needs|# things need} you."]

schema = 1, a name and one emoji are required. id is optional but, when present, must match the filename. The name is 1–32 characters. The tagline is one line of at most 100 characters and cannot contain $ or a backtick. lang is a BCP 47 language tag; English is the default. Colours may be #RRGGBB or ANSI indices 0–255. Each light/dark token omitted here is inherited from the parent. extends = "none" stops the chain at that file: the embedded Neatpik supplies nothing, so a colour the chain does not set stays the terminal’s own (persona show says terminal default for it), and a message with no line is said by the catalog’s English. Any other chain ends with the embedded Neatpik, then the catalog’s English. extends = "neatpik" is the default, so writing it is the same as omitting it: both mean the embedded copy, never a local neatpik.toml (that file only matters when you pick neatpik itself). Explicit parent chains may have at most four files, the persona included (the embedded Neatpik does not count), and cannot cycle. A [colors] that is not a table of accent, ok and muted, each with light and dark, makes the persona unusable. For each message ID, the first file in that chain with usable lines supplies all its variants.

File safety and checks

User files must be regular files of at most 256 KiB. A symlink is accepted only when it points to a regular file. Pipes, devices, sockets and folders are refused; reading cannot block the background helper on a pipe. Unknown TOML keys, invalid syntax, a bad header, an invalid ID or an invalid parent make the persona unusable. An invalid line variant is dropped; usable variants remain, and an ID with none falls through to its parent. homebot persona validate <id> loads the whole chain, as show and preview do, and prints every finding of every file in it to stderr. Each finding starts with the path of the file it is in, so a problem in a parent is not taken for one in the file you named. The path is relative to the config directory (personas/tester.toml) when the file is under it, and absolute otherwise. A missing or broken parent, a chain of more than four files and a cycle make the persona unusable, like a bad header in any of its files; invalid lines are reported as errors too, and validate exits with an error for them, although at load such a variant is only dropped (as said above). validate <file.toml> does the same for a file you have not installed yet, with the file as the first of the chain and the files it extends found by ID among the installed ones. With no argument it checks the persona in use; when that is none, there is no file to check and it says the neutral voice is selected. If homebot.yml cannot be loaded, the config error is reported as persona use reports it and the exit is 1; the persona named by HOMEBOT_PERSONA, if any, is still checked, and with none set there is nothing to check. Naming none is refused: it is reserved and has no file. Findings go to stderr, like every other warning and error of the CLI, so the stdout of show and preview is only what they print. homebot persona use <id> refuses a persona with any error in its chain, even a single bad line variant that would otherwise just be dropped, and homebot persona list marks such a persona [unusable] with its first error, the same verdict use and validate give: a persona is judged with the files it extends, so one under a broken parent, in a cycle or in a chain of five files is [unusable] too. When the error is in another file than the persona’s own, the reason starts with that file’s path, relative to the config directory when the file is under it. list still prints every persona when homebot.yml cannot be loaded, reports that error as use does, exits 1 and marks none as current.

Line IDs must be in homebot persona ids and marked for voice. A variant must parse, preserve required and fixed placeholders, plural counts (a count the English shows must still be shown, as a bare {n} or in a plural form with #: {n} {n:step|steps} and {n:# step|# steps} both show it, {n:step|steps} alone hides it), leading/trailing whitespace, a leading {name}: prefix, a leading ,, ; or (, placeholders that touch in the English ({a}{b}) still touching, punctuation that protects an appended command, and the original number of line breaks. An empty list of variants is an error too. The validator rejects control and format characters, including terminal escapes and bidi controls. In a line, it allows only the same newlines as the English; the emoji field alone may contain the joiner and variation marks needed for one emoji. It warns about low colour contrast, uncertain emoji width, duplicate or long variants, non-English language tags and possible added facts. A variant beyond the hard length limit is rejected. Run homebot persona preview <id> to see the voice in both themes, or add --event <message-id> and --all-variants to inspect individual lines. A slot the inbox fills with another message or a count is filled the same way (3 things need you (1 urgent)); any other slot shows a generic sample such as <profile>.

What is voiced

A persona words what homebot prints, not what it stores. The reasons homebot link gives for a link it will not make (a name that breaks the layout rules, something in the way in $HOME) are in the persona’s voice when printed, in link, link --dry-run, the inbox item and the error of the link unpack action. They are English, whatever the persona, in anything homebot stores, and when stdout is piped or --plain is set.

Selection and rotation

HOMEBOT_PERSONA (when nonempty) wins over persona: in homebot.yml; the default is Neatpik. none selects the neutral voice. A missing or unusable choice falls back to the embedded Neatpik, even if a broken local neatpik.toml shadows the built-in. A configured failure raises persona_broken in the inbox; a failing environment override warns once on a terminal. The neutral English is used when a message has no usable variant.

For each message ID, homebot picks one variant per process and tries not to repeat the previous process’s choice. Previous picks are stored per machine in $XDG_CACHE_HOME/homebot/voice.json; a cache read or write failure only changes the pick. The main nudge line uses a stable pick keyed on the inbox items; notifications and the nudge’s urgent suffix always use the same variant for a persona. Neither changes wording on every refresh. This state stays outside the home repo.

Generated file fields and voice IDs

These tables come from the accepted persona fields and the message catalog. They are updated by go run ./tools/gendocs docs.

Fields

Voice IDs