# renzoramosdev/tony architecture

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

- Interactive diagram: https://gitdiagram.com/renzoramosdev/tony
- Repository: https://github.com/renzoramosdev/tony

## Overview

Tony is a local personal assistant with CLI and desktop entry points. A user sends a text or voice request; Jarvis handles conversation and delegates work to Viernes, whose tool calls are mediated by Edith’s deterministic permission policy before reaching native tools or MCP connectors. Results and events return to the interface. Major documented branches include voice, clarification, verified-source responses, routines, recovery/undo, and conversation history. The workflow edges reflect README documentation; source-level wiring is shown only where the supplied excerpts or index support it.

Main entry points: [`tony/core/orchestrator/runtime.py`](https://github.com/renzoramosdev/tony/blob/main/tony/core/orchestrator/runtime.py) (Core runtime), [`tony/core/orchestrator/proxy.py`](https://github.com/renzoramosdev/tony/blob/main/tony/core/orchestrator/proxy.py) (Tool proxy), [`tony/core/orchestrator/runner.py`](https://github.com/renzoramosdev/tony/blob/main/tony/core/orchestrator/runner.py) (Viernes worker), [`tony/apps/desktop/app.py`](https://github.com/renzoramosdev/tony/blob/main/tony/apps/desktop/app.py) (Desktop app)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User interfaces"]
  node_cli["CLI<br/>[main.py]"]
  node_desktop["Desktop app<br/>[app.py]"]
  node_webui["React interface<br/>[App.tsx]"]
end

subgraph group_agents["Assistant workflow"]
  node_runtime["Core runtime<br/>[runtime.py]"]
  node_jarvis["Jarvis front agent<br/>[runner.py]"]
  node_viernes["Viernes worker<br/>[runner.py]"]
  node_claude["Claude engine<br/>[claude_engine.py]"]
  node_proxy["Tool proxy<br/>[proxy.py]"]
  node_edith["Edith policy guard<br/>[policy.py]"]
end

subgraph group_connectors["Tools and connectors"]
  node_mcp["MCP manager<br/>[manager.py]"]
  node_natives["Native tools<br/>[natives.py]"]
  node_tool_config["Tool definitions<br/>[tool_json.py]"]
  node_config["Configuration<br/>[settings.py]"]
end

subgraph group_state["Local state and recovery"]
  node_conversations[("Conversation history<br/>[history.py]")]
  node_action_journal[("Action journal<br/>[actions.py]")]
  node_task_log[("Task log<br/>[task_log.py]")]
  node_events["Core events<br/>[core_events.py]"]
end

subgraph group_capabilities["Additional capabilities"]
  node_clarification["Clarification broker<br/>[broker.py]"]
  node_evidence["Source validation<br/>[validate.py]"]
  node_voice["Voice service<br/>[service.py]"]
  node_voice_engines["Voice engines<br/>[loader.py]"]
  node_routines["Routine scheduler<br/>[scheduler.py]"]
  node_recovery["Task recovery<br/>[tasks.py]"]
end

node_user(("User"))

node_user -->|"sends request"| node_cli
node_user -->|"sends request"| node_desktop
node_cli -.->|"submits commands"| node_runtime
node_desktop -->|"starts runtime"| node_runtime
node_desktop -.->|"hosts interface"| node_webui
node_webui -->|"sends commands"| node_runtime
node_runtime -.->|"routes turns"| node_jarvis
node_jarvis -->|"delegates task"| node_viernes
node_viernes -->|"requests tool"| node_proxy
node_proxy -->|"checks permission"| node_edith
node_edith -->|"returns ruling"| node_proxy
node_proxy -->|"dispatches MCP call"| node_mcp
node_proxy -->|"dispatches native call"| node_natives
node_claude -.->|"runs agent request"| node_viernes
node_tool_config -->|"configures servers"| node_mcp
node_config -.->|"configures runtime"| node_runtime
node_runtime -->|"publishes events"| node_events
node_events -->|"updates interface"| node_webui
node_runtime -->|"stores conversations"| node_conversations
node_proxy -->|"journals actions"| node_action_journal
node_runtime -->|"records task events"| node_task_log
node_viernes -->|"asks user"| node_clarification
node_viernes -->|"validates citations"| node_evidence
node_desktop -->|"creates voice service"| node_voice
node_voice -->|"loads engines"| node_voice_engines
node_voice -->|"provides spoken input"| node_jarvis
node_routines -->|"starts routine task"| node_viernes
node_recovery -->|"reads action records"| node_action_journal

click node_cli "https://github.com/renzoramosdev/tony/blob/main/tony/apps/cli/main.py"
click node_desktop "https://github.com/renzoramosdev/tony/blob/main/tony/apps/desktop/app.py"
click node_webui "https://github.com/renzoramosdev/tony/blob/main/tony/apps/desktop/web/src/App.tsx"
click node_runtime "https://github.com/renzoramosdev/tony/blob/main/tony/core/orchestrator/runtime.py"
click node_jarvis "https://github.com/renzoramosdev/tony/blob/main/tony/core/orchestrator/runner.py"
click node_viernes "https://github.com/renzoramosdev/tony/blob/main/tony/core/orchestrator/runner.py"
click node_claude "https://github.com/renzoramosdev/tony/blob/main/tony/core/orchestrator/claude_engine.py"
click node_proxy "https://github.com/renzoramosdev/tony/blob/main/tony/core/orchestrator/proxy.py"
click node_edith "https://github.com/renzoramosdev/tony/blob/main/tony/core/guard/policy.py"
click node_clarification "https://github.com/renzoramosdev/tony/blob/main/tony/core/clarification/broker.py"
click node_evidence "https://github.com/renzoramosdev/tony/blob/main/tony/core/evidence/validate.py"
click node_voice "https://github.com/renzoramosdev/tony/blob/main/tony/core/voice/service.py"
click node_voice_engines "https://github.com/renzoramosdev/tony/blob/main/tony/core/voice/engines/loader.py"
click node_routines "https://github.com/renzoramosdev/tony/blob/main/tony/core/automation/scheduler.py"
click node_recovery "https://github.com/renzoramosdev/tony/blob/main/tony/core/recovery/tasks.py"
click node_mcp "https://github.com/renzoramosdev/tony/blob/main/tony/core/mcp/manager.py"
click node_natives "https://github.com/renzoramosdev/tony/blob/main/tony/core/orchestrator/natives.py"
click node_tool_config "https://github.com/renzoramosdev/tony/blob/main/tony/core/loader/tool_json.py"
click node_config "https://github.com/renzoramosdev/tony/blob/main/tony/core/config/settings.py"
click node_conversations "https://github.com/renzoramosdev/tony/blob/main/tony/core/memory/history.py"
click node_action_journal "https://github.com/renzoramosdev/tony/blob/main/tony/core/memory/actions.py"
click node_task_log "https://github.com/renzoramosdev/tony/blob/main/tony/core/logging/task_log.py"
click node_events "https://github.com/renzoramosdev/tony/blob/main/tony/core/events/core_events.py"

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_cli,node_desktop,node_webui,node_user toneBlue
class node_runtime,node_jarvis,node_viernes,node_claude,node_proxy,node_edith toneAmber
class node_mcp,node_natives,node_tool_config,node_config toneMint
class node_conversations,node_action_journal,node_task_log,node_events toneRose
class node_clarification,node_evidence,node_voice,node_voice_engines,node_routines,node_recovery toneIndigo
```

## Components

### User interfaces

- [CLI](https://github.com/renzoramosdev/tony/blob/main/tony/apps/cli/main.py): `tony/apps/cli/main.py`
- [Desktop app](https://github.com/renzoramosdev/tony/blob/main/tony/apps/desktop/app.py): `tony/apps/desktop/app.py`
- [React interface](https://github.com/renzoramosdev/tony/blob/main/tony/apps/desktop/web/src/App.tsx): `tony/apps/desktop/web/src/App.tsx`

### Assistant workflow

- [Core runtime](https://github.com/renzoramosdev/tony/blob/main/tony/core/orchestrator/runtime.py): `tony/core/orchestrator/runtime.py`
- [Jarvis front agent](https://github.com/renzoramosdev/tony/blob/main/tony/core/orchestrator/runner.py): `tony/core/orchestrator/runner.py`
- [Viernes worker](https://github.com/renzoramosdev/tony/blob/main/tony/core/orchestrator/runner.py): `tony/core/orchestrator/runner.py`
- [Claude engine](https://github.com/renzoramosdev/tony/blob/main/tony/core/orchestrator/claude_engine.py): `tony/core/orchestrator/claude_engine.py`
- [Tool proxy](https://github.com/renzoramosdev/tony/blob/main/tony/core/orchestrator/proxy.py): `tony/core/orchestrator/proxy.py`
- [Edith policy guard](https://github.com/renzoramosdev/tony/blob/main/tony/core/guard/policy.py): `tony/core/guard/policy.py`

### Tools and connectors

- [MCP manager](https://github.com/renzoramosdev/tony/blob/main/tony/core/mcp/manager.py): `tony/core/mcp/manager.py`
- [Native tools](https://github.com/renzoramosdev/tony/blob/main/tony/core/orchestrator/natives.py): `tony/core/orchestrator/natives.py`
- [Tool definitions](https://github.com/renzoramosdev/tony/blob/main/tony/core/loader/tool_json.py): `tony/core/loader/tool_json.py`
- [Configuration](https://github.com/renzoramosdev/tony/blob/main/tony/core/config/settings.py): `tony/core/config/settings.py`

### Local state and recovery

- [Conversation history](https://github.com/renzoramosdev/tony/blob/main/tony/core/memory/history.py): `tony/core/memory/history.py`
- [Action journal](https://github.com/renzoramosdev/tony/blob/main/tony/core/memory/actions.py): `tony/core/memory/actions.py`
- [Task log](https://github.com/renzoramosdev/tony/blob/main/tony/core/logging/task_log.py): `tony/core/logging/task_log.py`
- [Core events](https://github.com/renzoramosdev/tony/blob/main/tony/core/events/core_events.py): `tony/core/events/core_events.py`

### Additional capabilities

- [Clarification broker](https://github.com/renzoramosdev/tony/blob/main/tony/core/clarification/broker.py): `tony/core/clarification/broker.py`
- [Source validation](https://github.com/renzoramosdev/tony/blob/main/tony/core/evidence/validate.py): `tony/core/evidence/validate.py`
- [Voice service](https://github.com/renzoramosdev/tony/blob/main/tony/core/voice/service.py): `tony/core/voice/service.py`
- [Voice engines](https://github.com/renzoramosdev/tony/blob/main/tony/core/voice/engines/loader.py): `tony/core/voice/engines/loader.py`
- [Routine scheduler](https://github.com/renzoramosdev/tony/blob/main/tony/core/automation/scheduler.py): `tony/core/automation/scheduler.py`
- [Task recovery](https://github.com/renzoramosdev/tony/blob/main/tony/core/recovery/tasks.py): `tony/core/recovery/tasks.py`

### Other components

- **User**

## Connections

- User → CLI: sends request
- User → Desktop app: sends request
- CLI → Core runtime: submits commands
- Desktop app → Core runtime: starts runtime (evidence: `tony/apps/desktop/app.py`)
- Desktop app → React interface: hosts interface
- React interface → Core runtime: sends commands
- Core runtime → Jarvis front agent: routes turns
- Jarvis front agent → Viernes worker: delegates task
- Viernes worker → Tool proxy: requests tool
- Tool proxy → Edith policy guard: checks permission
- Edith policy guard → Tool proxy: returns ruling
- Tool proxy → MCP manager: dispatches MCP call
- Tool proxy → Native tools: dispatches native call
- Claude engine → Viernes worker: runs agent request
- Tool definitions → MCP manager: configures servers (evidence: `tony/core/mcp/manager.py`)
- Configuration → Core runtime: configures runtime
- Core runtime → Core events: publishes events (evidence: `tony/apps/desktop/app.py`)
- Core events → React interface: updates interface
- Core runtime → Conversation history: stores conversations
- Tool proxy → Action journal: journals actions
- Core runtime → Task log: records task events (evidence: `tony/core/logging/task_log.py`)
- Viernes worker → Clarification broker: asks user
- Viernes worker → Source validation: validates citations
- Desktop app → Voice service: creates voice service (evidence: `tony/apps/desktop/app.py`)
- Voice service → Voice engines: loads engines (evidence: `tony/core/voice/service.py`)
- Voice service → Jarvis front agent: provides spoken input
- Routine scheduler → Viernes worker: starts routine task
- Task recovery → Action journal: reads action records (evidence: `tony/core/recovery/tasks.py`)
