Inbox & helper

Inbox & helper

homebot assumes you’ll forget. So it does everything that can’t lose data on
its own, and puts the rest in one short list, in your face, with the fix
attached.

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

  1  ! A commit was refused
       furniture/big.iso is 4.2 GB (limit 50 MB)
       → homebot save
  2  • 2 new things to sort: track, ignore or snooze
       ~/.config/zed, ~/.config/ghostty
       → homebot triage
  3  • Profile workstation changed since the last unpack
       → homebot unpack

  Done for you since you last looked: sealed 1 secret, committed 4 files, pushed 1 commit.
  Do the first one now: homebot next

Where it reaches you

Where What you see Cost
New shell 🚚 homebot: 3 things need you (1 urgent), run: homebot reads a cache file, no subprocess
Prompt HOMEBOT_COUNT (e.g. 3!), shown by Starship one read per prompt
Desktop notification when the set of urgent items changes, again daily while unresolved notify-send / osascript
homebot the full list

The shell refreshes the cache in the background when it’s older than 30 minutes.

What it watches

Urgent (!)
To do (•)
  • Git has no name or email for you, so commits fail (a new machine; listed
    before the refused commit it causes)
  • Signing is on but the key file (~/.ssh/id_rsa here) isn’t on this
    machine, so every commit fails. The fix shown turns signing off in
    ~/.config/git/config.local; homebot unlock brings the key back once it’s in
    private/
  • A commit was refused (guard reason attached)
  • An automatic chore failed (seal, export, autosave, sync, link)
  • Layout errors in the repo
  • Secret conflict (changed here and elsewhere)
  • gitleaks or age missing
  • Commit guard not installed
  • This machine and the remote both have new commits
  • The repo isn’t a git repository
  • Files in the way of links
  • A ~/.gitconfig that overrides the repo’s ~/.config/git/config (the fix
    moves it aside for homebot cleanup)
  • Backups that homebot link --backup moved aside (homebot cleanup)
  • Links not made yet
  • New things to triage
  • Secrets to unlock, or not sealed yet
  • Uncommitted changes, unpushed or unpulled commits
  • No remote / remote unreachable
  • Profile never unpacked here, or changed since
  • An export is failing
  • Background helper missing or stale
  • Keys not set up

The background helper

homebot setup installs it: a systemd user timer on Linux
(homebot-tidy.timer, 5 min after boot, then hourly), a launchd agent on
macOS (sh.homebot.tidy). Each run is homebot tidy --notify --quiet:

  1. Guard: reinstall the commit guard if core.hooksPath drifted.
  2. Seal: encrypt changed secrets.
  3. Export: refresh package snapshots due (about once a day).
  4. Autosave: commit tracked changes on the autosave.commit cadence (off / hourly / daily).
  5. Sync: pull (rebase), push if autosave.push.
  6. Link: fix links that are safe to fix (never moves your files).
  7. Refresh the inbox, notify if the urgent set changed.

Each step that fails becomes an urgent item; the rest still run. A lock file
stops two runs from overlapping.

What it never does

It never overwrites a real file, never commits a file git doesn’t already
track, other than sealed secrets and export snapshots (new files go through homebot triage; the one exception is the very
first commit of an empty repo), never decrypts (that needs your
passphrase) and never resolves a conflict for you.

Shell integration

Add this to your .zshrc:

eval "$(homebot shell zsh)"
Starship
Spaceship
[env_var.HOMEBOT_COUNT]
style = 'bold yellow'
format = """[🚚 $env_value ]\
($style)"""

Add homebot to SPACESHIP_PROMPT_ORDER.

State

Per machine, outside the repo:

Path Holds
$XDG_STATE_HOME/homebot links made, secret hashes, snoozes, journal, last tidy
$XDG_CACHE_HOME/homebot nudge and count for the shell
Previous Commands Next homebot.yml