Docs/Resonant/Getting Started

Getting Started

This guide walks you through installing Resonant and running your first companion. You’ll be chatting in under five minutes.

Prerequisites

  • Node.js 20-24 LTS — download here. Node 25+ is not currently supported due to native addon issues.
  • Claude Code — install here. Make sure you’re logged in (claude login).
  • Git — to clone the repository.

Resonant uses the Claude Agent SDK, which runs through your existing Claude Code subscription. No separate API key is required.

Installation

git clone https://github.com/codependentai/resonant.git
cd resonant
npm install

Setup Wizard

Run the interactive setup wizard to configure your companion:

node scripts/setup.mjs

The wizard will ask you to:

  1. Name your companion — this appears in the UI and in messages
  2. Set your name — how the companion addresses you
  3. Choose your timezone — used for scheduling and time awareness
  4. Select a model — the default is claude-sonnet-4-6
  5. Configure integrations (optional) — Discord, Telegram, voice

This creates two files:

  • resonant.yaml — all configuration (models, integrations, scheduling)
  • CLAUDE.md — your companion’s personality and instructions

Both files are gitignored and won’t be affected by updates.

Writing Your Companion’s Personality

Open CLAUDE.md in any text editor. This is where you define who your AI is. Resonant ships with a starter template, but you’ll want to make it yours.

A good CLAUDE.md includes:

  • Identity — name, core traits, communication style
  • Relationship context — who are you to each other
  • Boundaries — what the AI should and shouldn’t do
  • Preferences — how you like to communicate

See examples/CLAUDE.md for a full example.

Build and Run

npm run build
npm start

Open http://localhost:3002 in your browser and start talking.

What You’ll See

The web UI includes:

  • Chat — real-time streaming with tool call visualisation
  • Threads — daily rotation plus named threads for ongoing topics
  • Search — keyword and semantic search across all messages
  • Canvas — markdown, code, and HTML editor
  • Settings — configuration, orchestrator management, system status

Enabling the Orchestrator

The orchestrator gives your companion autonomous capabilities — scheduled check-ins, awareness monitoring, and the ability to create its own routines.

In resonant.yaml:

orchestrator:
  enabled: true

Once enabled, your companion gains access to scheduling tools and can create routines, set timers, and monitor conditions on its own. See Configuration for the full reference.

Next Steps

arrow_back
Previous Overview
Next Architecture
arrow_forward