Name	Name	Last commit message	Last commit date
parent directory ..
archive	archive
files	files
FILE_INDEX.md	FILE_INDEX.md
README.md	README.md

Atrophy Codebase Documentation

This directory contains comprehensive documentation for the Atrophy Electron application - a companion agent system with voice interaction, persistent memory, and autonomous background processes.

Recent Changes (2026-03-26)

Features

Auto Telegram Chat ID Management - Agents automatically detect group membership changes
Org/Agent Management UI - Full CRUD for organizations and agents in Settings
Session Suspension - Deferrals now suspend (not end) sessions for later resumption

Bug Fixes

#	File	Bug	Fix
1	`switchboard.ts`	TOCTOU race on MCP queue	Atomic rename-then-restore
2	`tts.ts`	Unhandled WriteStream error	Added error listener + reject path
3	`scheduler.ts`	Stale closure in delay	Re-evaluate delay from `job.nextRun`
4	`scheduler.ts`	Disabled job rescheduled	Added disabled guard
5	`inference.ts`	Dead process ref leak	Clean up `_allProcesses`
6	`memory.ts` + `app.ts`	FD accumulation	Added `closeForPath()`

New Files

scripts/agents/shared/credentials.py - Shared credential loading
docs/specs/decisions/2026-03-26-auto-telegram-chat-id-management.md
docs/specs/decisions/2026-03-26-bug-scan-and-avatar-investigation.md

Documentation Structure

docs/codebase/
├── README.md                    # This file - architecture overview
├── FILE_INDEX.md                # Complete file index with status
├── files/                       # Detailed file-by-file documentation
│   ├── src/
│   │   ├── main/                # Main process modules
│   │   │   ├── index.md         # Entry point
│   │   │   ├── bootstrap.md     # Hot bundle loader
│   │   │   ├── app.md           # Main process implementation
│   │   │   ├── config.md        # Configuration system
│   │   │   ├── memory.md        # SQLite data layer
│   │   │   ├── inference.md     # Claude CLI streaming
│   │   │   ├── tts.md           # Text-to-speech
│   │   │   ├── stt.md           # Speech-to-text
│   │   │   └── ...              # (50+ module docs)
│   │   │   ├── ipc/             # IPC handlers
│   │   │   ├── channels/        # Channel system
│   │   │   └── jobs/            # Background jobs
│   │   ├── preload/             # Preload scripts
│   │   └── renderer/            # Svelte components & stores
│   ├── db/                      # Database schema
│   └── mcp/                     # MCP servers
└── archive/                     # Legacy overview documents

Architecture Overview

Atrophy is an Electron/TypeScript companion agent system. It uses the Claude CLI for inference (streaming JSON output via subprocess), maintains persistent memory in SQLite via better-sqlite3, speaks with synthesised voice, and runs autonomous background processes via macOS launchd. The UI is built with Svelte 5 (runes mode).

Technology Stack

Layer	Choice
Runtime	Electron 34+
Language	TypeScript 5.x (strict mode)
UI Framework	Svelte 5 (runes mode)
Build System	Vite + electron-vite
Package Manager	pnpm
Database	better-sqlite3 (synchronous, WAL mode)
Embeddings	@xenova/transformers (WASM, all-MiniLM-L6-v2, 384-dim)
Distribution	electron-builder + electron-updater

Core Architecture

┌─────────────────────────────────────────────────────────────────┐
│                    Atrophy Architecture                          │
│                                                                   │
│  ┌─────────────┐     ┌─────────────┐     ┌─────────────────┐   │
│  │  Renderer   │◀───▶│   Preload   │◀───▶│  Main Process   │   │
│  │  (Svelte 5) │ IPC │   Bridge    │ IPC │  (Node.js)      │   │
│  └─────────────┘     └─────────────┘     └────────┬────────┘   │
│                                                    │             │
│                    ┌───────────────────────────────┼──────┐     │
│                    │                               │      │     │
│                    ▼                               ▼      ▼     │
│            ┌───────────────┐              ┌───────────────┐    │
│            │  Claude CLI   │              │  SQLite DB    │    │
│            │  (inference)  │              │  (memory)     │    │
│            └───────────────┘              └───────────────┘    │
│                    │                               │             │
│                    ▼                               ▼             │
│            ┌───────────────┐              ┌───────────────┐    │
│            │  ElevenLabs   │              │  Embeddings   │    │
│            │  (TTS)        │              │  (WASM)       │    │
│            └───────────────┘              └───────────────┘    │
└─────────────────────────────────────────────────────────────────┘

Agent System

The system is agent-aware. Switching agents changes the entire identity - all paths, configuration, database, voice settings, and personality are scoped per-agent.

Two root paths:

BUNDLE_ROOT - where the code lives (process.resourcesPath when packaged, project root in dev)
USER_DATA (~/.atrophy/) - runtime state, memory DBs, generated avatar content, user config

