How cheiineeey/callhome works
Callhome is a self-hosted voice-call stack for AI companions. Its main voice workflow sends browser-recorded audio to the STT service for transcription, emotion tags, and speaker-relative tone cues, then returns the interaction to a gateway that coordinates an LLM and TTS. A separate invite workflow supports companion-initiated calls and PWA push ringing. The repository contains reference extracts rather than the complete gateway or client; several README-documented capabilities have no sampled implementation path, so their links are documentation-based.
Main entry points: pwa-reference Call UI · gateway-reference Conversation gateway · markers.js Marker handler · server.py Transcription endpoint
Components 22
PWA ringing
- Call UI
pwa-reference - Worker registration
pwa-reference/register-and-clear.js - Push worker
pwa-reference/sw.js - Ring cleanup
pwa-reference/register-and-clear.js
Call orchestration
- Conversation gateway
gateway-reference - Marker handler
gateway-reference/markers.js - Escalation dialer
gateway-reference/escalation.js - Call invite API
gateway-reference - Ring burst
gateway-reference/ring-burst.py
Speech understanding
- Transcription endpoint
stt-service/server.py - Tone baseline
stt-service/tone.py - Emotion sensing
stt-service/server.py
Call capabilities
- Gentle hangup
gateway-reference/markers.js - Do not disturb
gateway-reference/markers.js - Voicemail
docs/PROTOCOL.md - Quick decline
docs/PROTOCOL.md - Call records
docs/PROTOCOL.md - Bedtime radio
README.md
Other components
- Person
- LLM service
- TTS service
- Web push
Connections 25
- Person → Call UI: uses
README.md - Call UI → Transcription endpoint: uploads audio
README.md - Transcription endpoint → Emotion sensing: tags speech
stt-service/server.py - Transcription endpoint → Tone baseline: ranks features
stt-service/server.py - Transcription endpoint → Conversation gateway: returns transcript
README.md - Conversation gateway → LLM service: requests reply
README.md - Conversation gateway → TTS service: requests speech
README.md - TTS service → Call UI: streams audio
README.md - Conversation gateway → Marker handler: parses reply
gateway-reference/markers.js - Marker handler → Call invite API: creates invite
gateway-reference/markers.js - Call invite API → Ring burst: starts burst
gateway-reference/ring-burst.py - Ring burst → Web push: sends notifications
gateway-reference/ring-burst.py - Web push → Push worker: delivers push
pwa-reference/sw.js - Push worker → Call UI: signals incoming call
pwa-reference/sw.js - Call UI → Worker registration: registers worker
pwa-reference/register-and-clear.js - Call UI → Ring cleanup: stops ringing
pwa-reference/register-and-clear.js - Push worker → Ring cleanup: closes notification stack
pwa-reference/sw.js - Escalation dialer → Call invite API: requests invite
gateway-reference/escalation.js - Escalation dialer → LLM service: generates reason
gateway-reference/escalation.js - Marker handler → Gentle hangup: handles marker
gateway-reference/markers.js - Marker handler → Do not disturb: updates flag
gateway-reference/markers.js - Conversation gateway → Voicemail: supports
README.md - Call UI → Quick decline: offers
README.md - Conversation gateway → Call records: keeps
README.md - Call UI → Bedtime radio: offers
README.md