# thedeepakreddy/e.c.h.o-mac architecture

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

- Interactive diagram: https://gitdiagram.com/thedeepakreddy/e.c.h.o-mac
- Repository: https://github.com/thedeepakreddy/e.c.h.o-mac

## Overview

Echo Mac is a macOS voice and desktop assistant. A user speaks or types a goal; the configured model interprets it, routes tool work or a supervised task, and Echo exposes progress, checks, and results for review. Distinct capabilities include coding, research, desktop control, memory, background work, voice, and phone interaction. The graph combines README-described product stages with source-index evidence for selected internal links; many subsystem internals were not sampled, so their detailed call paths are intentionally omitted.

Main entry points: [`src/main.ts`](https://github.com/thedeepakreddy/e.c.h.o-mac/blob/main/src/main.ts) (App runtime), [`src/agent-replay/runtime.ts`](https://github.com/thedeepakreddy/e.c.h.o-mac/blob/main/src/agent-replay/runtime.ts) (Recorded agent loop), [`src/brain/index.ts`](https://github.com/thedeepakreddy/e.c.h.o-mac/blob/main/src/brain/index.ts) (Model selection), [`src/brain/tool-router.ts`](https://github.com/thedeepakreddy/e.c.h.o-mac/blob/main/src/brain/tool-router.ts) (Tool routing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Interaction and runtime"]
  node_main["App runtime<br/>[main.ts]"]
  node_voice["Voice input/output<br/>[listener.ts]"]
  node_config["Configuration<br/>[config.ts]"]
  node_review["Progress and results<br/>[control-panel.ts]"]
end

subgraph group_agent["Agent execution"]
  node_brain["Model selection<br/>[index.ts]"]
  node_router["Tool routing<br/>[tool-router.ts]"]
  node_recording["Recorded agent loop<br/>[runtime.ts]"]
  node_looplog["Loop log<br/>[loop-log.ts]"]
  node_recorder["Run recorder<br/>[recorder.ts]"]
  node_recovery["Run recovery<br/>[recovery.ts]"]
end

subgraph group_work["Task capabilities"]
  node_supervisor["Supervised tasks<br/>[supervisor.ts]"]
  node_coding["Coding workflow<br/>[session.ts]"]
  node_processes["Managed processes<br/>[processes.ts]"]
  node_research["Research<br/>[research.ts]"]
  node_desktop["Desktop controls"]
  node_companion["Phone companion"]
end

subgraph group_state["Memory and evidence"]
  node_memory[("Memory service<br/>[service.ts]")]
  node_taskstate[("Task state<br/>[task-state.ts]")]
  node_episodic[("Episodic cognition<br/>[episodic.ts]")]
  node_paths["Data paths<br/>[paths.ts]"]
  node_voice_log[("Voice log<br/>[voice-log.ts]")]
  node_storage["Storage budget<br/>[storage-budget.ts]"]
  node_safety["Secret redaction<br/>[redact.ts]"]
end

subgraph group_integrations["External integrations"]
  node_models{{"Model providers"}}
  node_macos{{"macOS apps"}}
  node_phone{{"Companion phone"}}
end

node_user(("User"))

node_user -->|"speaks to"| node_voice
node_user -->|"types request"| node_main
node_voice -.->|"submits request"| node_main
node_main -->|"creates brain"| node_brain
node_brain -->|"queries provider"| node_models
node_main -->|"routes tools"| node_router
node_brain -->|"wraps provider"| node_recording
node_recording -->|"records runs"| node_recorder
node_recording -->|"logs iterations"| node_looplog
node_recording -->|"uses recovery"| node_recovery
node_router -->|"selects coding tools"| node_coding
node_main -->|"starts tasks"| node_supervisor
node_coding -->|"manages commands"| node_processes
node_router -.->|"dispatches controls"| node_desktop
node_router -->|"routes research"| node_research
node_main -->|"wires companion"| node_companion
node_companion -->|"sends updates"| node_phone
node_main -->|"loads settings"| node_config
node_recording -->|"persists task state"| node_taskstate
node_brain -->|"loads prompt facts"| node_episodic
node_memory -->|"uses data paths"| node_paths
node_main -.->|"wires memory"| node_memory
node_recorder -->|"redacts records"| node_safety
node_recorder -->|"checks write budget"| node_storage
node_voice -->|"logs voice"| node_voice_log
node_voice_log -->|"checks budget"| node_storage
node_main -->|"exposes progress"| node_review
node_review -->|"presents results"| node_user
node_desktop -->|"acts on apps"| node_macos

click node_main "https://github.com/thedeepakreddy/e.c.h.o-mac/blob/main/src/main.ts"
click node_voice "https://github.com/thedeepakreddy/e.c.h.o-mac/blob/main/src/voice/listener.ts"
click node_brain "https://github.com/thedeepakreddy/e.c.h.o-mac/blob/main/src/brain/index.ts"
click node_router "https://github.com/thedeepakreddy/e.c.h.o-mac/blob/main/src/brain/tool-router.ts"
click node_recording "https://github.com/thedeepakreddy/e.c.h.o-mac/blob/main/src/agent-replay/runtime.ts"
click node_looplog "https://github.com/thedeepakreddy/e.c.h.o-mac/blob/main/src/agent-replay/loop-log.ts"
click node_recorder "https://github.com/thedeepakreddy/e.c.h.o-mac/blob/main/src/agent-replay/recorder.ts"
click node_recovery "https://github.com/thedeepakreddy/e.c.h.o-mac/blob/main/src/agent-replay/recovery.ts"
click node_supervisor "https://github.com/thedeepakreddy/e.c.h.o-mac/blob/main/src/tasks/supervisor.ts"
click node_coding "https://github.com/thedeepakreddy/e.c.h.o-mac/blob/main/src/coding/session.ts"
click node_processes "https://github.com/thedeepakreddy/e.c.h.o-mac/blob/main/src/coding/processes.ts"
click node_research "https://github.com/thedeepakreddy/e.c.h.o-mac/blob/main/src/frontier/research.ts"
click node_desktop "https://github.com/thedeepakreddy/e.c.h.o-mac/blob/main/src/tools/computer-actions.ts"
click node_companion "https://github.com/thedeepakreddy/e.c.h.o-mac/blob/main/src/control-companion.ts"
click node_config "https://github.com/thedeepakreddy/e.c.h.o-mac/blob/main/src/config.ts"
click node_memory "https://github.com/thedeepakreddy/e.c.h.o-mac/blob/main/src/memory/service.ts"
click node_taskstate "https://github.com/thedeepakreddy/e.c.h.o-mac/blob/main/src/memory/task-state.ts"
click node_episodic "https://github.com/thedeepakreddy/e.c.h.o-mac/blob/main/src/cognition/episodic.ts"
click node_paths "https://github.com/thedeepakreddy/e.c.h.o-mac/blob/main/src/memory/paths.ts"
click node_voice_log "https://github.com/thedeepakreddy/e.c.h.o-mac/blob/main/src/voice/voice-log.ts"
click node_storage "https://github.com/thedeepakreddy/e.c.h.o-mac/blob/main/src/diagnostics/storage-budget.ts"
click node_safety "https://github.com/thedeepakreddy/e.c.h.o-mac/blob/main/src/safety/redact.ts"
click node_review "https://github.com/thedeepakreddy/e.c.h.o-mac/blob/main/src/control-panel.ts"

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_main,node_voice,node_config,node_review,node_user toneBlue
class node_brain,node_router,node_recording,node_looplog,node_recorder,node_recovery toneAmber
class node_supervisor,node_coding,node_processes,node_research,node_desktop,node_companion toneMint
class node_memory,node_taskstate,node_episodic,node_paths,node_voice_log,node_storage,node_safety toneRose
class node_models,node_macos,node_phone toneIndigo
```

## Components

### Interaction and runtime

- [App runtime](https://github.com/thedeepakreddy/e.c.h.o-mac/blob/main/src/main.ts): `src/main.ts`
- [Voice input/output](https://github.com/thedeepakreddy/e.c.h.o-mac/blob/main/src/voice/listener.ts): `src/voice/listener.ts`
- [Configuration](https://github.com/thedeepakreddy/e.c.h.o-mac/blob/main/src/config.ts): `src/config.ts`
- [Progress and results](https://github.com/thedeepakreddy/e.c.h.o-mac/blob/main/src/control-panel.ts): `src/control-panel.ts`

### Agent execution

- [Model selection](https://github.com/thedeepakreddy/e.c.h.o-mac/blob/main/src/brain/index.ts): `src/brain/index.ts`
- [Tool routing](https://github.com/thedeepakreddy/e.c.h.o-mac/blob/main/src/brain/tool-router.ts): `src/brain/tool-router.ts`
- [Recorded agent loop](https://github.com/thedeepakreddy/e.c.h.o-mac/blob/main/src/agent-replay/runtime.ts): `src/agent-replay/runtime.ts`
- [Loop log](https://github.com/thedeepakreddy/e.c.h.o-mac/blob/main/src/agent-replay/loop-log.ts): `src/agent-replay/loop-log.ts`
- [Run recorder](https://github.com/thedeepakreddy/e.c.h.o-mac/blob/main/src/agent-replay/recorder.ts): `src/agent-replay/recorder.ts`
- [Run recovery](https://github.com/thedeepakreddy/e.c.h.o-mac/blob/main/src/agent-replay/recovery.ts): `src/agent-replay/recovery.ts`

### Task capabilities

- [Supervised tasks](https://github.com/thedeepakreddy/e.c.h.o-mac/blob/main/src/tasks/supervisor.ts): `src/tasks/supervisor.ts`
- [Coding workflow](https://github.com/thedeepakreddy/e.c.h.o-mac/blob/main/src/coding/session.ts): `src/coding/session.ts`
- [Managed processes](https://github.com/thedeepakreddy/e.c.h.o-mac/blob/main/src/coding/processes.ts): `src/coding/processes.ts`
- [Research](https://github.com/thedeepakreddy/e.c.h.o-mac/blob/main/src/frontier/research.ts): `src/frontier/research.ts`
- [Desktop controls](https://github.com/thedeepakreddy/e.c.h.o-mac/blob/main/src/tools/computer-actions.ts): `src/tools/computer-actions.ts`
- [Phone companion](https://github.com/thedeepakreddy/e.c.h.o-mac/blob/main/src/control-companion.ts): `src/control-companion.ts`

### Memory and evidence

- [Memory service](https://github.com/thedeepakreddy/e.c.h.o-mac/blob/main/src/memory/service.ts): `src/memory/service.ts`
- [Task state](https://github.com/thedeepakreddy/e.c.h.o-mac/blob/main/src/memory/task-state.ts): `src/memory/task-state.ts`
- [Episodic cognition](https://github.com/thedeepakreddy/e.c.h.o-mac/blob/main/src/cognition/episodic.ts): `src/cognition/episodic.ts`
- [Data paths](https://github.com/thedeepakreddy/e.c.h.o-mac/blob/main/src/memory/paths.ts): `src/memory/paths.ts`
- [Voice log](https://github.com/thedeepakreddy/e.c.h.o-mac/blob/main/src/voice/voice-log.ts): `src/voice/voice-log.ts`
- [Storage budget](https://github.com/thedeepakreddy/e.c.h.o-mac/blob/main/src/diagnostics/storage-budget.ts): `src/diagnostics/storage-budget.ts`
- [Secret redaction](https://github.com/thedeepakreddy/e.c.h.o-mac/blob/main/src/safety/redact.ts): `src/safety/redact.ts`

### External integrations

- **Model providers**
- **macOS apps**
- **Companion phone**

### Other components

- **User**

## Connections

- User → Voice input/output: speaks to
- User → App runtime: types request
- Voice input/output → App runtime: submits request (evidence: `src/main.ts`)
- App runtime → Model selection: creates brain (evidence: `src/main.ts`)
- Model selection → Model providers: queries provider (evidence: `src/brain/index.ts`)
- App runtime → Tool routing: routes tools (evidence: `src/main.ts`)
- Model selection → Recorded agent loop: wraps provider (evidence: `src/brain/index.ts`)
- Recorded agent loop → Run recorder: records runs (evidence: `src/agent-replay/runtime.ts`)
- Recorded agent loop → Loop log: logs iterations (evidence: `src/agent-replay/runtime.ts`)
- Recorded agent loop → Run recovery: uses recovery (evidence: `src/agent-replay/runtime.ts`)
- Tool routing → Coding workflow: selects coding tools (evidence: `src/brain/tool-router.ts`)
- App runtime → Supervised tasks: starts tasks (evidence: `src/main.ts`)
- Coding workflow → Managed processes: manages commands (evidence: `src/coding/processes.ts`)
- Tool routing → Desktop controls: dispatches controls
- Tool routing → Research: routes research (evidence: `src/brain/tool-router.ts`)
- App runtime → Phone companion: wires companion (evidence: `src/main.ts`)
- Phone companion → Companion phone: sends updates
- App runtime → Configuration: loads settings (evidence: `src/main.ts`)
- Recorded agent loop → Task state: persists task state (evidence: `src/agent-replay/runtime.ts`)
- Model selection → Episodic cognition: loads prompt facts
- Memory service → Data paths: uses data paths (evidence: `src/memory/service.ts`)
- App runtime → Memory service: wires memory (evidence: `src/main.ts`)
- Run recorder → Secret redaction: redacts records (evidence: `src/agent-replay/recorder.ts`)
- Run recorder → Storage budget: checks write budget (evidence: `src/agent-replay/recorder.ts`)
- Voice input/output → Voice log: logs voice
- Voice log → Storage budget: checks budget (evidence: `src/voice/voice-log.ts`)
- App runtime → Progress and results: exposes progress
- Progress and results → User: presents results
- Desktop controls → macOS apps: acts on apps