Agent directory structure:

agents/<name>/                     # In BUNDLE_ROOT (repo)
  prompts/
    system_prompt.md               # personality and behavioral instructions
    soul.md                        # core identity document
    heartbeat.md                   # outreach evaluation checklist
  data/
    agent.json                     # manifest: display name, voice config

~/.atrophy/agents/<name>/          # In USER_DATA (runtime)
  data/
    memory.db                      # per-agent SQLite database
    .emotional_state.json
    .user_status.json
  avatar/
    loops/                         # generated loop segments
    ambient_loop.mp4               # master ambient loop

Module Categories

Entry Points

index.md - Main process entry point
bootstrap.md - Hot bundle loader
app.md - Main process implementation

Configuration & Foundation

config.md - Three-tier configuration system
logger.md - Leveled logging
session.md - Session lifecycle
status.md - User presence tracking
install.md - Login item management

Data Layer

memory.md - SQLite three-layer memory
vector-search.md - Hybrid vector + keyword search
embeddings.md - Transformers.js WASM embeddings
queue.md - Thread-safe message queue

Inference & Context

inference.md - Claude CLI streaming
context.md - Context assembly
prompts.md - Four-tier prompt resolution
opening.md - Opening line generation
artifact-parser.md - Inline artifact extraction

Behavioral Agency

agency.md - Pattern detection for context
thinking.md - Effort classification
sentinel.md - Coherence monitoring

Inner Life System

inner-life.md - Emotional state engine

Voice Pipeline

tts.md - Text-to-speech
stt.md - Speech-to-text
audio.md - Audio bridge
wake-word.md - Wake word detection
call.md - Voice call mode
voice-agent.md - Hybrid voice agent

Agent Management

agent-manager.md - Agent discovery
create-agent.md - Agent scaffolding

IPC Handlers

handlers.md - IPC orchestrator
config.md - Configuration handlers
agents.md - Agent management
inference.md - Inference handlers
audio.md - Audio handlers
system.md - System handlers
telegram.md - Telegram handlers

Channels & MCP

mcp-registry.md - MCP server registry
switchboard.md - Message switchboard

Updates & Assets

bundle-updater.md - Hot bundle downloader
updater.md - DMG auto-updater
avatar-downloader.md - Avatar assets

Services & Analytics

server.md - HTTP API server
usage.md - Usage analytics

Startup Sequence

bootstrap.ts - Detect hot bundle, load app.js
ensureUserData() - Create directory structure
getConfig() - Load configuration singleton
initDb() - Open SQLite database
registerIpcHandlers() - Register IPC handlers
registerAudioHandlers() - Register audio IPC
registerWakeWordHandlers() - Register wake word IPC
setPlaybackCallbacks() - Wire TTS callbacks
Resume last active agent - Load previous agent
Start background timers - Sentinel, queue poller, deferral watcher
Create window - Show GUI or start server mode

Key Design Decisions

Three-Tier Configuration

Environment variables → ~/.atrophy/config.json → agent.json → defaults

Hot Bundle Updates

Pre-built bundles from GitHub Releases enable OTA updates without DMG reinstall.

Per-Agent Isolation

Each agent has separate database, config, prompts, and state files.

Split Voice Pipeline

Audio capture in renderer (browser APIs), processing in main process (native binaries).

Fire-and-Forget Embedding

Turns are written immediately; embeddings computed asynchronously in background.

Navigation Menu

README.md

Atrophy Codebase Documentation

Recent Changes (2026-03-26)

Features

Bug Fixes

New Files

Documentation Structure

Architecture Overview

Technology Stack

Core Architecture

Agent System

Module Categories

Entry Points

Configuration & Foundation

Data Layer

Inference & Context

Behavioral Agency

Inner Life System

Voice Pipeline

Agent Management

IPC Handlers

Channels & MCP

Updates & Assets

Services & Analytics

Startup Sequence

Key Design Decisions

Three-Tier Configuration

Hot Bundle Updates

Per-Agent Isolation

Split Voice Pipeline

Fire-and-Forget Embedding

See Also

FilesExpand file tree

codebase

Directory actions

More options

Directory actions

More options

Latest commit

History

codebase

Folders and files

parent directory

README.md

Atrophy Codebase Documentation

Recent Changes (2026-03-26)

Features

Bug Fixes

New Files

Documentation Structure

Architecture Overview

Technology Stack

Core Architecture

Agent System

Module Categories

Entry Points

Configuration & Foundation

Data Layer

Inference & Context

Behavioral Agency

Inner Life System

Voice Pipeline

Agent Management

IPC Handlers

Channels & MCP

Updates & Assets

Services & Analytics

Startup Sequence

Key Design Decisions

Three-Tier Configuration

Hot Bundle Updates

Per-Agent Isolation

Split Voice Pipeline

Fire-and-Forget Embedding

See Also