# vfarcic/dot-agent-deck architecture

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

- Interactive diagram: https://gitdiagram.com/vfarcic/dot-agent-deck
- Repository: https://github.com/vfarcic/dot-agent-deck

## Overview

Agent Deck is a multi-agent coding-work coordinator: a background daemon owns agent sessions while terminal and desktop clients observe and control them. Users start agents or orchestrations, route delegated work through an inbox, and can dispatch isolated worktree units or schedule prompts; agents’ activity is surfaced back through shared clients. The graph also preserves remote-daemon access, telemetry, and desktop voice control. README statements support the product-level links; source-index references support only the sampled internal links, so unsampled internals are grouped conservatively.

Main entry points: [`src/daemon.rs`](https://github.com/vfarcic/dot-agent-deck/blob/main/src/daemon.rs) (Background daemon), [`src/agent_pty.rs`](https://github.com/vfarcic/dot-agent-deck/blob/main/src/agent_pty.rs) (Agent sessions), [`desktop/src/App.tsx`](https://github.com/vfarcic/dot-agent-deck/blob/main/desktop/src/App.tsx) (Desktop app), [`src/ui.rs`](https://github.com/vfarcic/dot-agent-deck/blob/main/src/ui.rs) (Terminal UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Daemon runtime"]
  node_daemon["Background daemon<br/>[daemon.rs]"]
  node_agentpty["Agent sessions<br/>[agent_pty.rs]"]
  node_events["Agent events<br/>[event.rs]"]
  node_protocol["Daemon protocol<br/>[daemon_protocol.rs]"]
  node_probe["Terminal input probe"]
end

subgraph group_coordination["Work coordination"]
  node_orchestration["Orchestration context"]
  node_inbox["Delegation inbox<br/>[inbox.rs]"]
  node_receipts["Inbox delivery engine<br/>[inbox_engine.rs]"]
  node_dispatch["Worktree dispatch<br/>[dispatch.rs]"]
  node_schedules["Scheduled tasks<br/>[scheduler.rs]"]
end

subgraph group_clients["User clients"]
  node_tui["Terminal UI<br/>[ui.rs]"]
  node_desktop["Desktop app<br/>[App.tsx]"]
  node_desktopruntime["Desktop runtime hook<br/>[useDeckRuntime.ts]"]
  node_bridge["Desktop daemon bridge<br/>[bridge.ts]"]
  node_voice["Voice commands"]
end

subgraph group_integrations["Integrations"]
  node_remote["Remote environments<br/>[remote.rs]"]
  node_telemetry["Telemetry pipeline<br/>[mod.rs]"]
  node_hooks["Agent hooks<br/>[hook.rs]"]
end

node_user(("User"))
node_agent(("Coding agents"))
node_otel[("OTel backend")]
node_remotehost(("Remote host"))

node_user -->|"controls"| node_tui
node_user -->|"controls"| node_desktop
node_tui -->|"controls shared agents"| node_daemon
node_desktop -->|"uses runtime"| node_desktopruntime
node_desktopruntime -->|"invokes"| node_bridge
node_bridge -.->|"communicates with"| node_protocol
node_daemon -.->|"manages sessions"| node_agentpty
node_agentpty -->|"runs"| node_agent
node_agentpty -->|"reports activity"| node_events
node_daemon -.->|"serves clients"| node_protocol
node_daemon -->|"composes spawn context"| node_orchestration
node_orchestration -->|"delegates work through"| node_inbox
node_daemon -->|"owns inbox"| node_inbox
node_daemon -->|"drives delivery"| node_receipts
node_user -->|"requests isolated work"| node_dispatch
node_dispatch -->|"starts work unit"| node_agentpty
node_user -->|"sets prompt schedule"| node_schedules
node_schedules -->|"fires prompts"| node_daemon
node_tui -->|"connects over SSH"| node_remote
node_desktop -->|"shows remote agents"| node_remote
node_remote -->|"connects to"| node_remotehost
node_daemon -->|"records runs"| node_telemetry
node_telemetry -->|"exports records"| node_otel
node_agent -.->|"reports lifecycle"| node_hooks
node_desktop -->|"offers voice control"| node_voice
node_agentpty -->|"tracks terminal input"| node_probe

click node_daemon "https://github.com/vfarcic/dot-agent-deck/blob/main/src/daemon.rs"
click node_agentpty "https://github.com/vfarcic/dot-agent-deck/blob/main/src/agent_pty.rs"
click node_events "https://github.com/vfarcic/dot-agent-deck/blob/main/src/event.rs"
click node_protocol "https://github.com/vfarcic/dot-agent-deck/blob/main/src/daemon_protocol.rs"
click node_probe "https://github.com/vfarcic/dot-agent-deck/tree/main/src/composer_probe"
click node_orchestration "https://github.com/vfarcic/dot-agent-deck/blob/main/src/orchestrator_context.rs"
click node_inbox "https://github.com/vfarcic/dot-agent-deck/blob/main/src/inbox.rs"
click node_receipts "https://github.com/vfarcic/dot-agent-deck/blob/main/src/inbox_engine.rs"
click node_dispatch "https://github.com/vfarcic/dot-agent-deck/blob/main/src/dispatch.rs"
click node_schedules "https://github.com/vfarcic/dot-agent-deck/blob/main/src/scheduler.rs"
click node_tui "https://github.com/vfarcic/dot-agent-deck/blob/main/src/ui.rs"
click node_desktop "https://github.com/vfarcic/dot-agent-deck/blob/main/desktop/src/App.tsx"
click node_desktopruntime "https://github.com/vfarcic/dot-agent-deck/blob/main/desktop/src/hooks/useDeckRuntime.ts"
click node_bridge "https://github.com/vfarcic/dot-agent-deck/blob/main/desktop/src/lib/bridge.ts"
click node_voice "https://github.com/vfarcic/dot-agent-deck/tree/main/desktop/src-tauri/src/voice"
click node_remote "https://github.com/vfarcic/dot-agent-deck/blob/main/src/remote.rs"
click node_telemetry "https://github.com/vfarcic/dot-agent-deck/blob/main/src/telemetry/mod.rs"
click node_hooks "https://github.com/vfarcic/dot-agent-deck/blob/main/src/hook.rs"

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_daemon,node_agentpty,node_events,node_protocol,node_probe,node_user toneBlue
class node_orchestration,node_inbox,node_receipts,node_dispatch,node_schedules,node_otel toneAmber
class node_tui,node_desktop,node_desktopruntime,node_bridge,node_voice toneMint
class node_remote,node_telemetry,node_hooks toneRose
class node_agent,node_remotehost toneIndigo
```

## Components

### Daemon runtime

- [Background daemon](https://github.com/vfarcic/dot-agent-deck/blob/main/src/daemon.rs): `src/daemon.rs`
- [Agent sessions](https://github.com/vfarcic/dot-agent-deck/blob/main/src/agent_pty.rs): `src/agent_pty.rs`
- [Agent events](https://github.com/vfarcic/dot-agent-deck/blob/main/src/event.rs): `src/event.rs`
- [Daemon protocol](https://github.com/vfarcic/dot-agent-deck/blob/main/src/daemon_protocol.rs): `src/daemon_protocol.rs`
- [Terminal input probe](https://github.com/vfarcic/dot-agent-deck/tree/main/src/composer_probe): `src/composer_probe`

### Work coordination

- [Orchestration context](https://github.com/vfarcic/dot-agent-deck/blob/main/src/orchestrator_context.rs): `src/orchestrator_context.rs`
- [Delegation inbox](https://github.com/vfarcic/dot-agent-deck/blob/main/src/inbox.rs): `src/inbox.rs`
- [Inbox delivery engine](https://github.com/vfarcic/dot-agent-deck/blob/main/src/inbox_engine.rs): `src/inbox_engine.rs`
- [Worktree dispatch](https://github.com/vfarcic/dot-agent-deck/blob/main/src/dispatch.rs): `src/dispatch.rs`
- [Scheduled tasks](https://github.com/vfarcic/dot-agent-deck/blob/main/src/scheduler.rs): `src/scheduler.rs`

### User clients

- [Terminal UI](https://github.com/vfarcic/dot-agent-deck/blob/main/src/ui.rs): `src/ui.rs`
- [Desktop app](https://github.com/vfarcic/dot-agent-deck/blob/main/desktop/src/App.tsx): `desktop/src/App.tsx`
- [Desktop runtime hook](https://github.com/vfarcic/dot-agent-deck/blob/main/desktop/src/hooks/useDeckRuntime.ts): `desktop/src/hooks/useDeckRuntime.ts`
- [Desktop daemon bridge](https://github.com/vfarcic/dot-agent-deck/blob/main/desktop/src/lib/bridge.ts): `desktop/src/lib/bridge.ts`
- [Voice commands](https://github.com/vfarcic/dot-agent-deck/tree/main/desktop/src-tauri/src/voice): `desktop/src-tauri/src/voice`

### Integrations

- [Remote environments](https://github.com/vfarcic/dot-agent-deck/blob/main/src/remote.rs): `src/remote.rs`
- [Telemetry pipeline](https://github.com/vfarcic/dot-agent-deck/blob/main/src/telemetry/mod.rs): `src/telemetry/mod.rs`
- [Agent hooks](https://github.com/vfarcic/dot-agent-deck/blob/main/src/hook.rs): `src/hook.rs`

### Other components

- **User**
- **Coding agents**
- **OTel backend**
- **Remote host**

## Connections

- User → Terminal UI: controls
- User → Desktop app: controls
- Terminal UI → Background daemon: controls shared agents
- Desktop app → Desktop runtime hook: uses runtime (evidence: `desktop/src/App.tsx`)
- Desktop runtime hook → Desktop daemon bridge: invokes (evidence: `desktop/src/hooks/useDeckRuntime.ts`)
- Desktop daemon bridge → Daemon protocol: communicates with
- Background daemon → Agent sessions: manages sessions
- Agent sessions → Coding agents: runs
- Agent sessions → Agent events: reports activity (evidence: `src/event.rs`)
- Background daemon → Daemon protocol: serves clients
- Background daemon → Orchestration context: composes spawn context (evidence: `src/orchestrator_context.rs`)
- Orchestration context → Delegation inbox: delegates work through
- Background daemon → Delegation inbox: owns inbox (evidence: `src/inbox.rs`)
- Background daemon → Inbox delivery engine: drives delivery (evidence: `src/inbox_engine.rs`)
- User → Worktree dispatch: requests isolated work
- Worktree dispatch → Agent sessions: starts work unit
- User → Scheduled tasks: sets prompt schedule
- Scheduled tasks → Background daemon: fires prompts
- Terminal UI → Remote environments: connects over SSH
- Desktop app → Remote environments: shows remote agents
- Remote environments → Remote host: connects to
- Background daemon → Telemetry pipeline: records runs
- Telemetry pipeline → OTel backend: exports records
- Coding agents → Agent hooks: reports lifecycle
- Desktop app → Voice commands: offers voice control
- Agent sessions → Terminal input probe: tracks terminal input (evidence: `src/composer_probe/epoch.rs`)