Personas
Personas
A persona gives homebot a name, emoji, colours and alternate wording for some
messages. Neatpik is the default. Run homebot persona list to see the built-in
and local choices, with the active one marked. homebot persona show <id> shows
its header, colours and four sample messages.
A persona cannot change facts, paths, counts, commands, fixes or the commit
guard. Help, commit messages, the journal and anything stored in your home
repo keep their neutral wording. Ordinary piped command output also stays
neutral; persona show and persona preview deliberately display their named
voice even through a pipe. On a terminal, the active persona speaks where a
message allows it; the shell nudge and desktop notifications use that voice
even though they run in the background. The file format and checks explain what a
voice is allowed to change.
Choose a voice
From inside your home repo:
homebot persona use neatpik
homebot persona use none
use checks the choice and writes persona: in homebot.yml, preserving
comments. none selects the neutral voice, including for the nudge. The next
homebot save carries the config change; use does not make a commit.
HOMEBOT_PERSONA=<id> overrides persona: in the current process. An empty
value counts as unset. HOMEBOT_PERSONA=none selects neutral without changing
the repo. An unusable selection falls back to Neatpik; a broken selection from
homebot.yml also becomes an inbox item. An unusable environment selection
warns once on a terminal and makes no shared inbox item.
homebot --plain <command> or HOMEBOT_PLAIN=1 uses neutral wording for that
run, even in persona show and persona preview. NO_COLOR=1 removes colours
but keeps the chosen voice. HOMEBOT_THEME=light or dark chooses a palette;
it does not change the words. Giving homebot a command name
uses the separate homebot name command and name: key; a persona does not
create that name.
Write your own
homebot persona new tester
homebot persona validate tester
homebot persona preview tester
homebot persona preview tester --event inbox.nudge --all-variants
homebot persona ids
new creates $XDG_CONFIG_HOME/homebot/personas/tester.toml and will not
overwrite a file. --from <id> copies an existing persona’s header and lines
into the new file. Without --from, the scaffold lists voice message IDs as comments. ids
shows each voice ID, its English text and its placeholders. validate also
accepts a .toml path; preview shows light and dark output without sending
a notification or changing your repo.
Persona files live in each machine’s config directory. To take yours to
another machine, keep it in the home repo with homebot pack and let homebot
link it there. A machine that sees persona: tester before receiving
tester.toml speaks as Neatpik in the terminal, keeps the shell nudge, the prompt
symbol and desktop notifications neutral (the prompt shows 🚚), and shows a
persona_broken inbox item; run
homebot persona validate tester on that machine to inspect the problem.
Before adding persona: to a home repo shared with other machines, update
every machine that reads it to a homebot build from this release or later.
An older build rejects the new key, including when its background helper reads
the file. HOMEBOT_PERSONA set in one shell also affects the shared nudge and
symbol caches when a background refresh inherits that environment, so a shell
may show that voice after the setting is removed until the next refresh.