Otto Docs

Reference

Every tool the channel exposes, every state file, and the schedules that run without being asked.

Tools

ToolWhat it does
replysend a message: text or voice, with optional files, buttons, priority and topic
reactput an emoji reaction on one of their messages
edit_messagerewrite a message Otto already sent, with no new notification
read_historyread the conversation back from the history log
download_attachmentpull a photo, document or voice note into the local inbox
briefthe rolling snapshot of the day
recallsearch the notes store and durable memories together
rememberwrite a note or a durable memory
forgetdelete a durable memory
consolidate_memoryforce the nightly distillation pass out of band
create_triggerarm a cron or email trigger
update_triggerchange an armed trigger
delete_triggerdisarm one
list_triggerswhat is armed, and when each next fires
snoozehold non-urgent messages until a time
proactivity_reportper source: sent, engaged, silent streak
set_email_statemove the email scan checkpoint

Send parameters worth knowing

priority is urgent or normal. Normal may be held; urgent never is.

topic is a stable slug naming what a message is about. Two proactive sends under one topic within a few hours collapse to the first unless the content materially changed. Omit it and the send is keyed by its trigger, which already catches the restart burst.

voice overrides the channel's default for one send. Omit it and the channel speaks whenever they last spoke.

Files

FileHolds
access.jsonallowlist, quiet hours, voice policy, chunking
triggers.jsonarmed triggers
email-state.jsonscan checkpoints
notes.jsonfacts, loops, saved items, write log
queue.jsonheld messages
topics.jsonwhat was said recently, per topic
history.jsonlboth directions, with attribution
runtime.jsonsession runtime state
trips.json, airports.jsontrips assembled from booking mail, and the airport zone table
hygiene.jsonwhat the loop-hygiene pass has already proposed or named, so nothing is asked twice
recall-stats.jsonrecall hits and misses
heartbeat.jsonthe server's liveness beat
backup.key, backup-state.jsonthe backup key, and how last night's backup went
digests/, inbox/composed digests, downloaded attachments

All of it is machine-local, mode 0600, written atomically. Durable memories are markdown under the Claude memory directories.

Schedules

WhenWhat
every houremail scan, suppressed during quiet hours
08:57morning brief
04:00memory consolidation
05:00 or laterloop hygiene, once consolidation has finished for the day
05:30encrypted backup of state and memory, then its restore drill
short cyclebrief rebuild, flight-day lifecycle events
on the hold liftingqueue flush, coalesced
every 5 min, own launchd jobthe dead-man liveness check, independent of the session

Conventions in the code

Decision logic is pure and tested; plumbing lives at the edges. Files are written to a temp path and renamed, so a crash mid-write cannot truncate state. A corrupt file is moved aside with a note on stderr, never deleted and never silently ignored. There are no external dependencies: Bun and the standard library only.

Tools added by the later waves

Beyond the core list above, the channel also exposes the substrate tools: delegate and jobs for background work, record_money and spending, record_trip and trips, note_contact and who, projects, body, forge, self_edit_check, self_test, watchdog_report, capability_log, revert_capability, memory_audit, loop_hygiene and otto_status.

Scheduler ticks cover the rest: the calendar poll, the nightly repo scan, the repetition miner, the watchdog probes, the flight-day lifecycle events, the loop escalation sweep and the nightly loop-hygiene pass.

Commands

/otto:status runs otto_status and shows its output as-is; if the session is down it falls back to bun otto/status.ts from the repo, which reads the same evidence and exits non-zero on anything DOWN.

On this page