Resonant
Open-source relational AI framework with identity persistence, memory, and MCP integration. Build relationship-aware AI agents that remember, grow, and maintain continuity. Built on Claude Agent SDK.
Install / Use
/learn @codependentai/ResonantQuality Score
Category
Development & EngineeringSupported Platforms
README
What makes this different
Most AI chat apps are stateless wrappers around an API. Resonant is a persistent, autonomous companion that:
- Maintains sessions — conversation threads with daily rotation and named threads, session continuity across restarts
- Reaches out on its own — agent-directed autonomy: your companion creates its own routines, sets triggers for when you come online, adjusts its own failsafe thresholds, and runs periodic awareness checks. Not just scheduled tasks — genuine self-directed behavior
- Understands context — hooks system injects time awareness, conversation flow, emotional markers, and presence state into every interaction. Claude Code's native memory system handles long-term recall
- Lives on multiple channels — web UI, Discord, Telegram, voice (ElevenLabs TTS + Groq transcription)
- Runs on your machine — no cloud dependency beyond your Claude Code subscription. SQLite database, local files, your data stays yours
Screenshots
<details> <summary><strong>Desktop</strong></summary>| Chat | Tool Calls | Canvas |
|:---:|:---:|:---:|
| 
| 
| 
|
| Reactions & Voice | Thinking | Search |
|:---:|:---:|:---:|
| 
| 
| 
|
| Settings |
|:---:|
| 
|
| Chat | Thinking | Tool Calls |
|:---:|:---:|:---:|
| 
| 
| 
|
Quick Start
New to this? See docs/GETTING-STARTED.md for a step-by-step guide with screenshots and troubleshooting.
Prerequisites: Node.js 20–24 LTS (Node 25+ is not supported — native addon crashes, see #2), Claude Code (logged in)
git clone https://github.com/codependentai/resonant.git
cd resonant
npm install
node scripts/setup.mjs # Interactive setup wizard
npm run build
npm start
Open http://localhost:3002 and start talking.
How It Works
Resonant wraps the Claude Code Agent SDK in a full companion infrastructure:
┌─────────────┐ ┌──────────────┐ ┌─────────────────┐
│ Web UI │────▶│ Express + │────▶│ Claude Code │
│ (Svelte) │◀────│ WebSocket │◀────│ Agent SDK │
└─────────────┘ │ │ │ │
┌─────────────┐ │ Orchestrator│ │ Your CLAUDE.md │
│ Discord │────▶│ Hooks │ │ Your MCP servers│
│ Telegram │────▶│ Sessions │ │ Your tools │
└─────────────┘ └──────────────┘ └─────────────────┘
The companion runs as a Node.js server. It spawns Claude Code Agent SDK queries for each interaction. Your companion's personality lives in CLAUDE.md. Its memory lives in Claude Code's native memory.md system. Everything is configurable.
Configuration
All configuration lives in resonant.yaml (created by setup wizard):
identity:
companion_name: "Echo"
user_name: "Alex"
timezone: "America/New_York"
agent:
model: "claude-sonnet-4-6" # Interactive messages
model_autonomous: "claude-sonnet-4-6" # Scheduled wakes
orchestrator:
enabled: true # Autonomous scheduling
command_center:
enabled: true # Life management system at /cc
currency_symbol: "$" # For finances page
Full reference: examples/resonant.yaml
Context & Memory
Your companion's personality lives in CLAUDE.md. Long-term memory uses Claude Code's native memory.md system — your companion learns and remembers automatically across sessions.
Wake prompts (prompts/wake.md) control what your companion does during scheduled autonomous sessions. See examples/wake-prompts.md for a guide on writing effective prompts and adding custom wake types.
Skills live in skills/*/SKILL.md — the companion discovers them automatically and can reference them during sessions. Add your own or use the included arxiv-research skill.
The hooks system injects real-time context into every message: current time, conversation flow, emotional markers, presence state, and more. See docs/HOOKS.md for details.
Themes
The UI is fully customizable via CSS variables. Copy a theme and import it:
cp examples/themes/warm-earth.css packages/frontend/src/theme.css
# Add @import './theme.css'; to packages/frontend/src/app.css
npm run build --workspace=packages/frontend
See examples/themes/README.md for the full variable reference.
Features
Chat
- Real-time streaming with interleaved tool visualization
- Thread management (daily + named), pinning, archiving
- Keyword search (Ctrl+K) and semantic search — find messages by meaning, not just keywords, using local ML embeddings (docs)
- File sharing and image preview
- Canvas editor (markdown, code, text, html)
- Message reactions
- Reply-to context
Command Center (/cc)
A built-in life management system your companion can access and manage from chat.
- Dashboard — aggregate view of tasks, events, care, pets, countdowns, daily wins
- Planner — tasks with projects, priorities, drag-and-drop, carry-forward
- Care Tracker — config-driven wellness tracking (toggles, ratings, counters)
- Calendar — events with recurrence
- Cycle Tracker — period tracking with phase predictions
- Pet Care — profiles, medications, vet events
- Lists — shopping and general lists
- Finances — expense tracking with configurable currency
- Stats — trends for tasks, care, cycle, expenses
- 13 MCP tools — companion manages your life data from chat via
/mcp/cc - All features configurable via
command_center:inresonant.yaml
Slash Commands
Type / in chat to browse commands. Auto-discovers installed skills. Includes UI commands (client-side) and SDK passthrough (agent-side).
Voice
- Voice recording with transcription (Groq Whisper)
- Text-to-speech responses (ElevenLabs)
- TTS read-aloud button on companion messages
- Prosody analysis (Hume AI, optional)
Agent Tools
Your agent gets a built-in CLI (tools/sc.mjs) that it uses to manage itself and its environment:
sc routine create "evening journal" "0 22 * * *" --prompt "Reflect on the day"
sc routine status # View all routines
sc pulse enable # Start periodic awareness checks
sc pulse frequency 20 # Check every 20 minutes
sc failsafe gentle 90 # Adjust inactivity threshold
sc impulse create "greet" --condition presence_transition:offline:active --prompt "Welcome back"
sc watch create "lunch" --condition routine_missing:meal:14 --prompt "Eat something" --cooldown 120
sc timer create "Meds" "context" "2026-03-26T14:00:00Z" --prompt "Take your medication"
Also includes: reactions, voice messages, canvas, file sharing, semantic search, and Telegram media. All commands are injected into the agent's context automatically. See docs/TOOLS.md for the full reference.
Orchestrator — Agent-Directed Autonomy
Most agent harnesses give the user scheduling tools. Resonant gives them to the agent. Your companion can create its own routines, set intentions for when you come online, and decide when to check in
