# ai-timon/timon architecture

> Architecture diagram of the GitHub repository ai-timon/timon, 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/ai-timon/timon
- Repository: https://github.com/ai-timon/timon

## Overview

Timon is a self-hosted AI agent-team product: a user describes work, the orchestrator plans and dispatches it to agents using CLI-backed models, and the team produces reviewed code while requesting approval for consequential actions. The cockpit exposes missions, tasks, and agent status. Separate branches cover scheduled automation, extensibility, browser and voice features, and desktop operation. README statements support the user workflow and major capabilities; sampled source excerpts support selected internal calls. Unshown wiring is omitted.

Main entry points: [`app/src/app/chat/chat-client.tsx`](https://github.com/ai-timon/timon/blob/main/app/src/app/chat/chat-client.tsx) (Timon cockpit), [`orchestrator/src/agent.ts`](https://github.com/ai-timon/timon/blob/main/orchestrator/src/agent.ts) (Orchestrator), [`app/src/components/mascot/three/sim.ts`](https://github.com/ai-timon/timon/blob/main/app/src/components/mascot/three/sim.ts) (Mascot simulation), [`orchestrator/src/db.ts`](https://github.com/ai-timon/timon/blob/main/orchestrator/src/db.ts) (Persistent state)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_cockpit["Timon cockpit<br/>[chat-client.tsx]"]
  node_mission["Missions and Kanban"]
  node_approval["Human approvals<br/>[route.ts]"]
end

subgraph group_execution["Agent execution"]
  node_orchestrator["Orchestrator<br/>[agent.ts]"]
  node_agentconfig["Agent roles and config<br/>[agent-config.ts]"]
  node_backend["Model backends<br/>[engine.ts]"]
  node_kanban["Task pipelines<br/>[pipelines.ts]"]
  node_missionroutes["Mission API<br/>[routes.ts]"]
  node_state[("Persistent state<br/>[db.ts]")]
end

subgraph group_automation["Automation and extensions"]
  node_workflow["Workflow engine<br/>[engine.ts]"]
  node_triggers["Triggers and routines<br/>[engine.ts]"]
  node_pluginfacade["Plugin pipeline API"]
  node_agentimport["Agent import<br/>[engine.ts]"]
end

subgraph group_runtime["Desktop and integrations"]
  node_browser["Isolated mission browser<br/>[browser-island.tsx]"]
  node_desktop["Desktop service<br/>[main.ts]"]
end

subgraph group_voice["Voice and interface assets"]
  node_dictation["Dictation recognition"]
  node_localengine["Local speech engine<br/>[local-engine.ts]"]
  node_speechhost["Speech process host"]
  node_mascot["Mascot renderer<br/>[engine.ts]"]
  node_mascotsim["Mascot simulation<br/>[sim.ts]"]
  node_mascotdata["Mascot model data<br/>[model-data.ts]"]
  node_mascoteyes["Mascot eyes<br/>[eyes.ts]"]
  node_mascotgeometry["Mascot geometry<br/>[mascot-geometry.ts]"]
  node_mascotstates["Mascot states<br/>[mascot-states.ts]"]
end

node_user(("User"))
node_cli{{"Provider CLIs"}}

node_user -->|"describes work"| node_cockpit
node_cockpit -->|"submits mission"| node_orchestrator
node_orchestrator -->|"selects roles"| node_agentconfig
node_orchestrator -->|"dispatches tasks"| node_kanban
node_orchestrator -.->|"runs agents"| node_backend
node_backend -->|"invokes provider"| node_cli
node_orchestrator -.->|"serves missions"| node_missionroutes
node_missionroutes -.->|"persists mission data"| node_state
node_cockpit -->|"follows task progress"| node_mission
node_orchestrator -->|"requests approval"| node_approval
node_workflow -->|"reads run state"| node_state
node_workflow -.->|"executes plugin node"| node_pluginfacade
node_triggers -->|"loads trigger"| node_state
node_pluginfacade -->|"runs pipeline"| node_kanban
node_agentimport -.->|"imports agent setup"| node_cockpit
node_cockpit -->|"uses mission browser"| node_browser
node_desktop -.->|"hosts interface"| node_cockpit
node_cockpit -->|"dictates request"| node_dictation
node_dictation -.->|"selects local engine"| node_localengine
node_localengine -->|"uses desktop speech"| node_speechhost
node_mascot -->|"decodes model data"| node_mascotdata
node_mascot -.->|"renders simulation"| node_mascotsim
node_mascotsim -->|"uses geometry"| node_mascotgeometry
node_mascotsim -->|"uses state definitions"| node_mascotstates
node_mascotsim -->|"uses eye behavior"| node_mascoteyes

click node_cockpit "https://github.com/ai-timon/timon/blob/main/app/src/app/chat/chat-client.tsx"
click node_mission "https://github.com/ai-timon/timon/blob/main/app/src/app/(main)/missions/missions-client.tsx"
click node_approval "https://github.com/ai-timon/timon/blob/main/app/src/app/api/ui/permissions/route.ts"
click node_orchestrator "https://github.com/ai-timon/timon/blob/main/orchestrator/src/agent.ts"
click node_agentconfig "https://github.com/ai-timon/timon/blob/main/orchestrator/src/agent-config.ts"
click node_backend "https://github.com/ai-timon/timon/blob/main/orchestrator/src/backends/engine/engine.ts"
click node_kanban "https://github.com/ai-timon/timon/blob/main/orchestrator/src/pipelines.ts"
click node_missionroutes "https://github.com/ai-timon/timon/blob/main/orchestrator/src/plugins-bundled/missions/routes.ts"
click node_state "https://github.com/ai-timon/timon/blob/main/orchestrator/src/db.ts"
click node_workflow "https://github.com/ai-timon/timon/blob/main/orchestrator/src/workflows/engine.ts"
click node_triggers "https://github.com/ai-timon/timon/blob/main/orchestrator/src/triggers/engine.ts"
click node_pluginfacade "https://github.com/ai-timon/timon/blob/main/orchestrator/src/plugins/pipelines-facade.ts"
click node_agentimport "https://github.com/ai-timon/timon/blob/main/plugins/agent-import/src/engine.ts"
click node_browser "https://github.com/ai-timon/timon/blob/main/app/src/components/browser-island.tsx"
click node_desktop "https://github.com/ai-timon/timon/blob/main/desktop/src/main.ts"
click node_dictation "https://github.com/ai-timon/timon/blob/main/app/src/lib/dictation/engine-recognition.ts"
click node_localengine "https://github.com/ai-timon/timon/blob/main/app/src/plugins-client/local-dictation/local-engine.ts"
click node_speechhost "https://github.com/ai-timon/timon/blob/main/desktop/src/speech-engine-host.ts"
click node_mascot "https://github.com/ai-timon/timon/blob/main/app/src/components/mascot/three/engine.ts"
click node_mascotsim "https://github.com/ai-timon/timon/blob/main/app/src/components/mascot/three/sim.ts"
click node_mascotdata "https://github.com/ai-timon/timon/blob/main/app/src/components/mascot/three/model-data.ts"
click node_mascoteyes "https://github.com/ai-timon/timon/blob/main/app/src/components/mascot/three/eyes.ts"
click node_mascotgeometry "https://github.com/ai-timon/timon/blob/main/app/src/components/mascot/mascot-geometry.ts"
click node_mascotstates "https://github.com/ai-timon/timon/blob/main/app/src/components/mascot/mascot-states.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_cockpit,node_mission,node_approval,node_user toneBlue
class node_orchestrator,node_agentconfig,node_backend,node_kanban,node_missionroutes,node_state toneAmber
class node_workflow,node_triggers,node_pluginfacade,node_agentimport toneMint
class node_browser,node_desktop toneRose
class node_dictation,node_localengine,node_speechhost,node_mascot,node_mascotsim,node_mascotdata,node_mascoteyes,node_mascotgeometry,node_mascotstates,node_cli toneIndigo
```

## Components

### User experience

- [Timon cockpit](https://github.com/ai-timon/timon/blob/main/app/src/app/chat/chat-client.tsx): `app/src/app/chat/chat-client.tsx`
- [Missions and Kanban](https://github.com/ai-timon/timon/blob/main/app/src/app/(main)/missions/missions-client.tsx): `app/src/app/(main)/missions/missions-client.tsx`
- [Human approvals](https://github.com/ai-timon/timon/blob/main/app/src/app/api/ui/permissions/route.ts): `app/src/app/api/ui/permissions/route.ts`

### Agent execution

- [Orchestrator](https://github.com/ai-timon/timon/blob/main/orchestrator/src/agent.ts): `orchestrator/src/agent.ts`
- [Agent roles and config](https://github.com/ai-timon/timon/blob/main/orchestrator/src/agent-config.ts): `orchestrator/src/agent-config.ts`
- [Model backends](https://github.com/ai-timon/timon/blob/main/orchestrator/src/backends/engine/engine.ts): `orchestrator/src/backends/engine/engine.ts`
- [Task pipelines](https://github.com/ai-timon/timon/blob/main/orchestrator/src/pipelines.ts): `orchestrator/src/pipelines.ts`
- [Mission API](https://github.com/ai-timon/timon/blob/main/orchestrator/src/plugins-bundled/missions/routes.ts): `orchestrator/src/plugins-bundled/missions/routes.ts`
- [Persistent state](https://github.com/ai-timon/timon/blob/main/orchestrator/src/db.ts): `orchestrator/src/db.ts`

### Automation and extensions

- [Workflow engine](https://github.com/ai-timon/timon/blob/main/orchestrator/src/workflows/engine.ts): `orchestrator/src/workflows/engine.ts`
- [Triggers and routines](https://github.com/ai-timon/timon/blob/main/orchestrator/src/triggers/engine.ts): `orchestrator/src/triggers/engine.ts`
- [Plugin pipeline API](https://github.com/ai-timon/timon/blob/main/orchestrator/src/plugins/pipelines-facade.ts): `orchestrator/src/plugins/pipelines-facade.ts`
- [Agent import](https://github.com/ai-timon/timon/blob/main/plugins/agent-import/src/engine.ts): `plugins/agent-import/src/engine.ts`

### Desktop and integrations

- [Isolated mission browser](https://github.com/ai-timon/timon/blob/main/app/src/components/browser-island.tsx): `app/src/components/browser-island.tsx`
- [Desktop service](https://github.com/ai-timon/timon/blob/main/desktop/src/main.ts): `desktop/src/main.ts`

### Voice and interface assets

- [Dictation recognition](https://github.com/ai-timon/timon/blob/main/app/src/lib/dictation/engine-recognition.ts): `app/src/lib/dictation/engine-recognition.ts`
- [Local speech engine](https://github.com/ai-timon/timon/blob/main/app/src/plugins-client/local-dictation/local-engine.ts): `app/src/plugins-client/local-dictation/local-engine.ts`
- [Speech process host](https://github.com/ai-timon/timon/blob/main/desktop/src/speech-engine-host.ts): `desktop/src/speech-engine-host.ts`
- [Mascot renderer](https://github.com/ai-timon/timon/blob/main/app/src/components/mascot/three/engine.ts): `app/src/components/mascot/three/engine.ts`
- [Mascot simulation](https://github.com/ai-timon/timon/blob/main/app/src/components/mascot/three/sim.ts): `app/src/components/mascot/three/sim.ts`
- [Mascot model data](https://github.com/ai-timon/timon/blob/main/app/src/components/mascot/three/model-data.ts): `app/src/components/mascot/three/model-data.ts`
- [Mascot eyes](https://github.com/ai-timon/timon/blob/main/app/src/components/mascot/three/eyes.ts): `app/src/components/mascot/three/eyes.ts`
- [Mascot geometry](https://github.com/ai-timon/timon/blob/main/app/src/components/mascot/mascot-geometry.ts): `app/src/components/mascot/mascot-geometry.ts`
- [Mascot states](https://github.com/ai-timon/timon/blob/main/app/src/components/mascot/mascot-states.ts): `app/src/components/mascot/mascot-states.ts`

### Other components

- **User**
- **Provider CLIs**

## Connections

- User → Timon cockpit: describes work (evidence: `README.md`)
- Timon cockpit → Orchestrator: submits mission (evidence: `README.md`)
- Orchestrator → Agent roles and config: selects roles (evidence: `README.md`)
- Orchestrator → Task pipelines: dispatches tasks (evidence: `README.md`)
- Orchestrator → Model backends: runs agents
- Model backends → Provider CLIs: invokes provider (evidence: `README.md`)
- Orchestrator → Mission API: serves missions
- Mission API → Persistent state: persists mission data
- Timon cockpit → Missions and Kanban: follows task progress (evidence: `README.md`)
- Orchestrator → Human approvals: requests approval (evidence: `README.md`)
- Workflow engine → Persistent state: reads run state (evidence: `orchestrator/src/workflows/engine.ts`)
- Workflow engine → Plugin pipeline API: executes plugin node
- Triggers and routines → Persistent state: loads trigger (evidence: `orchestrator/src/triggers/engine.ts`)
- Plugin pipeline API → Task pipelines: runs pipeline (evidence: `orchestrator/src/plugins/pipelines-facade.ts`)
- Agent import → Timon cockpit: imports agent setup
- Timon cockpit → Isolated mission browser: uses mission browser (evidence: `README.md`)
- Desktop service → Timon cockpit: hosts interface
- Timon cockpit → Dictation recognition: dictates request (evidence: `README.md`)
- Dictation recognition → Local speech engine: selects local engine
- Local speech engine → Speech process host: uses desktop speech (evidence: `app/src/plugins-client/local-dictation/local-engine.ts`)
- Mascot renderer → Mascot model data: decodes model data (evidence: `app/src/components/mascot/three/engine.ts`)
- Mascot renderer → Mascot simulation: renders simulation (evidence: `app/src/components/mascot/three/engine.ts`)
- Mascot simulation → Mascot geometry: uses geometry (evidence: `app/src/components/mascot/three/sim.ts`)
- Mascot simulation → Mascot states: uses state definitions (evidence: `app/src/components/mascot/three/sim.ts`)
- Mascot simulation → Mascot eyes: uses eye behavior (evidence: `app/src/components/mascot/three/sim.ts`)
