Reference
Every tool the channel exposes, every state file, and the schedules that run without being asked.
Tools
| Tool | What it does |
|---|---|
reply | send a message: text or voice, with optional files, buttons, priority and topic |
react | put an emoji reaction on one of their messages |
edit_message | rewrite a message Otto already sent, with no new notification |
read_history | read the conversation back from the history log |
download_attachment | pull a photo, document or voice note into the local inbox |
brief | the rolling snapshot of the day |
recall | search the notes store and durable memories together |
remember | write a note or a durable memory |
forget | delete a durable memory |
consolidate_memory | force the nightly distillation pass out of band |
create_trigger | arm a cron or email trigger |
update_trigger | change an armed trigger |
delete_trigger | disarm one |
list_triggers | what is armed, and when each next fires |
snooze | hold non-urgent messages until a time |
proactivity_report | per source: sent, engaged, silent streak |
set_email_state | move 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
| File | Holds |
|---|---|
access.json | allowlist, quiet hours, voice policy, chunking |
triggers.json | armed triggers |
email-state.json | scan checkpoints |
notes.json | facts, loops, saved items, write log |
queue.json | held messages |
topics.json | what was said recently, per topic |
history.jsonl | both directions, with attribution |
runtime.json | session runtime state |
trips.json, airports.json | trips assembled from booking mail, and the airport zone table |
hygiene.json | what the loop-hygiene pass has already proposed or named, so nothing is asked twice |
recall-stats.json | recall hits and misses |
heartbeat.json | the server's liveness beat |
backup.key, backup-state.json | the 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
| When | What |
|---|---|
| every hour | email scan, suppressed during quiet hours |
| 08:57 | morning brief |
| 04:00 | memory consolidation |
| 05:00 or later | loop hygiene, once consolidation has finished for the day |
| 05:30 | encrypted backup of state and memory, then its restore drill |
| short cycle | brief rebuild, flight-day lifecycle events |
| on the hold lifting | queue flush, coalesced |
| every 5 min, own launchd job | the 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.