homebot

Your home, on every machine.

An old sepia photograph of the homebot family on the lawn in front of a Victorian house with a porch, garden urns and a lamp post. Back row, left to right: HAL 9000, a tall black monolith with a round glowing eye; Johnny 5, arms folded, on his treads; Rosie in a maid’s cap and apron, both hands resting on Neatpik’s head; Miss Minute, a smiling pocket-watch face; and Marvin, tall, gaunt and glum. Front row: R2-D2, Neatpik in the centre holding a clipboard, and WALL-E.
The homebot family, at home

homebot keeps your dotfiles, secrets and install lists in one git repo, puts them in place on any machine, and keeps one short list of what still needs you.

Read the docs Meet the family

Not released yet. There is nothing to install today. The docs describe how it works.

What it does

Your home repo is one folder in git, ~/.home. homebot reads it and puts this machine in order, then tells you what is left.

Tells you what still needs you

Type homebot and you get one short list: what is broken, what is waiting, what is new in your home folder. Every item ends with the exact command that fixes it.

homebot next does the first one for you. When a fix is yours to run, it shows you the command instead.

How the inbox works

$ homebot
homebot · laptop · 3 things need you (1 urgent)

  1  ! The commit guard is not installed
       → homebot setup
  2  • 1 file is in the way of links
       ~/.zshrc
       → homebot link
  3  • 2 new things to sort: track, ignore or snooze
       ~/.config/zed, ~/.config/ghostty
       → homebot triage

  Do the first one now: homebot next

Links your dotfiles

Everything in autolink/ is linked into $HOME, so editing the repo edits the live file. When a real file is in the way, homebot stops and says so. With --backup it moves the file aside, renamed. Nothing is deleted.

The linking rules

$ homebot link
  link    ~/.gitconfig
  link    ~/.tmux
  blocked ~/.zshrc  already exists with different content
2 changes, 0 already linked, 1 blocked
To move what is in the way aside (renamed *.homebot-backup-<time>, nothing is deleted):
  homebot link --backup

Seals your secrets

Files in private/ are linked like the rest, but git only ever sees them encrypted with age. Sealing needs only the public key, so it happens on its own before every commit. Unlocking asks for your passphrase once.

How secrets work

$ homebot pack --private ~/.netrc
packed ~/.netrc → private/common/netrc (sealed 1)
Commit it with:
  homebot save

Installs what each machine needs

A profile lists what a machine gets, in order: brew, apt and flatpak lists, fonts, your own scripts. A laptop and a server share a base and differ in the rest. --dry-run shows the steps before anything runs.

Profiles and packages

$ homebot unpack --dry-run
Would unpack workstation on laptop (linux): 7 steps
[1/7] unlock
[2/7] link
[3/7] brew linux/Brewfile
[4/7] apt-repos linux/apt-repos
[5/7] apt linux/apt.txt
[6/7] flatpak linux/flatpak.txt
[7/7] fonts OpenDyslexicNerd

Keeps going while you work

homebot save commits and pushes. Every hour a background helper seals secrets, records what you installed, pulls and repairs links, and with autosave on it commits and pushes too. When something needs you, a new shell tells you in one line.

The background helper

$ homebot save
committed 1 file
pushed 1 commit

# later, in a new shell
🚚 homebot: 1 thing needs you, run: homebot

Meet the family

homebot talks in one of eight voices. Neatpik is the default; the other seven are robots you may have met before. A voice changes the sentence and nothing else: the paths, commands and counts are the same in every voice, and commands are always shown as homebot ….

Pick one with homebot persona use and its name. If that name is free in your shell, you can type it instead of homebot.

Who’s talking? 
$ homebot
homebot · laptop · 3 things need you3 chores waiting, hon. Sleeves up.Ooh. 3 things. Found them for you.3 things need you. I'd fix them, but nobody ever asks.Dweet-bwoo-wee! [3 things need you]3 things need you! Already read them twice. Wonderful!I've noticed 3 things that need you. There's no need to worry.3 things need you, sugar, and the clock's a-tickin'! (1 urgent)

  1  ! The commit guard is not installed
       → homebot setup
  2  • 1 file is in the way of links
       ~/.zshrc
       → homebot link
  3  • 2 new things to sort: track, ignore or snooze
       ~/.config/zed, ~/.config/ghostty
       → homebot triage

  Do the first one now:Start with the first one, dear:First one... here:If you insist, start here:Bloo-wip! [the first one:]Ooh, ooh, start here:I suggest we begin with the first:Chop chop! First up: homebot next

Only the voiced sentences change. The items, paths and commands stay put.