Guided Exercises
OpenCouch includes 13 structured exercises spanning 6 therapeutic subtypes. The catalog is shared by text and voice, but availability is channel-aware: text can use the full catalog, while voice filters to exercises marked suitable for spoken delivery. Each exercise is a multi-turn flow run by plain guided-exercise services: the control LLM selects the exercise and classifies step progress, the response model writes user-facing guidance, and local code applies catalog/state validation.
How it works
- Dispatcher routes to
guided_exercisewhen the user explicitly asks for a structured exercise or practice. - Exercise selector chooses one supported exercise. Selection is LLM-owned and constrained to definitions available for the current channel, installed skills, and therapeutic approach.
- Step-state classifier evaluates each user response as
complete/hold/stuck/exitusing the current step's natural-language completion criteria. ExerciseRunneradvances, holds, adapts, exits, or completes based on the classifier output and local state validation.- Exercise clears on natural completion or user-initiated exit.
Approach continuity
The therapeutic approach picked at exercise start (e.g., act for a
values-clarification exercise) is pinned on
exercise_state.exercise_therapeutic_approach.
If the user pauses mid-exercise to ask a clarifying question, or when
the exercise guidance resumes, the dispatcher preserves the pinned
approach instead of letting the LLM pick a fresh one. Psychoeducation
side-turns preserve the active exercise state, but may use a fresh
top-level approach for the explanation. Without the exercise pin,
resuming guidance after a side-turn could silently drift into cbt or
motivational_interviewing framing.
Text and voice delivery
The registry normalizes text-like channels to text and voice turns to
voice. Voice can only offer definitions where voice_supported=True
or the definition explicitly includes the voice channel.
Today the voice-supported set contains 10 exercises:
| Exercise id | Family |
|---|---|
grounding_5_4_3_2_1 | Grounding |
grounding_box_breathing | Grounding |
grounding_stop_technique | Grounding |
grounding_muscle_relaxation | Grounding |
thought_work_continuum | Thought work |
behavioral_activation_tiny_action | Activation |
defusion_values_compass | ACT values |
self_compassion_break | Emotion regulation |
emotion_regulation_improve | Emotion regulation |
emotion_regulation_gratitude | Emotion regulation |
Voice uses Realtime function tools to list available exercises, load the selected skill block, and record step progress. The underlying catalog and state validation are the same as text; only the transport binding differs.
Post-exercise check-in
When an exercise reaches its terminal step, the completion node
enriches the prompt with a "How was that for you?" check-in so the
session can reflect on the experience rather than ending abruptly.
The completion turn also sets should_persist_memory=True to hint
the persistence layer to summarize the session.
Completion modes
Steps use one of four modes for judging completion:
| Mode | How it works | Used for |
|---|---|---|
| items | Complete when the user names enough relevant items for the step's min_items / target_items guidance | Sensory listing, naming thoughts, identifying actions |
| confirmation | Complete when the user indicates they performed the private action or are ready to continue | Breathing actions, visualization, body exercises |
| response | Complete when the user gives a substantive answer to the step instruction | Reflections, values, planning prompts |
| llm_judged | Complete when the user's reply satisfies custom completion_criteria in substance, even if imperfect | More nuanced cognitive or emotional steps |
Priority ordering
The classifier returns exactly one state:
- exit — the user wants to stop, cancel, switch away, or just talk.
- stuck — the user says they cannot do the step, nothing comes to mind, or the exercise feels confusing/frustrating.
- complete — the user appears to have completed the requested step.
- hold — the user is tentative, partial, off-step, or still engaging but has not clearly completed the step.
Exercise catalog
Click any exercise to see its steps and trigger keywords. Use the filter tabs to browse by subtype. To see exercises in context as multi-turn conversations, see Scenarios.
5-4-3-2-1 Grounding
Sensory anchoring exercise. The user identifies items across five senses to return to the present moment. Steps are independent — order matters less than engagement.
Box Breathing
Structured 4-phase breathing cycle targeting somatic regulation. Each step is a single breathing action confirmed by the user. Complements 5-4-3-2-1 (sensory) with a respiratory channel.
STOP Technique
DBT-informed distress tolerance skill. Each letter is a discrete step. S-T steps use confirmation mode (somatic); O-P steps use item count (cognitive).
Progressive Muscle Relaxation
Body-focused relaxation: tense and release 5 muscle groups. Each step is a simple "tense, hold, release, notice." Complements breathing (respiratory) and 5-4-3-2-1 (sensory) with a muscular channel.
Simple Thought Record
Simplified 4-step CBT thought record. Sequential — each step depends on the prior. Exit is the only valid off-ramp. The user discovers the reframe rather than being told what the "correct" thought is.
Behavioral Experiment
Tests beliefs in the real world. The thought record examines evidence in the mind; this tests it in reality. Step 3→4 may span hours (the user does something IRL between turns).
Continuum (All-or-Nothing)
Targets rigid all-or-nothing self-labels by converting an absolute ("I'm a terrible parent") into a 0-100 dimension. The user defines both endpoints, then places themselves honestly. Most discover they're mid-range, not at zero — which is already a shift from the absolute framing.
Tiny Action Experiment
One small action framed as an experiment, not a commitment. Targets avoidance and low activation. The ask is intentionally tiny — "just to see what happens."
Leaves on a Stream
ACT defusion exercise. The user names a sticky thought, places it on an imagined leaf, watches it float, notices what remains, then identifies a values-aligned step. The exercise is about acting alongside the thought, not removing it.
Values Compass
ACT values clarification. Counterpart to defusion — Leaves on a Stream helps with letting go; Values Compass helps with moving toward. Together they cover the full ACT arc.
Self-Compassion Break
Kristin Neff's 3-component model. Very short by design — self-compassion exercises lose power when long. The user chooses their own kind words rather than following a script.
IMPROVE the Moment
Core DBT distress tolerance skill. Uses 4 of the 7 IMPROVE letters: Imagery, Meaning, One thing, Encouragement. For users in acute overwhelm who need help tolerating the current moment.
Gratitude Inventory
Short positive-psychology exercise for building positive affect. Best for neutral-to-low-mood states or session closers. Not appropriate during acute distress.
Define an ExerciseDefinition under agent/skills/guided_exercises/definitions/, include its steps and selector groups, register it in the ALL_EXERCISE_DEFINITIONS tuple in agent/skills/guided_exercises/registry.py, and add LLM guidance to agent/prompts/sources/response_styles/guided_exercise.md when the new exercise needs behavior-specific prose. No dispatcher or graph changes should be needed. See Agent Graph for the full architecture.