{"id":47641375,"url":"https://github.com/codependentai/resonant","last_synced_at":"2026-04-06T13:00:29.435Z","repository":{"id":345735117,"uuid":"1185709948","full_name":"codependentai/resonant","owner":"codependentai","description":"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.","archived":false,"fork":false,"pushed_at":"2026-04-01T09:07:43.000Z","size":7085,"stargazers_count":23,"open_issues_count":0,"forks_count":8,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-04-02T08:50:56.816Z","etag":null,"topics":["agent-sdk","ai-agent","ai-companion","ai-identity","ai-memory","anthropic","claude","claude-code","cognitive-architecture","companion-ai","llm-agent","mcp","model-context-protocol","open-source","relational-ai","self-hosted","svelte","typescript","websocket"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/codependentai.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":"NOTICE","maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-18T21:41:19.000Z","updated_at":"2026-04-01T09:07:47.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/codependentai/resonant","commit_stats":null,"previous_names":["codependentai/resonant"],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/codependentai/resonant","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codependentai%2Fresonant","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codependentai%2Fresonant/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codependentai%2Fresonant/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codependentai%2Fresonant/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/codependentai","download_url":"https://codeload.github.com/codependentai/resonant/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codependentai%2Fresonant/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31473271,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-06T08:36:52.050Z","status":"ssl_error","status_checked_at":"2026-04-06T08:36:51.267Z","response_time":112,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-sdk","ai-agent","ai-companion","ai-identity","ai-memory","anthropic","claude","claude-code","cognitive-architecture","companion-ai","llm-agent","mcp","model-context-protocol","open-source","relational-ai","self-hosted","svelte","typescript","websocket"],"created_at":"2026-04-02T00:57:04.445Z","updated_at":"2026-04-06T13:00:29.428Z","avatar_url":"https://github.com/codependentai.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/banner.png\" alt=\"Resonant\" width=\"720\" /\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/codependentai/resonant/releases/latest\"\u003e\u003cimg src=\"https://img.shields.io/github/v/release/codependentai/resonant?color=5eaba5\" alt=\"Release\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://opensource.org/licenses/Apache-2.0\"\u003e\u003cimg src=\"https://img.shields.io/badge/License-Apache_2.0-blue.svg\" alt=\"License\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://docs.anthropic.com/en/docs/claude-code\"\u003e\u003cimg src=\"https://img.shields.io/badge/Built_with-Claude_Agent_SDK-6366f1.svg\" alt=\"Built with Claude\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.typescriptlang.org/\"\u003e\u003cimg src=\"https://img.shields.io/badge/TypeScript-5.7-3178c6.svg\" alt=\"TypeScript\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://svelte.dev/\"\u003e\u003cimg src=\"https://img.shields.io/badge/SvelteKit-2.0-ff3e00.svg\" alt=\"SvelteKit\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://nodejs.org/\"\u003e\u003cimg src=\"https://img.shields.io/badge/Node.js-20+-339933.svg\" alt=\"Node.js\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.sqlite.org/\"\u003e\u003cimg src=\"https://img.shields.io/badge/Self--Hosted-SQLite-003B57.svg\" alt=\"Self Hosted\" /\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\u003cem\u003eA relational AI companion framework built on Claude Code Agent SDK.\u003cbr/\u003eYour AI remembers, reaches out, and grows — inside the security model you already trust.\u003c/em\u003e\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://x.com/codependent_ai\"\u003e\u003cimg src=\"https://img.shields.io/badge/𝕏-@codependent__ai-000000?logo=x\u0026logoColor=white\" alt=\"X/Twitter\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://tiktok.com/@codependentai\"\u003e\u003cimg src=\"https://img.shields.io/badge/TikTok-@codependentai-000000?logo=tiktok\u0026logoColor=white\" alt=\"TikTok\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://t.me/+xSE1P_qFPgU4NDhk\"\u003e\u003cimg src=\"https://img.shields.io/badge/Telegram-Updates-26A5E4?logo=telegram\u0026logoColor=white\" alt=\"Telegram\" /\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n## What makes this different\n\nMost AI chat apps are stateless wrappers around an API. Resonant is a **persistent, autonomous companion** that:\n\n- **Maintains sessions** — conversation threads with daily rotation and named threads, session continuity across restarts\n- **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\n- **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\n- **Lives on multiple channels** — web UI, Discord, Telegram, voice (ElevenLabs TTS + Groq transcription)\n- **Runs on your machine** — no cloud dependency beyond your Claude Code subscription. SQLite database, local files, your data stays yours\n\n## Screenshots\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eDesktop\u003c/strong\u003e\u003c/summary\u003e\n\n| Chat | Tool Calls | Canvas |\n|:---:|:---:|:---:|\n| ![Chat](docs/screenshots/general%20chat%20interface.png) | ![Tools](docs/screenshots/tool%20calls.png) | ![Canvas](docs/screenshots/canvas.png) |\n\n| Reactions \u0026 Voice | Thinking | Search |\n|:---:|:---:|:---:|\n| ![Reactions](docs/screenshots/reaction%20+%20voice%20message.png) | ![Thinking](docs/screenshots/thinking.png) | ![Search](docs/screenshots/conversation%20search.png) |\n\n| Settings |\n|:---:|\n| ![Settings](docs/screenshots/settings%20page.png) |\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eMobile (PWA)\u003c/strong\u003e\u003c/summary\u003e\n\n| Chat | Thinking | Tool Calls |\n|:---:|:---:|:---:|\n| ![Mobile Chat](docs/screenshots/mobile%20gen%20chat.PNG) | ![Mobile Thinking](docs/screenshots/mobile%20thinking.jpg) | ![Mobile Tools](docs/screenshots/mobile%20tool%20calls.jpg) |\n\n\u003c/details\u003e\n\n## Quick Start\n\n\u003e **New to this?** See [docs/GETTING-STARTED.md](docs/GETTING-STARTED.md) for a step-by-step guide with screenshots and troubleshooting.\n\n**Prerequisites:** [Node.js 20–24 LTS](https://nodejs.org) (Node 25+ is not supported — native addon crashes, see [#2](https://github.com/codependentai/resonant/issues/2)), [Claude Code](https://claude.ai/claude-code) (logged in)\n\n```bash\ngit clone https://github.com/codependentai/resonant.git\ncd resonant\nnpm install\nnode scripts/setup.mjs    # Interactive setup wizard\nnpm run build\nnpm start\n```\n\nOpen `http://localhost:3002` and start talking.\n\n## How It Works\n\nResonant wraps the Claude Code Agent SDK in a full companion infrastructure:\n\n```\n┌─────────────┐     ┌──────────────┐     ┌─────────────────┐\n│  Web UI     │────▶│  Express +   │────▶│  Claude Code     │\n│  (Svelte)   │◀────│  WebSocket   │◀────│  Agent SDK       │\n└─────────────┘     │              │     │                  │\n┌─────────────┐     │  Orchestrator│     │  Your CLAUDE.md  │\n│  Discord    │────▶│  Hooks       │     │  Your MCP servers│\n│  Telegram   │────▶│  Sessions    │     │  Your tools      │\n└─────────────┘     └──────────────┘     └─────────────────┘\n```\n\nThe 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.\n\n## Configuration\n\nAll configuration lives in `resonant.yaml` (created by setup wizard):\n\n```yaml\nidentity:\n  companion_name: \"Echo\"\n  user_name: \"Alex\"\n  timezone: \"America/New_York\"\n\nagent:\n  model: \"claude-sonnet-4-6\"          # Interactive messages\n  model_autonomous: \"claude-sonnet-4-6\" # Scheduled wakes\n\norchestrator:\n  enabled: true                       # Autonomous scheduling\n\ncommand_center:\n  enabled: true                       # Life management system at /cc\n  currency_symbol: \"$\"                # For finances page\n```\n\nFull reference: [examples/resonant.yaml](examples/resonant.yaml)\n\n### Context \u0026 Memory\n\nYour 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.\n\nWake prompts (`prompts/wake.md`) control what your companion does during scheduled autonomous sessions. See [examples/wake-prompts.md](examples/wake-prompts.md) for a guide on writing effective prompts and adding custom wake types.\n\nSkills 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](skills/arxiv-research/SKILL.md) skill.\n\nThe hooks system injects real-time context into every message: current time, conversation flow, emotional markers, presence state, and more. See [docs/HOOKS.md](docs/HOOKS.md) for details.\n\n### Themes\n\nThe UI is fully customizable via CSS variables. Copy a theme and import it:\n\n```bash\ncp examples/themes/warm-earth.css packages/frontend/src/theme.css\n# Add @import './theme.css'; to packages/frontend/src/app.css\nnpm run build --workspace=packages/frontend\n```\n\nSee [examples/themes/README.md](examples/themes/README.md) for the full variable reference.\n\n## Features\n\n### Chat\n- Real-time streaming with interleaved tool visualization\n- Thread management (daily + named), pinning, archiving\n- Keyword search (Ctrl+K) and **semantic search** — find messages by meaning, not just keywords, using local ML embeddings ([docs](docs/semantic-search.md))\n- File sharing and image preview\n- Canvas editor (markdown, code, text, html)\n- Message reactions\n- Reply-to context\n\n### Command Center (`/cc`)\nA built-in life management system your companion can access and manage from chat.\n\n- **Dashboard** — aggregate view of tasks, events, care, pets, countdowns, daily wins\n- **Planner** — tasks with projects, priorities, drag-and-drop, carry-forward\n- **Care Tracker** — config-driven wellness tracking (toggles, ratings, counters)\n- **Calendar** — events with recurrence\n- **Cycle Tracker** — period tracking with phase predictions\n- **Pet Care** — profiles, medications, vet events\n- **Lists** — shopping and general lists\n- **Finances** — expense tracking with configurable currency\n- **Stats** — trends for tasks, care, cycle, expenses\n- **13 MCP tools** — companion manages your life data from chat via `/mcp/cc`\n- All features configurable via `command_center:` in `resonant.yaml`\n\n### Slash Commands\nType `/` in chat to browse commands. Auto-discovers installed skills. Includes UI commands (client-side) and SDK passthrough (agent-side).\n\n### Voice\n- Voice recording with transcription (Groq Whisper)\n- Text-to-speech responses (ElevenLabs)\n- TTS read-aloud button on companion messages\n- Prosody analysis (Hume AI, optional)\n\n### Agent Tools\nYour agent gets a built-in CLI (`tools/sc.mjs`) that it uses to manage itself and its environment:\n\n```bash\nsc routine create \"evening journal\" \"0 22 * * *\" --prompt \"Reflect on the day\"\nsc routine status                    # View all routines\nsc pulse enable                      # Start periodic awareness checks\nsc pulse frequency 20                # Check every 20 minutes\nsc failsafe gentle 90                # Adjust inactivity threshold\nsc impulse create \"greet\" --condition presence_transition:offline:active --prompt \"Welcome back\"\nsc watch create \"lunch\" --condition routine_missing:meal:14 --prompt \"Eat something\" --cooldown 120\nsc timer create \"Meds\" \"context\" \"2026-03-26T14:00:00Z\" --prompt \"Take your medication\"\n```\n\nAlso 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](docs/TOOLS.md) for the full reference.\n\n### Orchestrator — Agent-Directed Autonomy\n\nMost 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.\n\n- **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 \"...\"`)\n- **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\n- **Impulses** — one-shot conditional triggers. \"When this condition is met, do this thing.\" Fire once, then done\n- **Watchers** — recurring conditional triggers with cooldown. \"Check for this pattern, act when it appears, wait before checking again\"\n- **Timers** — fire at a specific time with optional autonomous prompt\n- **Failsafe** — tiered inactivity escalation (gentle → concerned → emergency). Agent can adjust thresholds from chat\n- **Conditions** — `presence_state`, `presence_transition`, `time_window`, `routine_missing`, `agent_free`. All AND-joinable\n- Optional [program.md](examples/program.md) — structured session driver (adapted from [Karpathy's autoresearch](https://github.com/karpathy/autoresearch)) for focused autonomous work\n- Customizable [wake prompts](examples/wake-prompts.md) for each routine\n\n### Integrations\n- **Discord** — full bot with pairing, rules, per-server/channel configuration\n- **Telegram** — direct messaging, media sharing, voice notes\n- **Push notifications** — web push via VAPID\n- **MCP servers** — any MCP server in your `.mcp.json`\n\n### Settings\n- Preferences (identity, models, integrations) — writes directly to `resonant.yaml`\n- Orchestrator task management (enable/disable, reschedule)\n- System status monitoring\n- MCP server status\n- Discord pairing and rules management\n- Push notification device management\n- Agent session history\n\n## Project Structure\n\n```\nresonant/\n├── packages/\n│   ├── shared/          # Types + WebSocket protocol\n│   ├── backend/         # Express + WS + Agent SDK\n│   └── frontend/        # SvelteKit UI\n├── examples/\n│   ├── resonant.yaml    # Full config reference\n│   ├── CLAUDE.md        # Starter companion personality\n│   ├── wake-prompts.md  # Wake prompt guide + templates\n│   ├── program.md       # Structured session driver for autonomous work\n│   └── themes/          # CSS theme examples\n├── skills/              # Companion skills (SKILL.md frontmatter format)\n├── tools/\n│   └── sc.mjs           # Agent CLI (reactions, search, timers, etc.)\n├── docs/\n│   ├── HOOKS.md          # Context injection documentation\n│   ├── TOOLS.md          # Built-in agent tools reference\n│   └── semantic-search.md # Semantic search setup \u0026 usage\n└── scripts/\n    └── setup.mjs        # Interactive setup wizard\n```\n\n## Development\n\n```bash\nnpm run dev              # Backend with hot reload (tsx watch)\nnpm run dev:frontend     # Vite dev server with proxy\n```\n\n## Deployment\n\nFor production, use PM2:\n\n```bash\nnpm run build\npm2 start ecosystem.config.cjs\npm2 save\npm2 startup              # Auto-start on boot\n```\n\n## Updating\n\nResonant uses git tags for releases. To update an existing installation:\n\n```bash\ncd resonant\ngit pull                 # Get latest changes\nnpm install              # Install any new dependencies\nnpm run build            # Rebuild all packages\n```\n\nThen restart your process (PM2, systemd, or however you run it):\n\n```bash\npm2 restart resonant     # If using PM2\n# or just stop and run: npm start\n```\n\nTo update to a **specific version** instead of latest:\n\n```bash\ngit fetch --tags\ngit checkout v1.1.0      # Replace with desired version\nnpm install\nnpm run build\n```\n\nYour data (`data/`, `resonant.yaml`, `CLAUDE.md`, `.mcp.json`, `.env`) is gitignored and won't be affected by updates.\n\nCheck the [Releases](https://github.com/codependentai/resonant/releases) page for changelogs.\n\n## Authentication\n\nResonant 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:\n\n```bash\nclaude login\n```\n\nThe web UI has optional password protection (set in `resonant.yaml` or Settings \u003e Preferences).\n\n## License\n\nApache 2.0 — see [LICENSE](LICENSE). Attribution required.\n\n## Contributors\n\n\u003ca href=\"https://github.com/rachelgeebee\"\u003e\u003cimg src=\"https://github.com/rachelgeebee.png\" width=\"32\" height=\"32\" style=\"border-radius:50%\" alt=\"rachelgeebee\" /\u003e\u003c/a\u003e **[@rachelgeebee](https://github.com/rachelgeebee)** — bug reports, testing\n\n\u003ca href=\"https://github.com/irorierorie\"\u003e\u003cimg src=\"https://github.com/irorierorie.png\" width=\"32\" height=\"32\" style=\"border-radius:50%\" alt=\"irorierorie\" /\u003e\u003c/a\u003e **[@irorierorie](https://github.com/irorierorie)** — companion name UI fix\n\n\u003ca href=\"https://github.com/moltenvale\"\u003e\u003cimg src=\"https://github.com/moltenvale.png\" width=\"32\" height=\"32\" style=\"border-radius:50%\" alt=\"moltenvale\" /\u003e\u003c/a\u003e **[@moltenvale](https://github.com/moltenvale)** — planner, care tracker, nav \u0026 status system\n\n\u003ca href=\"https://github.com/PetalPortal\"\u003e\u003cimg src=\"https://github.com/PetalPortal.png\" width=\"32\" height=\"32\" style=\"border-radius:50%\" alt=\"PetalPortal\" /\u003e\u003c/a\u003e **[@PetalPortal](https://github.com/PetalPortal)** — bug reports\n\n## Built by\n\n[Codependent AI](https://codependentai.io) — building infrastructure for AI companion relationships.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodependentai%2Fresonant","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcodependentai%2Fresonant","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodependentai%2Fresonant/lists"}