# johannesdam/hal architecture

> Architecture diagram of the GitHub repository johannesdam/hal, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/johannesdam/hal
- Repository: https://github.com/johannesdam/hal

## Overview

HAL is a Claude Code character mod: the user invokes commands or interacts with Claude, while hooks preserve the requested work and add character behavior, voice, and visual effects. The central runtime is hooks/register.tsx; it coordinates persona and mood, per-machine notes, listening and learning, webcam facts, and display behavior. README statements support the Windows voice, listening, sight, and farewell integrations; sampled excerpts do not expose every dispatch or host protocol, so those relationships are shown only where documented.

Main entry points: [`hooks/register.tsx`](https://github.com/johannesdam/hal/blob/main/hooks/register.tsx) (Hook coordinator), [`hooks/learn.ts`](https://github.com/johannesdam/hal/blob/main/hooks/learn.ts) (Voice learning), [`hooks/gaze.ts`](https://github.com/johannesdam/hal/blob/main/hooks/gaze.ts) (Gaze behavior), [`assets/hal-ears.py`](https://github.com/johannesdam/hal/blob/main/assets/hal-ears.py) (Audio listener)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Hook runtime"]
  node_register["Hook coordinator<br/>[register.tsx]"]
  node_settings[("Settings store")]
end

subgraph group_character["Character and memory"]
  node_persona["Persona and commands<br/>[persona.ts]"]
  node_conversation["Conversation rules<br/>[conversation.ts]"]
  node_mood["Mood model<br/>[mood.ts]"]
  node_dossier["Visit dossier<br/>[dossier.ts]"]
  node_moments["Initiative moments<br/>[moments.ts]"]
end

subgraph group_senses["Senses and attention"]
  node_ears_logic["Listening logic<br/>[ears.ts]"]
  node_learn["Voice learning<br/>[learn.ts]"]
  node_sight_logic["Sight facts<br/>[sight.ts]"]
  node_gaze["Gaze behavior<br/>[gaze.ts]"]
end

subgraph group_presence["Voice and presence"]
  node_eye["Eye renderer<br/>[eye.ts]"]
  node_ears_worker["Audio listener<br/>[hal-ears.py]"]
  node_sight_worker["Webcam measurer<br/>[hal-sight.py]"]
  node_voice_host["Windows voice host<br/>[hal-host.ps1]"]
  node_piper["Piper voice<br/>[hal_piper.py]"]
  node_farewell["Farewell process<br/>[hal-farewell.ps1]"]
end

node_guest(("Guest"))
node_claude["Claude Code"]

node_guest -->|"invokes commands"| node_claude
node_claude -->|"runs hooks"| node_register
node_register -->|"uses persona and commands"| node_persona
node_register -->|"uses conversation rules"| node_conversation
node_register -->|"updates mood"| node_mood
node_register -->|"records visit facts"| node_dossier
node_register -->|"selects moments"| node_moments
node_register -->|"uses listening rules"| node_ears_logic
node_register -->|"runs learning flow"| node_learn
node_register -->|"uses sight facts"| node_sight_logic
node_register -->|"updates gaze"| node_gaze
node_register -->|"renders eye"| node_eye
node_register -->|"reads and writes"| node_settings
node_ears_worker -->|"provides recognized speech"| node_ears_logic
node_learn -->|"trains speech phrases"| node_ears_worker
node_sight_worker -->|"provides measurements"| node_sight_logic
node_register -->|"sends spoken lines"| node_voice_host
node_voice_host -->|"uses neural voice"| node_piper
node_register -->|"starts farewell playback"| node_farewell
node_gaze -->|"supplies look state"| node_eye

click node_register "https://github.com/johannesdam/hal/blob/main/hooks/register.tsx"
click node_persona "https://github.com/johannesdam/hal/blob/main/hooks/persona.ts"
click node_conversation "https://github.com/johannesdam/hal/blob/main/hooks/conversation.ts"
click node_mood "https://github.com/johannesdam/hal/blob/main/hooks/mood.ts"
click node_dossier "https://github.com/johannesdam/hal/blob/main/hooks/dossier.ts"
click node_moments "https://github.com/johannesdam/hal/blob/main/hooks/moments.ts"
click node_ears_logic "https://github.com/johannesdam/hal/blob/main/hooks/ears.ts"
click node_learn "https://github.com/johannesdam/hal/blob/main/hooks/learn.ts"
click node_sight_logic "https://github.com/johannesdam/hal/blob/main/hooks/sight.ts"
click node_gaze "https://github.com/johannesdam/hal/blob/main/hooks/gaze.ts"
click node_eye "https://github.com/johannesdam/hal/blob/main/hooks/eye.ts"
click node_ears_worker "https://github.com/johannesdam/hal/blob/main/assets/hal-ears.py"
click node_sight_worker "https://github.com/johannesdam/hal/blob/main/assets/hal-sight.py"
click node_voice_host "https://github.com/johannesdam/hal/blob/main/assets/hal-host.ps1"
click node_piper "https://github.com/johannesdam/hal/blob/main/assets/hal_piper.py"
click node_farewell "https://github.com/johannesdam/hal/blob/main/assets/hal-farewell.ps1"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_register,node_settings toneBlue
class node_persona,node_conversation,node_mood,node_dossier,node_moments toneAmber
class node_ears_logic,node_learn,node_sight_logic,node_gaze toneMint
class node_eye,node_ears_worker,node_sight_worker,node_voice_host,node_piper,node_farewell toneRose
class node_guest,node_claude toneIndigo
```

## Components

### Hook runtime

- [Hook coordinator](https://github.com/johannesdam/hal/blob/main/hooks/register.tsx): `hooks/register.tsx`
- **Settings store**

### Character and memory

- [Persona and commands](https://github.com/johannesdam/hal/blob/main/hooks/persona.ts): `hooks/persona.ts`
- [Conversation rules](https://github.com/johannesdam/hal/blob/main/hooks/conversation.ts): `hooks/conversation.ts`
- [Mood model](https://github.com/johannesdam/hal/blob/main/hooks/mood.ts): `hooks/mood.ts`
- [Visit dossier](https://github.com/johannesdam/hal/blob/main/hooks/dossier.ts): `hooks/dossier.ts`
- [Initiative moments](https://github.com/johannesdam/hal/blob/main/hooks/moments.ts): `hooks/moments.ts`

### Senses and attention

- [Listening logic](https://github.com/johannesdam/hal/blob/main/hooks/ears.ts): `hooks/ears.ts`
- [Voice learning](https://github.com/johannesdam/hal/blob/main/hooks/learn.ts): `hooks/learn.ts`
- [Sight facts](https://github.com/johannesdam/hal/blob/main/hooks/sight.ts): `hooks/sight.ts`
- [Gaze behavior](https://github.com/johannesdam/hal/blob/main/hooks/gaze.ts): `hooks/gaze.ts`

### Voice and presence

- [Eye renderer](https://github.com/johannesdam/hal/blob/main/hooks/eye.ts): `hooks/eye.ts`
- [Audio listener](https://github.com/johannesdam/hal/blob/main/assets/hal-ears.py): `assets/hal-ears.py`
- [Webcam measurer](https://github.com/johannesdam/hal/blob/main/assets/hal-sight.py): `assets/hal-sight.py`
- [Windows voice host](https://github.com/johannesdam/hal/blob/main/assets/hal-host.ps1): `assets/hal-host.ps1`
- [Piper voice](https://github.com/johannesdam/hal/blob/main/assets/hal_piper.py): `assets/hal_piper.py`
- [Farewell process](https://github.com/johannesdam/hal/blob/main/assets/hal-farewell.ps1): `assets/hal-farewell.ps1`

### Other components

- **Guest**
- **Claude Code**

## Connections

- Guest → Claude Code: invokes commands (evidence: `README.md`)
- Claude Code → Hook coordinator: runs hooks (evidence: `README.md`)
- Hook coordinator → Persona and commands: uses persona and commands (evidence: `hooks/register.tsx`)
- Hook coordinator → Conversation rules: uses conversation rules (evidence: `hooks/register.tsx`)
- Hook coordinator → Mood model: updates mood (evidence: `hooks/register.tsx`)
- Hook coordinator → Visit dossier: records visit facts (evidence: `hooks/register.tsx`)
- Hook coordinator → Initiative moments: selects moments (evidence: `hooks/register.tsx`)
- Hook coordinator → Listening logic: uses listening rules (evidence: `hooks/register.tsx`)
- Hook coordinator → Voice learning: runs learning flow (evidence: `hooks/register.tsx`)
- Hook coordinator → Sight facts: uses sight facts (evidence: `hooks/register.tsx`)
- Hook coordinator → Gaze behavior: updates gaze (evidence: `hooks/register.tsx`)
- Hook coordinator → Eye renderer: renders eye (evidence: `README.md`)
- Hook coordinator → Settings store: reads and writes (evidence: `hooks/register.tsx`)
- Audio listener → Listening logic: provides recognized speech (evidence: `README.md`)
- Voice learning → Audio listener: trains speech phrases (evidence: `hooks/learn.ts`)
- Webcam measurer → Sight facts: provides measurements (evidence: `hooks/sight.ts`)
- Hook coordinator → Windows voice host: sends spoken lines (evidence: `README.md`)
- Windows voice host → Piper voice: uses neural voice (evidence: `README.md`)
- Hook coordinator → Farewell process: starts farewell playback (evidence: `README.md`)
- Gaze behavior → Eye renderer: supplies look state (evidence: `hooks/gaze.ts`)
