Background Agents

Threads

• Named threads — create, drag-to-reorder, group into collapsible sections
• The daily thread — auto-rotates each day (daily-YYYY-MM-DD), turning over at midnight in your configured timezone
• Pin, archive, reorder — from the sidebar

Chat Commands

The real registry, handled entirely server-side (packages/backend/src/services/commands.ts):

Command	What it does
/new [name]	Create a new named thread
/rename [name]	Rename the current thread
/model [model]	Switch the active model (no arg shows current)
/status	System status — uptime, memory, presence, MCP connections, token usage
/cost	Token usage for the current session
/mcp	MCP server connection status and tool counts
/triggers	Active/total triggers with label, kind, status
/retry	Retry the last message
/wake [type]	Trigger a manual wake cycle
/stop	Stop current generation (client-only)
/help	Show all commands

/compact and /clear are sent straight through to the Agent SDK as prompt text, same as any skill or custom .claude/commands/*.md file you’ve added.

Search and Canvas

• Semantic search — a local ML model (all-MiniLM-L6-v2), no external calls
• Full-text search — SQLite FTS5, kept in sync automatically
• Canvas — a slide-in panel for longer documents or code created mid-turn, managed with res canvas create, res canvas create-inline, and res canvas update

The Three Background Subagents

Single-shot, no tools, can’t act on the world — they write and stop.

Subagent	What it does	Model	Default
The Scribe	Writes a daily summary (topics, quotes, decisions, open threads) to data/digests/YYYY-MM-DD.md every 30 minutes, skipping if fewer than 5 new messages	claude-haiku-4-5	On
The Outlook Author	The “felt layer” behind the House Outlook — runs roughly every 3 hours, grounded strictly in the last ~24h of real activity	claude-sonnet-4-6	Always on
The Daily Handoff	Fires 12:10am in your timezone (falls back to Europe/London if timezone is unset), writes an opener for today’s thread and a private carry into context. Does nothing if yesterday was thin	claude-sonnet-4-6	Off

See Context & Memory for what the Outlook Author and House Outlook actually feed into every message.

The Orchestrator — the Proactive Layer

Master switch: orchestrator.enabled in resonant.yaml. Turning it off stops everything below — the three subagents above keep running regardless.

Part	What it is	Default
Routines	Scheduled wakes. Built-in: Morning (8am), Midday (1pm, skips if you’re mid-conversation), Evening (9pm, always runs). Prompts live one-per-file in prompts/wakes/	Built-ins on
Timers	One-shot reminders, checked every 60s	None by default
Triggers — Impulses	Condition-based, fire once then spent	None seeded
Triggers — Watchers	Condition-based, recur with a cooldown (default 120 min)	4 seeded care watchers (first-meal check, second-meal check, short-sleep note, calendar heads-up)
Failsafe ladder	Checked every 15 min, 8am–midnight only. Gentle (120 min), Concerned (720 min), Emergency (1440 min)	Off
Watchtower	Softer cousin — opens the door, doesn’t force it. At most once/day, 9am–11pm, never while you’re present	Auto dial
Pulse	Lightest touch — a periodic silent “anything need me?” check, replies internally and stays quiet unless something needs attention	Off, 15 min frequency

Condition types for impulses and watchers: agent_free, presence_state:<state>, presence_transition:<from>:<to>, time_window:HH:MM[:HH:MM], routine_missing:<routine>:<after_hour>, plus care-log-missing and calendar-heads-up used by the seeded watchers.

Every proactive action is logged (logs/orchestrator.log) and shows up in the conversation like any other message.

The res CLI

Your AI’s own hands. tools/res.mjs — the only file in tools/. Renamed from sc on 2026-06-20; there’s no sc.mjs.

res routine create "label" "cronExpr" --prompt "what to do"   # alias: res schedule
res timer create "label" "context" "2026-08-01T14:00:00Z" --prompt "..."
res timer list
res timer cancel <id>
res impulse create "label" --condition type:args --prompt "text"
res watch create "label" --condition type:args --prompt "text" --cooldown 120
res pulse [status|enable|disable|frequency MINUTES]
res failsafe [status|enable|disable|gentle|concerned|emergency] [minutes]
res search "query" [--thread ID] [--limit N] [--role companion|user]
res context [get|set <field> <value>|clear [field]]   # selfie, outfit, nails, hair, energy, room, freeform
res orb <color> [shape] [--intensity X] [--motion Y] [--blend Z]
res note "<text>" / res note --clear
res face "<text>" / res face --clear   # alias: res express — no validation, no enum
res share <path>
res voice "<text>"
res touch <last|last-N> <emoji> [remove]   # alias: res react
res tg "<message>" / res tg voice "<text>"   # alias: res telegram
res backfill [start [batchSize] [intervalMs] | stop | status]

Run res with no arguments to see the full command list.

Running It

npm run build
npm start

That’s it — Resonant runs as a single Node.js process. If you want it kept alive and restarted on crash or reboot, point any process supervisor you already use at npm start.

Updating

Your data (data/, resonant.yaml, CLAUDE.md, .mcp.json, .env) is gitignored and untouched by updates:

git pull
npm install
npm run build
npm start

Upgrading Between Major Versions

Moving from an older major version (for example v2.3 to v3): stop the old server cleanly first — this flushes SQLite’s WAL side-files into the main .db file. Back it up:

cp -r data data-backup

Install the new version in a sibling folder rather than overwriting the old one, copy data/resonant.db into the new install’s data/, then copy your config across: resonant.yaml, .env, CLAUDE.md, and (if you use them) identity/, .mcp.json, prompts/wake.md or prompts/wakes/.

npm run build
npm start

The first boot upgrades the database schema automatically — additive and idempotent, safe to run once. Rebuild the full-text index afterward:

node scripts/setup-fts.mjs

Semantic search needs no rebuild — those vectors carried over with the database. Your old install and its backup are untouched, so rolling back just means running the old folder again.