Help her do more: build it with the brain¶
This page is for when you want your Anna to do something she can't yet: a new check, a new sense, a skill, a script, a change to how she works. The short version: don't go looking for a plugin. Talk to the brain and build it together.
She's built from modules¶
Anna is deliberately modular. Each part does one job, talks to the others through plain files and small commands, and can be added, swapped or left out on its own:
- The chat app is a channel plugin (Telegram by default; another app).
- Engines are separate subagents, one file each (
agents/). - Checks and senses are small scripts you drop into your record.
- Skills are Markdown procedures; the clock takes any dated task.
- Retrieval (merlin) is a separate server you can add or skip.
- The record is plain Markdown in git: every index over it is derived and rebuildable.
So "help her do more" is almost always "add or change one module", not "rewrite Anna". That keeps each feature small enough to build in a session and test on its own.
Why the brain¶
The bot is all of Anna: it's who you talk to day to day, on your phone. The brain is her logic center: a full Claude Code session with your record, your machines and the scaffold's code in reach. That's where features get built.
Buzzy
In the deployment Anna came from, the brain is called Buzzy, after the little pilot at the controls of the brain in Epcot's Cranium Command. Talking to the bot is talking to Anna; talking to the brain is talking to Buzzy. Name yours whatever you like.
Everything in this scaffold was built that way: someone said "I want her to…", and the brain and that person designed it, built it, tested it, and wrote it down.
How to reach the brain¶
- Attach to its screen session:
screen -r anna(detach with Ctrl-A, then D). See Your first day § brain or bot?. - Or, with
day.remote_control = true, from the Claude app on your phone or computer. - From the bot: ask for it, and the bot hands the request to the brain over the relay. That's fine for small things; for a real feature, sit down with the brain directly so you can go back and forth.
How a feature gets built¶
- Say what you want, in your words. "I want the porch light to come on when someone walks up the driveway at night." "I want a morning note if the backups didn't run." You don't need to know how; that's the brain's half.
- Design first. For anything bigger than a one-liner, the brain should tell you what it found (how things are set up now), propose how to do it, and ask the questions only you can answer (when, which one, what if it's already on). Decide those; the rest it can default and tell you.
- Build it, with the current state said out loud. Before it changes anything on a machine, it says what's there now. Changes go through the action gate: a change you asked for in so many words goes ahead; anything outward or irreversible waits for your yes.
- Test it. The brain checks the result live, adds a test if it changed code (
tests/run-all), and tells you what it couldn't test yet and how you'll know it works. - Write it down. A new procedure goes in a runbook, a fact about a machine in its host record, a lesson in memory, and the day's journal gets the commands and output (see The record's layout). That's what makes it hers: tomorrow's brain finds it in the record.
Where new pieces live¶
| You want… | It usually becomes… | Guide |
|---|---|---|
| her to verify something about your systems | a check | Write a check or a sense |
| her to feel something (load, heat, a service's health) | a sense | Write a check or a sense |
| the bot to be allowed to do something | a small wrapper script + one allowlist line | What the bot may do |
| a routine she runs at a time, or a follow-up later | a clock item (anna-clock add) |
Commands § anna-clock |
| a new way of working (a session ritual, a review) | a skill | Skills |
| a change to Anna herself | an edit to the scaffold's code in your clone | below |
Changing Anna herself¶
Your clone of the scaffold is yours to change. When you and the brain improve something generic (a fix, a better
check, a new engine), it belongs in the code: edit the clone, run tests/run-all, run ./install.sh, and commit.
If it would help everyone's Anna, offer it back upstream. Keep your own world out of it: no names, hosts or addresses
in the scaffold, only in your record (Coffee Logic).
After a git pull, your own changes and the upstream ones meet in git; Update after git pull covers
what to do if they collide.