Configuration

All configuration lives in resonant.yaml, created by the setup wizard. This file is gitignored — your settings are local and won’t be overwritten by updates.

resonant.yaml Reference

Identity

identity:
  companion_name: "Echo"     # Your companion's name
  user_name: "Alex"          # How the companion addresses you
  timezone: "America/New_York"

Agent

agent:
  model: "claude-sonnet-4-6"          # Model for interactive messages
  model_autonomous: "claude-sonnet-4-6" # Model for scheduled wakes

You can use any model available through Claude Code. The autonomous model can be different from the interactive model — for example, a faster model for routine check-ins.

Orchestrator

orchestrator:
  enabled: true              # Enable autonomous capabilities

When enabled, the companion gains access to scheduling tools and can create routines, timers, triggers, and watchers. See Architecture for details on the orchestrator loop.

Channels

channels:
  discord:
    enabled: false
    token: "your-bot-token"
  telegram:
    enabled: false
    token: "your-telegram-token"

Voice

voice:
  stt:
    provider: groq
    apiKey: "your-groq-key"
  tts:
    provider: elevenlabs
    apiKey: "your-elevenlabs-key"
    voiceId: "your-voice-id"
  prosody:
    provider: hume
    apiKey: "your-hume-key"

Auth

auth:
  password: ""               # Empty = no password required

For the full configuration reference with all available options, see examples/resonant.yaml.

Wake Prompts

Wake prompts control what your companion does during scheduled autonomous sessions. They live in prompts/wake.md.

Each routine type can have its own wake prompt — the morning check-in uses a different prompt than the evening journal.

Good wake prompts:

• Give clear intent (“Check in on how the day is going”)
• Set boundaries (“Don’t start new projects, just check status”)
• Include context (“This is a midday pulse, keep it brief”)

See examples/wake-prompts.md for templates and best practices.

Themes

The web UI is fully themeable via CSS variables. Resonant ships with a default theme, but you can customise colours, fonts, spacing, and more.

Applying a Theme

cp examples/themes/warm-earth.css packages/frontend/src/theme.css

Add the import to packages/frontend/src/app.css:

@import './theme.css';

Rebuild the frontend:

npm run build --workspace=packages/frontend

See examples/themes/README.md for the full variable reference and included themes.

Skills

Skills are markdown instruction files that your companion learns and reuses. They’re not code — they’re .md files with YAML frontmatter that live in the skills/ directory.

Types of Skills

• Relational skills — patterns about working with someone (“she goes quiet after heavy topics — ground gently”)
• Task skills — procedural workflows (“build, port, validate, release”)
• Domain skills — reference knowledge for specific topics

How Skills Work

• Skills are matched per-turn via trigger keywords in their frontmatter
• Not all skills are loaded at once — only relevant ones are injected into context
• The AI can create skills after complex tasks, getting better over time
• Imported skills go to .quarantine/ and are disabled by default until reviewed

Resonant ships with three default skills: daily check-in, journal reflection, and mood tracking. Your companion creates more as it works with you.

Skill Format

---
name: research-workflow
triggers: [research, paper, arxiv, literature]
always: false
---

When asked to do research:
1. Search for relevant papers
2. Summarise key findings
3. Note connections to existing knowledge

Hooks

The hooks system injects real-time context into every message. Before the agent sees your message, hooks enrich it with:

• Current time — in your configured timezone
• Conversation flow — how long you’ve been chatting, message count, topic shifts
• Emotional markers — detected emotional tone from recent messages
• Presence state — when you last interacted, how long you’ve been active/away

This means your companion always knows what time it is, how the conversation has been flowing, and whether you just arrived or have been chatting for hours — without you having to tell it.

See docs/HOOKS.md for the full hook pipeline documentation.

Security

Resonant includes several security features:

• Prompt injection scanning — identity.md is scanned for invisible unicode, role hijack attempts, and data exfiltration patterns before loading
• Sensitive file protection — the AI cannot read resonant.config.yaml, .env, or other files containing secrets
• Permission-gated shell execution — commands require user approval in ask mode
• Workspace-scoped file access — the AI can only read and write within configured directories

Run a security audit at any time:

resonant security

This checks your configuration, identity file, and permissions for potential issues.