Otto Docs

Is it still up?

The status report, the nightly backup, the doc-drift sentinel, the dead-man supervisor, and the watchdog's repair log.

A dead calendar source looks exactly like an empty calendar. Both read as "nothing today," and the second one is right most of the time, so nothing ever looks wrong until you find out at a meeting you missed. This is the part that answers "is it actually working" with evidence instead of a guess.

Status, one screen

otto_status (and /otto:status over Telegram) reports one row per moving part — this server, the trigger engine, the Telegram poller, the email scan, the webhook listener, the phone relay, the voice daemon, gog auth, the claude.ai connectors — each stamped with the time of its own evidence rather than the time of the check, and a plain verdict: UP, DEGRADED, DOWN, off when a part is simply not configured, or unknown when there is no evidence yet. The connectors row cannot be probed directly, so it is inferred from whether the brief's calendar and inbox sections are still rendering, and it says so.

When the session itself is down — exactly when this matters most — bun otto/status.ts reads the same files and pokes the same loopback ports from a terminal, and exits non-zero if anything is DOWN.

Nightly backup

Every loop, trigger, receipt and memory Otto holds lives in ~/.otto/state and the memory markdown under ~/.claude, and nobody versions either. So every night at 05:30, half an hour after the hygiene pass, Otto packs both into one archive with a SHA-256 hash for every file, encrypts it with AES-256-GCM and keeps the newest 14 in ~/.otto/backups.

Then it runs the restore drill on the archive it just made: decrypt it into a temporary folder, check every hash, check that every .json file still parses, and delete the folder. The outcome is the "Nightly backup" row in otto_status. One failed night shows up only there. Three in a row send you a message.

The key is 32 random bytes in ~/.otto/state/backup.key, created on the first run and readable only by you. It is never logged and never packed into an archive. Copy it somewhere off the Mac by hand: without it, every archive is unreadable.

bun otto/backup.ts list
bun otto/backup.ts verify <file>
bun otto/backup.ts restore <file> <folder>

restore only extracts into the folder you give it, and refuses one that overlaps the live state or memory. Putting files back is your decision, made after you've looked at what came out. To keep archives somewhere else, or more of them, set backup.dir and backup.keep in access.json.

Doc-drift sentinel

CLAUDE.md, AGENTS.md, the README, every skill, and the plugin's own instructions block all name tools, state files and /otto: commands. A rename that doesn't touch every one of those leaves a stale name behind, and prose cannot be type-checked. The doc-drift check reads every one of those surfaces and fails when a name in them doesn't resolve against the code: a tool that appears nowhere, a state file nothing refers to, a /otto: command with no matching skill. It runs inside bun test, so it fails the same way a broken type would.

Dead-man supervisor

Everything else that watches Otto runs inside the process it is watching, so when that process is wedged or gone, all of them go quiet together — and quiet looks exactly like a good day. The server writes a small heartbeat file every 30 seconds, and a second, independent checker — installed by hand as its own launchd job, sharing no code with the server beyond reading that file — notices when it stops changing. It alerts once per outage, over Telegram directly since the channel itself is what's down, and files a loop note so the outage is still in the brief once the session is back. A stale reading needs a second, later check before it counts, so a short sleep never trips it.

Watchdog repair log

The capability watchdog's repairs are restricted to an explicit allowlist — restarting the session, killing a stale voice daemon, freeing a held webhook port — checked against the exact command before it runs, never against whatever the watchdog happens to construct. Nothing that names access.json, .env or any other config file is ever eligible. Every attempt, successful or not, is written to the capability log before it runs, since some of these repairs restart the very process that would otherwise log them afterward.

On this page