# orkas-ai/orkas architecture

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

- Interactive diagram: https://gitdiagram.com/orkas-ai/orkas
- Repository: https://github.com/orkas-ai/orkas

## Overview

Orkas is a local-first, multi-agent desktop app: a user describes a goal in chat, the Commander coordinates work across agents and tools, and the app returns files and other results on the user’s machine. The graph highlights that workflow plus connectors, marketplace skills, and office/media capabilities documented in the README. Several feature modules are present in the tree but were not sampled; their links are included only where the README documents the relationship, and the excerpts do not establish detailed renderer-to-main wiring.

Main entry points: [`src/main/features/agents.ts`](https://github.com/orkas-ai/orkas/blob/main/src/main/features/agents.ts) (Agent management), [`src/core-agent/src/agent/session.ts`](https://github.com/orkas-ai/orkas/blob/main/src/core-agent/src/agent/session.ts) (Agent session), [`src/main/features/group_chat/router.ts`](https://github.com/orkas-ai/orkas/blob/main/src/main/features/group_chat/router.ts) (Group chat), [`src/main/model/core-agent/client.ts`](https://github.com/orkas-ai/orkas/blob/main/src/main/model/core-agent/client.ts) (Model client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_coordination["Chat and coordination"]
  node_chat["Group chat<br/>[router.ts]"]
  node_agent_host["Agent management<br/>[agents.ts]"]
end

subgraph group_agent_runtime["Agent runtime"]
  node_agent_client["Model client<br/>[client.ts]"]
  node_session["Agent session<br/>[session.ts]"]
  node_tool_defs["Tool definitions<br/>[base.ts]"]
  node_local_agents["Local agent sessions<br/>[runner.ts]"]
  node_skills["Skills and memory<br/>[skills.ts]"]
end

subgraph group_capabilities["Tools and integrations"]
  node_connectors["Connector manager<br/>[manager.ts]"]
  node_connector_catalog["Connector catalog<br/>[catalog.ts]"]
  node_marketplace["Agent marketplace<br/>[marketplace.ts]"]
  node_auto_tasks["Recurring tasks<br/>[auto_tasks.ts]"]
  node_knowledge["Knowledge base<br/>[kb_indexer.ts]"]
  node_web_apps["Web apps<br/>[runtime.ts]"]
end

subgraph group_deliverables["Local data and deliverables"]
  node_office["Office engine<br/>[office_engine.ts]"]
  node_video["Video studio<br/>[video_studio.ts]"]
  node_image["Image studio<br/>[image_studio.ts]"]
  node_storage[("Local persistence<br/>[storage.ts]")]
  node_paths["User data layout<br/>[paths.ts]"]
end

node_user(("Desktop user"))
node_provider(("Model provider"))
node_filesystem[("User files")]

node_user -->|"describes goal"| node_chat
node_chat -->|"coordinates agents"| node_agent_host
node_chat -->|"persists conversation"| node_storage
node_agent_host -.->|"starts model run"| node_agent_client
node_agent_client -->|"builds runner"| node_session
node_session -->|"uses tools"| node_tool_defs
node_agent_client -->|"sends model requests"| node_provider
node_agent_host -->|"uses skills and memory"| node_skills
node_agent_host -->|"coordinates local agents"| node_local_agents
node_agent_host -->|"offers agents"| node_marketplace
node_session -.->|"uses integrations"| node_connectors
node_connectors -->|"resolves catalog"| node_connector_catalog
node_chat -.->|"schedules recurring work"| node_auto_tasks
node_session -.->|"searches documents"| node_knowledge
node_session -.->|"uses local apps"| node_web_apps
node_agent_host -->|"creates office files"| node_office
node_agent_host -->|"drives video work"| node_video
node_agent_host -->|"creates images"| node_image
node_office -->|"reads and writes files"| node_filesystem
node_video -->|"delivers video files"| node_filesystem
node_image -->|"delivers image files"| node_filesystem
node_storage -->|"uses data paths"| node_paths
node_storage -->|"stores local data"| node_filesystem
node_user -->|"receives results"| node_filesystem

click node_chat "https://github.com/orkas-ai/orkas/blob/main/src/main/features/group_chat/router.ts"
click node_agent_host "https://github.com/orkas-ai/orkas/blob/main/src/main/features/agents.ts"
click node_agent_client "https://github.com/orkas-ai/orkas/blob/main/src/main/model/core-agent/client.ts"
click node_session "https://github.com/orkas-ai/orkas/blob/main/src/core-agent/src/agent/session.ts"
click node_tool_defs "https://github.com/orkas-ai/orkas/blob/main/src/core-agent/src/tools/base.ts"
click node_local_agents "https://github.com/orkas-ai/orkas/blob/main/src/main/features/local_agents/runner.ts"
click node_skills "https://github.com/orkas-ai/orkas/blob/main/src/main/features/skills.ts"
click node_connectors "https://github.com/orkas-ai/orkas/blob/main/src/main/features/connectors/manager.ts"
click node_connector_catalog "https://github.com/orkas-ai/orkas/blob/main/src/main/features/connectors/catalog.ts"
click node_marketplace "https://github.com/orkas-ai/orkas/blob/main/src/main/features/marketplace.ts"
click node_auto_tasks "https://github.com/orkas-ai/orkas/blob/main/src/main/features/auto_tasks.ts"
click node_knowledge "https://github.com/orkas-ai/orkas/blob/main/src/main/features/kb_indexer.ts"
click node_web_apps "https://github.com/orkas-ai/orkas/blob/main/src/main/features/web_apps/runtime.ts"
click node_office "https://github.com/orkas-ai/orkas/blob/main/src/main/features/office/office_engine.ts"
click node_video "https://github.com/orkas-ai/orkas/blob/main/src/main/features/video_studio.ts"
click node_image "https://github.com/orkas-ai/orkas/blob/main/src/main/features/image_studio.ts"
click node_storage "https://github.com/orkas-ai/orkas/blob/main/src/main/storage.ts"
click node_paths "https://github.com/orkas-ai/orkas/blob/main/src/main/paths.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_chat,node_agent_host,node_user toneBlue
class node_agent_client,node_session,node_tool_defs,node_local_agents,node_skills,node_filesystem toneAmber
class node_connectors,node_connector_catalog,node_marketplace,node_auto_tasks,node_knowledge,node_web_apps toneMint
class node_office,node_video,node_image,node_storage,node_paths toneRose
class node_provider toneIndigo
```

## Components

### Chat and coordination

- [Group chat](https://github.com/orkas-ai/orkas/blob/main/src/main/features/group_chat/router.ts): `src/main/features/group_chat/router.ts`
- [Agent management](https://github.com/orkas-ai/orkas/blob/main/src/main/features/agents.ts): `src/main/features/agents.ts`

### Agent runtime

- [Model client](https://github.com/orkas-ai/orkas/blob/main/src/main/model/core-agent/client.ts): `src/main/model/core-agent/client.ts`
- [Agent session](https://github.com/orkas-ai/orkas/blob/main/src/core-agent/src/agent/session.ts): `src/core-agent/src/agent/session.ts`
- [Tool definitions](https://github.com/orkas-ai/orkas/blob/main/src/core-agent/src/tools/base.ts): `src/core-agent/src/tools/base.ts`
- [Local agent sessions](https://github.com/orkas-ai/orkas/blob/main/src/main/features/local_agents/runner.ts): `src/main/features/local_agents/runner.ts`
- [Skills and memory](https://github.com/orkas-ai/orkas/blob/main/src/main/features/skills.ts): `src/main/features/skills.ts`

### Tools and integrations

- [Connector manager](https://github.com/orkas-ai/orkas/blob/main/src/main/features/connectors/manager.ts): `src/main/features/connectors/manager.ts`
- [Connector catalog](https://github.com/orkas-ai/orkas/blob/main/src/main/features/connectors/catalog.ts): `src/main/features/connectors/catalog.ts`
- [Agent marketplace](https://github.com/orkas-ai/orkas/blob/main/src/main/features/marketplace.ts): `src/main/features/marketplace.ts`
- [Recurring tasks](https://github.com/orkas-ai/orkas/blob/main/src/main/features/auto_tasks.ts): `src/main/features/auto_tasks.ts`
- [Knowledge base](https://github.com/orkas-ai/orkas/blob/main/src/main/features/kb_indexer.ts): `src/main/features/kb_indexer.ts`
- [Web apps](https://github.com/orkas-ai/orkas/blob/main/src/main/features/web_apps/runtime.ts): `src/main/features/web_apps/runtime.ts`

### Local data and deliverables

- [Office engine](https://github.com/orkas-ai/orkas/blob/main/src/main/features/office/office_engine.ts): `src/main/features/office/office_engine.ts`
- [Video studio](https://github.com/orkas-ai/orkas/blob/main/src/main/features/video_studio.ts): `src/main/features/video_studio.ts`
- [Image studio](https://github.com/orkas-ai/orkas/blob/main/src/main/features/image_studio.ts): `src/main/features/image_studio.ts`
- [Local persistence](https://github.com/orkas-ai/orkas/blob/main/src/main/storage.ts): `src/main/storage.ts`
- [User data layout](https://github.com/orkas-ai/orkas/blob/main/src/main/paths.ts): `src/main/paths.ts`

### Other components

- **Desktop user**
- **Model provider**
- **User files**

## Connections

- Desktop user → Group chat: describes goal (evidence: `README.md`)
- Group chat → Agent management: coordinates agents (evidence: `src/main/features/group_chat/router.ts`)
- Group chat → Local persistence: persists conversation (evidence: `src/main/features/group_chat/router.ts`)
- Agent management → Model client: starts model run
- Model client → Agent session: builds runner (evidence: `src/main/model/core-agent/client.ts`)
- Agent session → Tool definitions: uses tools (evidence: `src/core-agent/src/agent/session.ts`)
- Model client → Model provider: sends model requests (evidence: `README.md`)
- Agent management → Skills and memory: uses skills and memory (evidence: `src/main/features/agents.ts`)
- Agent management → Local agent sessions: coordinates local agents (evidence: `README.md`)
- Agent management → Agent marketplace: offers agents (evidence: `README.md`)
- Agent session → Connector manager: uses integrations
- Connector manager → Connector catalog: resolves catalog (evidence: `src/main/features/connectors/manager.ts`)
- Group chat → Recurring tasks: schedules recurring work
- Agent session → Knowledge base: searches documents
- Agent session → Web apps: uses local apps
- Agent management → Office engine: creates office files (evidence: `README.md`)
- Agent management → Video studio: drives video work (evidence: `README.md`)
- Agent management → Image studio: creates images (evidence: `README.md`)
- Office engine → User files: reads and writes files (evidence: `README.md`)
- Video studio → User files: delivers video files (evidence: `README.md`)
- Image studio → User files: delivers image files (evidence: `README.md`)
- Local persistence → User data layout: uses data paths (evidence: `src/main/storage.ts`)
- Local persistence → User files: stores local data (evidence: `README.md`)
- Desktop user → User files: receives results (evidence: `README.md`)