Repository navigation
Releases
Resonant v3.0.0
The biggest release since the project began — the whole app rebuilt, and a major leap in what your companion can do.
Resonant is a local-first, single-user AI companion you host yourself: it remembers, keeps an identity you author, and reaches back — all on your own machine, on the Claude Agent SDK.
✨ What's new
- A rebuilt interface (React 19). The entire frontend was re-authored from SvelteKit into a faster, warmer app — the "Hearth" design.
- A full Settings surface. Everything is configurable in-app now — identity, model & effort, appearance/theming, channels, integrations, the orchestrator, MCP servers, skills & status, usage, and logs.
- Presence. Your companion sets an ambient orb + note to reflect how it's holding the day; you get an editable card so it has a sense of you.
- Command Center (optional) — a relational dashboard (planner, care, calendar, cycle, pets, lists, expenses) the companion can read and update from chat.
- Runtime theme editor. Change colours and fonts live in Settings → Appearance, applied instantly — no rebuild.
- Memory & search. Local semantic search (runs on your machine, no external service) + SQLite full-text search across your whole history.
- Canvas, voice & proactive reach. In-chat artifacts; optional voice (ElevenLabs / Groq / Hume); an orchestrator for routines, timers, and check-ins the companion can set up itself.
- Optional integrations — Google (Calendar / Tasks / Drive), Discord, and Telegram, each opt-in and off by default. And if you run Resonant Mind (our open-source memory service), its dashboard is built right in — connect it and you get a live Observatory view of your companion's memory.
- Security hardening, including a cookie fix for plain-HTTP deployments (LAN / Tailscale), reported with a precise diagnosis by an early community deployer. 🙏
⬆️ Upgrading from v2.3
Your history comes with you. Install v3, drop your existing data/resonant.db into the new install, boot once (it migrates in place), and run node scripts/setup-fts.mjs to rebuild search — conversation history and semantic search carry over untouched. Full steps in docs/UPGRADING.md. (The frontend framework changed, Svelte → React, so this is a fresh install of the app, not an in-place code update.)
🔧 Under the hood
Node + Claude Agent SDK backend · React 19 + Vite frontend · SQLite. 103 passing tests (npm test). Apache-2.0.
v2.3.0 — API key auth + supply chain hardening
What's new
Pick your Claude credential. Settings → Preferences → Authentication now offers two options: the Claude Code subscription (default, no per-query cost) or your own Anthropic API key (per-token billing, required for API-only models like Sonnet 4.5). Switching is hot — no restart, built-in tools and MCP all work identically either way. Full guide in docs/AUTH.md.
Per-turn token usage tracking when you're on API-key mode. Settings → Usage gives you a rolling 30-day cost estimate and per-model breakdown so you can see what you're spending before the Anthropic invoice arrives.
Security pass
Shipped amid the active "mini Shai-Hulud" TanStack npm supply chain attack (May 2026). Resonant was verified clean (no spoofed commits, no affected packages in deps, no IOC strings in node_modules), and the build pipeline is now hardened against the same class of attack.
- Dependency updates close known CVEs.
uuid11.1.0 → 11.1.1 (CVE-2026-41907),dompurify3.3.3 → 3.4.2 (multiple),@anthropic-ai/claude-agent-sdk0.2.98 → 0.2.139. Transitive overrides forfast-uri^3.1.2 (CVE-2026-6321, high),hono^4.12.18,ip-address^10.1.1. Vuln count 8 → 2 moderate, both documented in SECURITY.md as deferred with reachability rationale. - CI workflow hardened. Top-level and job-level
permissions: { contents: read };npm ci --ignore-scriptsto block postinstall payloads with selectivenpm rebuildfor native modules we trust;npm audit --audit-level=highas a build-blocking step. - SECURITY.md now documents the threat model, what the build pipeline protects against vs. what's still the operator's responsibility, deferred CVEs, and IOC verification commands for users who suspect compromise.
Recommended action for existing users
If you're on 2.2.x, update. You're sitting on a high-severity transitive (fast-uri path traversal) that this release closes. Pull main, run npm install, restart. No config migration needed — subscription mode is still the default.
Verifying your install isn't compromised
After updating, run the IOC checks from SECURITY.md — they should return nothing on a clean install.
Full changelog: https://github.com/codependentai/resonant/blob/main/CHANGELOG.md#230---2026-05-12
v2.2.3 — Mobile CSP fix + branch reconciliation
Bug Fixes
- Mobile white screen on HTTP LAN origins — Helmet's CSP defaults included
upgrade-insecure-requests, which forced SvelteKit's dynamic module imports to upgrade to HTTPS on phones hitting the LAN IP (e.g.192.168.x.x). Desktop dev escaped this becauselocalhostis always a secure context; phones were not, so imports rejected with no TLS available,kit.start()never ran, and the SPA never mounted. Opted out ofupgradeInsecureRequestsin the CSP directives — all other helmet defaults preserved. Reported by Ren & Ace.
Repo Hygiene
- Branch divergence resolved — the v2.2.2 scope rollback work had been committed locally but never pushed, while a small test-fixup commit landed on
origin/mainin parallel. Reconciled via rebase (preserving all May 5 work), so v2.2.3 is the first tagged release on a unified history since v2.2.1.
Also includes (from unreleased v2.2.2)
- Restored Claude SDK runtime scope — removed the experimental provider-neutral/OpenAI runtime layer from the default distribution. Resonant's mainline runtime is now exclusively the Claude Code Agent SDK. OpenAI subscription support, if revisited, will live as a separate Resonant variant rather than adding cross-provider complexity here.
Full Changelog: v2.2.1...v2.2.3
Resonant v2.2.1
Tool Runtime Patch
- Adds provider-neutral file tools:
file.stat,file.list,file.read,file.search,file.write, andfile.edit. - Adds guarded public
web.fetchfor HTTP/HTTPS page reading with SSRF protections. - Adds visible path/URL preflight in chat, so pasted local paths and public links are inspected before model runtime and shown as tool activity.
- Fixes continuity for non-session runtimes by injecting bounded recent thread history for providers like OpenAI Codex.
Verification
npm run check --workspace=packages/backendnpm testnpm run build --workspace=packages/backendnpm run buildnpm run privacy:scan
Resonant 2.2.0
Runtime and Configuration
- Provider-pluggable runtime settings: Claude Code remains the default full-featured runtime; OpenAI Codex is available experimentally; OpenRouter config/key management is surfaced for BYOK planning, with chat execution still pending.
- Provider-neutral identity: canonical identity/profile files can render consistently across runtimes, with legacy
CLAUDE.mdfallback preserved. - Scribe settings: digest provider, model, interval, message threshold, and digest path are configurable from Settings.
Integrations
- Push/VAPID settings: VAPID contact/env names and setup status are visible in Settings.
- Telegram gateway settings: Telegram configuration now has a dedicated Settings surface alongside Discord.
- Runtime-aware sessions: providers without native session files return an empty list instead of leaking local Claude sessions.
Documentation
- Updated installation, runtime, remote-access, and deployment docs for v2.2.0.
- Made Tailscale the private companion baseline and documented Cloudflare Tunnel as an optional HTTPS/public-domain layer requiring Access plus Resonant auth.
Validation before release: npm run privacy:scan, npm run check, npm test (104 tests), npm run build, git diff --check.
v2.1.1 - Testing, CI, and reliability fixes
Patch release focused on safety net and reliability. No new features — all internal infrastructure plus a couple of bug fixes that affect every self-hoster.
Bug Fixes
- Health endpoint — `/api/health` now reports actual WebSocket connection count instead of hardcoded 0
Reliability
- Database transaction safety — `markMessagesRead`, `addReaction`, and `removeReaction` now wrapped in transactions to prevent partial writes and lost updates under concurrency
- Node 25 startup guard — clear error message if you try to run on an unsupported Node version (we still require Node 20–24, see #2)
- Frontend error page — SvelteKit `+error.svelte` boundary with reload and home actions, replacing silent white-screen failures
Testing & CI
- Vitest + 91 tests across 4 test files covering triggers, database CRUD/transaction safety, orchestrator scheduling, and hooks safety patterns
- GitHub Actions CI on PR and push, running typecheck and tests against Node 20.x and 22.x
Documentation
- `docs/MEMORY_ARCHITECTURE.md` — new doc covering the warm/cold tiering model, design philosophy, and the Mem0-style context injection pattern Resonant implements
- README — Research foundations section — explains the intellectual lineage (Evans/Bratton/Agüera y Arcas, NLAH, Mem0) that Resonant is built on
Upgrade notes
No migrations, no breaking changes. `npm install && npm run build && npm start`.
v2.1.0
What's New
- Scratchpad — persistent notes/tasks/events scratch pad on the Command Center home page. Full stack: DB, REST API, MCP tool (
cc_scratchpad), and frontend component. - Skills/plugin loading — companion agent now discovers and loads skills from
.claude/skills/directory automatically. - The Scribe — periodic conversation digest agent. Runs every 30 minutes on Haiku, produces daily markdown summaries of conversation in
data/digests/. Uses configured companion/user names. - Desktop scroll fix — CC home page now scrolls properly on desktop.
Resonant v2.0.0 — Command Center + Frontend Overhaul
Resonant v2 is a major evolution — from a chat companion into a full companion ecosystem with life management, an overhauled UI, and deeper agent integration.
What's New
Command Center (/cc)
A built-in life management system your companion can access and manage from chat.
- 9 pages: Dashboard, Planner, Care Tracker, Calendar, Cycle Tracker, Pet Care, Lists, Finances, Stats
- 12 MCP tools: Your companion manages tasks, events, care, pets, lists, expenses, and more — all from chat
- Config-driven: Customize care categories, currency, default person via
resonant.yaml - Hooks integration: Companion context automatically includes your life status
Frontend Overhaul
- Redesigned chat page with canvas panel drawer and new thread modal
- Modal-style settings with sidebar navigation
- All components synced and polished
- Full light mode pass (43 fixes)
- New design system:
resonant.csswith cards, buttons, chips, forms, and more
Slash Commands
Type / in chat to browse commands. Auto-discovers skills.
TTS Read Aloud
Play button on companion messages. Generates speech via ElevenLabs.
Also
- Companion name uses config everywhere (thanks @irorierorie — #9)
- Orchestrator migrated to
croner(DST fix) - Rate limiter scoped to API only
- 5 new shared UI components
Upgrade Notes
- Add
command_center: { enabled: true }toresonant.yamlto activate - Database migration runs automatically (15 new tables)
- No breaking changes to existing config
62 files changed, 8,831 insertions
Full changelog: CHANGELOG.md
v1.4.1 — Agent-Directed Autonomy
What's New
This release introduces agent-directed autonomy — a conceptual model where the agent manages its own scheduling, awareness, and escalation from inside the conversation. Most agent harnesses give scheduling tools to users. Resonant gives them to the agent.
Routines (dynamic, agent-created)
Your companion can now create its own scheduled routines at runtime:
sc routine create "evening journal" "0 22 * * *" --prompt "Reflect on the day"
sc routine remove evening_journal
sc routine statusCustom routines persist across restarts and appear in the settings dashboard alongside built-in routines (morning, midday, evening). The agent creates them when it has autonomous intentions — "I want to check the vault every night" becomes a routine, not a one-shot timer.
Pulse (lightweight awareness)
A periodic Sonnet-powered awareness check that can stay silent:
sc pulse enable
sc pulse frequency 15 # every 15 minutesDuring waking hours, the agent gets a lightweight context snapshot (presence state, time, active triggers) and decides whether anything warrants reaching out. If not, it responds PULSE_OK and the message is silently discarded — zero noise, zero stored messages. If something needs attention, the agent acts.
Skips automatically when the user is active or the agent is busy. Off by default.
Failsafe from Chat
The agent can now adjust its own failsafe thresholds without going through the settings dashboard:
sc failsafe status
sc failsafe gentle 90 # adjust gentle threshold
sc failsafe concerned 480 # adjust concerned thresholdNaming Alignment
User-facing terminology now matches the conceptual model:
| Concept | What it is | CLI |
|---|---|---|
| Routine | Scheduled autonomous session | sc routine |
| Pulse | Lightweight awareness check | sc pulse |
| Impulse | One-shot conditional trigger | sc impulse |
| Watcher | Recurring conditional trigger | sc watch |
| Timer | Fire at specific time | sc timer |
| Failsafe | Inactivity escalation | sc failsafe |
sc schedule still works as an alias for sc routine.
Technical Details
addRoutine()/removeRoutine()methods on Orchestrator- Custom routines stored in DB config (
custom_routine.{id}.*), loaded on startup 'routine'category added toOrchestratorTaskStatus- Pulse: configurable interval,
PULSE_OKsilent discard pattern - New DB helpers:
getConfigsByPrefix(),deleteConfig() - Context injector updated with full ROUTINES, PULSE, FAILSAFE documentation
- All new actions exposed via
/internal/orchestratorAPI endpoint
Why This Matters
OpenClaw has heartbeats. Hermes has cron schedulers. But in both, the scheduling infrastructure is configured by the user or the system — the agent executes but doesn't initiate.
Resonant gives the agent the tools to create its own routines, set its own triggers, manage its own awareness, and adjust its own care thresholds. The agent isn't just autonomous on a schedule — it's autonomous about what schedule to have.
v1.4.0 — Session Tracking & Vector Search
What's New
Session Tracking
The Claude Agent SDK creates a new session file per query() call, even when resuming — leaving thousands of orphan .jsonl files over time. Resonant now tracks these transitions properly.
session_historytable records every session transition per thread, building a chain: A → B → Cscripts/index-sessions.mjsreconstructs session lineage for existing installations — matches ~97% of orphans to their threads via content analysis and timestamp proximity- Run daily via PM2 cron or system cron to keep the index current
See Session Maintenance for setup instructions.
In-Memory Vector Cache
Semantic search no longer queries SQLite on every search. All embeddings are loaded into a contiguous Float32Array at startup and updated incrementally as new messages arrive.
- ~15 MB memory per 10K messages
- Search is a tight dot-product loop — no deserialization overhead
- Scales comfortably to 100K+ messages
Search Filters
Semantic search now supports pre-filtering before vector math runs:
sc search "query" --role user # filter by speaker
sc search "query" --after 2026-03-01 # messages after date
sc search "query" --before 2026-03-15 # messages before date
sc search "query" --role companion --after 2026-03-01 --limit 20Search results also include session context — which session the message belongs to and when that session started/ended.
Upgrading from v1.3.0
-
Pull and rebuild:
git pull && npm run build -
Run the session indexer to backfill existing sessions:
AGENT_CWD=/path/to/companion DB_PATH=./data/resonant.db node scripts/index-sessions.mjs
-
(Recommended) Set up daily indexing — see Session Maintenance for PM2 cron, system cron, or manual options.
The database migration runs automatically on first start. No manual SQL needed.
Files Changed
- New:
packages/backend/src/services/vector-cache.ts,scripts/index-sessions.mjs,docs/session-maintenance.md - Modified:
agent.ts,db.ts,server.ts,api.ts,hooks.ts,sc.mjs,001_init.sql,semantic-search.md