HavenSpace — AI assistant for therapists
A calm assistant for therapists, used after a session. It:
- drafts the clinical note (SOAP, DAP, BIRP or free text),
- offers supervisor-style reflection on the therapist's own technique, with every point linked to the exact moment in the transcript,
- keeps a timeline per client (themes, goals, homework),
- prepares a monthly supervision pack with an hours log.
It deliberately does not give live advice, suggest diagnoses or score risk (see docs/decisions.md, ADR-4).
Demo mode. Until the EU AI provider is connected and the privacy review (DPIA) is done, use role-play sessions only. The app shows a banner to remind you.
Run it on your Mac
You need two free tools, installed once:
| Tool | Why | Check it's installed |
|---|
| Node.js 24 | runs the website | node --version |
| uv | runs the Python worker (speech-to-text and AI) | ~/.local/bin/uv --version |
(Both are already installed on Shurik's Mac. To install uv elsewhere: curl -LsSf https://astral.sh/uv/install.sh | sh.)
First time only
Open Terminal in the project folder and run:
npm run setup
Then create your settings file (skip this if .env already exists — it does on Shurik's Mac):
cp .env.example .env
Open .env and fill in BETTER_AUTH_SECRET (any long random text; openssl rand -base64 32 makes one) and the two database passwords.
Every time
npm run up
This starts the database, the website and the background worker. Then open http://localhost:3210.
The first time, also load the demo data (a demo therapist with five role-play clients):
npm run db:seed
Signing in locally
Emails aren't sent on your laptop. The quickest way in is http://localhost:3210/dev/login: one click signs you in as the demo therapist (admin), a therapist waiting for approval, or a brand-new user. To try the real sign-in screen instead, ask for a code and find it at http://localhost:3210/dev/mailbox. Both pages exist only on your laptop, never on the live site.
- Demo account: [email protected] (has five role-play sessions ready to review)
- Or type any email to create a fresh account and go through onboarding.
Try a full recording without a microphone
This turns a written role-play into audio with the Mac's built-in voices, then feeds it through the whole pipeline (transcription → speaker labels → audio deletion → note and reflection):
cd services/worker
~/.local/bin/uv run python tools/make_roleplay_audio.py ../../evals/sessions/02-mi-alcohol.json
~/.local/bin/uv run python tools/simulate_session.py --email [email protected] --client "Client B" --audio .data/roleplay/02-mi-alcohol --mode in_person --calibrate
Then open Today in the app — the session appears under "Being prepared", and is ready within a couple of minutes on a laptop.
To try real recording, add a client, record consent, and choose Start session → In the room (any browser) or Online call (Chrome or Edge: share the meeting tab with "Share tab audio" ticked).
Turning on real AI drafting
Out of the box the AI is in demo mode: notes and reflections are clearly marked placeholders, so everything else can be tried without any account.
To use Claude for development (role-play data only):
- Create an account at console.anthropic.com, set a monthly spending limit, and create an API key.
- In
.env, set LLM_PROVIDER=anthropic and paste the key into ANTHROPIC_API_KEY=.
- Restart (
Ctrl+C, then npm run up).
Before any real client data: switch to LLM_PROVIDER=bedrock (Claude on AWS in Frankfurt) — see ADR-3 — and complete the checklist at the end of docs/privacy-architecture.md.
Live suggestions during a session (research experiment)
An experiment for Shurik and the Clinical Lead only (see docs/decisions.md, ADR-10). Role-play sessions only.
- In
.env, list the sign-in emails allowed to use it: [email protected],[email protected]. Restart (npm run up).
- Start a session (Online call or In the room). Tick Live suggestions during the session before you start.
- Every half a minute a short read appears next to the timer. After the session, the reads are listed at the bottom of the session page.
Without an AI key the reads are [Demo] placeholders. To try it without a microphone:
cd services/worker
~/.local/bin/uv run python tools/simulate_live.py --email [email protected] --client "Client A" --audio .data/roleplay/01-cbt-sleep-worry --mode online_call --seconds 90
Useful commands
| Command | What it does |
|---|
npm run up | Start everything (database, website, worker) |
npm run db:seed | Reset the demo account with five role-play sessions |
npm test | Run all automated checks (security, consent, deletion, evidence, speaker labels) |
npm run eval | Run the five role-play sessions through the AI and create a rating report in evals/reports/ for the Clinical Lead |
npm run signups | Save demo requests and waiting-list sign-ups to .data/signups.csv |
What's where
apps/web/ the website and app (Next.js)
messages/ all wording, English (en.json) and Russian (ru.json)
src/app/(marketing) public pages: landing, privacy, consent template, legal
src/app/(app) the signed-in app: Today, Clients, Sessions, Supervision, Settings
services/worker/ background worker (Python): speech-to-text, speaker labels, AI steps
prompts/ AI instructions (versioned; clinical review needed)
packages/shared/ modality rubrics (CBT, MI, person-centred, ...) — clinical review needed
db/migrations/ database structure, security rules and the consent gate
evals/ role-play sessions, forbidden terms, rating reports
docs/ decisions (ADRs), privacy architecture, sub-processors, clinical review list
reference/prototype/ place the Clinical Lead's original prototype here (not published)
Documents
docs/decisions.md — every significant choice and why (ADR-1 to ADR-9)
docs/privacy-architecture.md — data flows and protections (input for the DPIA)
docs/subprocessors.md — companies that would process data
docs/clinical-review.md — everything the Clinical Lead needs to review