# joi-lab/ouroboros-desktop architecture

> Architecture diagram of the GitHub repository joi-lab/ouroboros-desktop, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/joi-lab/ouroboros-desktop
- Repository: https://github.com/joi-lab/ouroboros-desktop

## Overview

1. **Overall shape**
   Ouroboros is a native desktop agent with a split runtime: a small desktop launcher starts a local Python server, and the browser-based UI talks to that server over HTTP/WebSocket. The core agent logic lives in `ouroboros/`, while `web/` is the client-side presentation layer.

2. **Process boundary**
   `launcher.py` / `ouroboros/launcher_bootstrap.py` manage the desktop app shell, while `server.py` / `ouroboros/server_entrypoint.py` start the Starlette + uvicorn backend. This separation matters: the launcher owns app/window lifecycle, restart behavior, and platform integration; the server owns API endpoints, task execution, and live UI state.

3. **Agent control plane**
   `ouroboros/agent.py`, `agent_task_pipeline.py`, `loop.py`, `loop_llm_call.py`, and `loop_tool_execution.py` form the main orchestration path. A user message or queued task becomes agent context, is routed to an LLM, tool calls are executed, results are fed back, and the task continues until completion or interruption. `task_continuation.py` and `task_results.py` handle persistence of that task lifecycle.

4. **Conversation, memory, and context**
   The agent’s persistent identity is stored under `ouroboros/memory.py`, with context assembly and trimming handled by `context.py` and `context_compaction.py`. `consolidator.py`, `reflection.py`, and `deep_self_review.py` turn task output into durable memory, patterns, and long-form self-review artifacts. This is the main continuity boundary: short-lived chat/task state is distilled into long-lived memory files.

5. **Persistent data layout**
   The app creates a local working area under `~/Ouroboros/`: a self-owned Git repo, runtime state, logs, uploads, and memory. The README’s layout is accurate for the architecture diagram: code changes happen inside the embedded repo, while chat logs, state, and knowledge live in separate durable folders.

6. **Model/provider routing**
   `ouroboros/config.py`, `llm.py`, `provider_models.py`, `pricing.py`, and `model_catalog_api.py` define model selection, provider routing, cost tracking, and catalog lookup. The system can target OpenRouter, OpenAI, OpenAI-compatible endpoints, Cloud.ru, Anthropic, and local models. A key architectural detail is that the same agent can switch providers per slot: main, code, light, fallback, review, and web-search roles are separately configured.

7. **Safety and execution policy**
   `safety.py`, `tool_policy.py`, `runtime_mode_policy.py`, and `server_auth.py` form the governance layer. Safety is not just “prompt-level”; there is a hardcoded sandbox on destructive file/git/shell behavior plus a policy-based LLM safety check for tool use. `tool_capabilities.py` and `tool_aliases.py` define what the agent is allowed to do, while the server enforces network/password gating for non-local exposure.

8. **Tooling architecture**
   Tools are auto-discovered from `ouroboros/tools/` and executed through the loop/tool-dispatch path. They cover git, shell, browser, search, memory, review, CI, PR work, health, vision, and skill execution. `tool_context.py`, `tool_abi.py`, and `tool_discovery.py` provide the contract boundary between the agent and each tool implementation.

9. **Skills and extensions**
   `ouroboros/skill_loader.py`, `skill_dependencies.py`, `skill_review.py`, `skill_lifecycle_queue.py`, and `extension_loader.py` support installable skills and plugins. Skills are a second plugin boundary beyond tools: they can contribute behavior, UI sections, and runtime dependencies, but are reviewed and gated before activation. The `skills/` directory contains built-in examples like `weather`, while marketplace-backed skills are fetched and staged through the marketplace subsystem.

10. **Marketplace and installation pipeline**
    `ouroboros/marketplace/` and `marketplace_api.py` handle browsing, fetching, provenance, and installation of skill packages from external sources such as ClawHub and OuroborosHub. This subsystem is isolated from the core agent because it has its own dependency staging, provenance tracking, and install specifications.

11. **Web API and UI flow**
    `server_web.py`, `server_runtime.py`, `server_control.py`, `server_history_api.py`, `chat_upload_api.py`, `file_browser_api.py`, and `a2a_server.py` expose the backend surface consumed by `web/`. The UI is a static JS app with feature modules for chat, settings, files, logs, dashboard, marketplace, skills, evolution, and websocket updates. Data flow is mostly server-pushed: the UI renders task progress, logs, and live cards from backend events.

12. **Supervisor and worker model**
    The `supervisor/` package is a second internal boundary for process orchestration: queues, workers, message bus, state, event tracking, and git ops. It exists to keep long-running work, restarts, and crash recovery separate from the request/response server path.

13. **External integrations**
    The notable external services are LLM providers, GitHub/GitHub CLI for PR and repo operations, Telegram for the optional bidirectional bridge, and Playwright/Chromium for browser tools. `gateways/claude_code.py` and the various `tools/github.py`, `tools/git_pr.py`, `tools/browser.py`, and `chat_upload_api.py` modules are the main integration surfaces.

14. **Build and release boundary**
    `build.sh`, `build_linux.sh`, `build_windows.ps1`, `Dockerfile`, and `scripts/build_repo_bundle.py` package the app for macOS, Linux, Windows, and Docker. The build pipeline treats the repo itself as a versioned artifact: tagged commits are bundled, and the launcher can verify the packaged source matches a real release.

15. **Where to draw the diagram boundaries**
    A clean diagram should show: desktop launcher on one side; local Python server in the middle; web UI, tools, model providers, GitHub/Telegram/local filesystem as external edges; and the persistent `~/Ouroboros/` storage layer beneath everything. The key internal subgraphs are agent loop, safety/policy, memory/context, tools, and skills/marketplace.

Main entry points: [`ouroboros/server_web.py`](https://github.com/joi-lab/ouroboros-desktop/blob/main/ouroboros/server_web.py) (API surface), [`ouroboros/agent.py`](https://github.com/joi-lab/ouroboros-desktop/blob/main/ouroboros/agent.py) (Agent), [`ouroboros/loop.py`](https://github.com/joi-lab/ouroboros-desktop/blob/main/ouroboros/loop.py) (Loop), [`ouroboros/server_entrypoint.py`](https://github.com/joi-lab/ouroboros-desktop/blob/main/ouroboros/server_entrypoint.py) (Entrypoint)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_launcher["Desktop launcher"]
  node_launcher_py["Launcher<br/>desktop entry<br/>[launcher.py]"]
  node_launcher_bootstrap["Bootstrap<br/>launcher init"]
end

subgraph group_server["Python server"]
  node_server_py["Server<br/>service entry<br/>[server.py]"]
  node_server_entrypoint["Entrypoint<br/>server boot"]
  node_server_web["API surface<br/>http/ws api<br/>[server_web.py]"]
  node_server_control["Control<br/>[server_control.py]"]
  node_supervisor["Supervisor<br/>process orchestration<br/>[workers.py]"]
  node_storage[("Local data<br/>workspace storage")]
end

subgraph group_agent["Agent core"]
  node_agent["Agent<br/>control plane<br/>[agent.py]"]
  node_pipeline["Task pipeline<br/>task orchestration"]
  node_loop["Loop<br/>[loop.py]"]
  node_llm["LLM routing<br/>model routing<br/>[llm.py]"]
  node_memory["Memory<br/>persistence<br/>[memory.py]"]
  node_context["Context<br/>[context.py]"]
  node_safety["Safety<br/>policy layer<br/>[safety.py]"]
  node_tools["Tools<br/>tool runtime<br/>[registry.py]"]
  node_skills["Skills<br/>plugin system<br/>[skill_loader.py]"]
  node_marketplace["Marketplace<br/>package intake<br/>[install.py]"]
end

subgraph group_ui["Web UI"]
  node_web_app["Web app<br/>browser client<br/>[app.js]"]
  node_ws["Live updates<br/>websocket client<br/>[ws.js]"]
end

node_launcher_py -->|"boots"| node_launcher_bootstrap
node_launcher_bootstrap -->|"starts"| node_server_py
node_server_py -->|"loads"| node_server_entrypoint
node_server_entrypoint -->|"exposes"| node_server_web
node_server_entrypoint -->|"manages"| node_server_control
node_server_control -->|"coordinates"| node_supervisor
node_server_web -->|"serves"| node_web_app
node_web_app -->|"subscribes"| node_ws
node_web_app -->|"calls"| node_server_web
node_server_web -->|"dispatches"| node_agent
node_agent -->|"orchestrates"| node_pipeline
node_pipeline -->|"drives"| node_loop
node_loop -->|"queries"| node_llm
node_loop -->|"executes"| node_tools
node_loop -->|"builds"| node_context
node_context -->|"reads/writes"| node_memory
node_agent -->|"checks"| node_safety
node_tools -->|"constrained by"| node_safety
node_agent -->|"loads"| node_skills
node_skills -->|"installs from"| node_marketplace
node_server_web -->|"persists"| node_storage
node_supervisor -->|"tracks"| node_storage

click node_launcher_py "https://github.com/joi-lab/ouroboros-desktop/blob/main/launcher.py"
click node_launcher_bootstrap "https://github.com/joi-lab/ouroboros-desktop/blob/main/ouroboros/launcher_bootstrap.py"
click node_server_py "https://github.com/joi-lab/ouroboros-desktop/blob/main/server.py"
click node_server_entrypoint "https://github.com/joi-lab/ouroboros-desktop/blob/main/ouroboros/server_entrypoint.py"
click node_server_web "https://github.com/joi-lab/ouroboros-desktop/blob/main/ouroboros/server_web.py"
click node_server_control "https://github.com/joi-lab/ouroboros-desktop/blob/main/ouroboros/server_control.py"
click node_supervisor "https://github.com/joi-lab/ouroboros-desktop/blob/main/supervisor/workers.py"
click node_agent "https://github.com/joi-lab/ouroboros-desktop/blob/main/ouroboros/agent.py"
click node_pipeline "https://github.com/joi-lab/ouroboros-desktop/blob/main/ouroboros/agent_task_pipeline.py"
click node_loop "https://github.com/joi-lab/ouroboros-desktop/blob/main/ouroboros/loop.py"
click node_llm "https://github.com/joi-lab/ouroboros-desktop/blob/main/ouroboros/llm.py"
click node_memory "https://github.com/joi-lab/ouroboros-desktop/blob/main/ouroboros/memory.py"
click node_context "https://github.com/joi-lab/ouroboros-desktop/blob/main/ouroboros/context.py"
click node_safety "https://github.com/joi-lab/ouroboros-desktop/blob/main/ouroboros/safety.py"
click node_tools "https://github.com/joi-lab/ouroboros-desktop/blob/main/ouroboros/tools/registry.py"
click node_skills "https://github.com/joi-lab/ouroboros-desktop/blob/main/ouroboros/skill_loader.py"
click node_marketplace "https://github.com/joi-lab/ouroboros-desktop/blob/main/ouroboros/marketplace/install.py"
click node_web_app "https://github.com/joi-lab/ouroboros-desktop/blob/main/web/app.js"
click node_ws "https://github.com/joi-lab/ouroboros-desktop/blob/main/web/modules/ws.js"

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_launcher_py,node_launcher_bootstrap toneBlue
class node_server_py,node_server_entrypoint,node_server_web,node_server_control,node_supervisor,node_storage toneAmber
class node_agent,node_pipeline,node_loop,node_llm,node_memory,node_context,node_safety,node_tools,node_skills,node_marketplace toneMint
class node_web_app,node_ws toneRose
```

## Components

### Desktop launcher

Native app shell and startup boundary

- [Launcher](https://github.com/joi-lab/ouroboros-desktop/blob/main/launcher.py): desktop entry · Starts the desktop shell and hands off to the local server · `launcher.py`
- [Bootstrap](https://github.com/joi-lab/ouroboros-desktop/blob/main/ouroboros/launcher_bootstrap.py): launcher init · Platform-specific bootstrap and app lifecycle wiring · `ouroboros/launcher_bootstrap.py`

### Python server

Backend runtime, APIs, and orchestration

- [Server](https://github.com/joi-lab/ouroboros-desktop/blob/main/server.py): service entry · Top-level backend entrypoint · `server.py`
- [Entrypoint](https://github.com/joi-lab/ouroboros-desktop/blob/main/ouroboros/server_entrypoint.py): server boot · Creates and configures the Starlette/uvicorn runtime · `ouroboros/server_entrypoint.py`
- [API surface](https://github.com/joi-lab/ouroboros-desktop/blob/main/ouroboros/server_web.py): http/ws api · Web, history, uploads, and live event endpoints · `ouroboros/server_web.py`
- [Control](https://github.com/joi-lab/ouroboros-desktop/blob/main/ouroboros/server_control.py): runtime control · Runtime state and operational control for the backend · `ouroboros/server_control.py`
- [Supervisor](https://github.com/joi-lab/ouroboros-desktop/blob/main/supervisor/workers.py): process orchestration · Queues, workers, events, and crash recovery · `supervisor/workers.py`
- **Local data**: workspace storage · Durable working area, logs, uploads, and embedded repo under ~/Ouroboros/

### Agent core

Loop, context, memory, and safety

- [Agent](https://github.com/joi-lab/ouroboros-desktop/blob/main/ouroboros/agent.py): control plane · Coordinates task execution and agent state · `ouroboros/agent.py`
- [Task pipeline](https://github.com/joi-lab/ouroboros-desktop/blob/main/ouroboros/agent_task_pipeline.py): task orchestration · Turns messages into tracked work items and continuations · `ouroboros/agent_task_pipeline.py`
- [Loop](https://github.com/joi-lab/ouroboros-desktop/blob/main/ouroboros/loop.py): reason-act loop · Main iterate-call-tool-repeat execution loop · `ouroboros/loop.py`
- [LLM routing](https://github.com/joi-lab/ouroboros-desktop/blob/main/ouroboros/llm.py): model routing · Provider selection, pricing, and model catalog lookup · `ouroboros/llm.py`
- [Memory](https://github.com/joi-lab/ouroboros-desktop/blob/main/ouroboros/memory.py): persistence · Persistent identity and long-term memory store · `ouroboros/memory.py`
- [Context](https://github.com/joi-lab/ouroboros-desktop/blob/main/ouroboros/context.py): context mgmt · Context assembly and compaction for prompts · `ouroboros/context.py`
- [Safety](https://github.com/joi-lab/ouroboros-desktop/blob/main/ouroboros/safety.py): policy layer · Runtime mode, tool policy, and destructive-action guardrails · `ouroboros/safety.py`
- [Tools](https://github.com/joi-lab/ouroboros-desktop/blob/main/ouroboros/tools/registry.py): tool runtime · Auto-discovered execution surface for shell, git, browser, search, and skill tools · `ouroboros/tools/registry.py`
- [Skills](https://github.com/joi-lab/ouroboros-desktop/blob/main/ouroboros/skill_loader.py): plugin system · Installable behavior extensions with lifecycle and review · `ouroboros/skill_loader.py`
- [Marketplace](https://github.com/joi-lab/ouroboros-desktop/blob/main/ouroboros/marketplace/install.py): package intake · Fetches, verifies, and installs external skill packages · `ouroboros/marketplace/install.py`

### Web UI

Browser client and live presentation

- [Web app](https://github.com/joi-lab/ouroboros-desktop/blob/main/web/app.js): browser client · Static JS client that renders chat, files, settings, logs, and marketplace views · `web/app.js`
- [Live updates](https://github.com/joi-lab/ouroboros-desktop/blob/main/web/modules/ws.js): websocket client · Subscribes to backend events and task progress · `web/modules/ws.js`

## Connections

- Launcher → Bootstrap: boots · Desktop entry delegates startup work to bootstrap
- Bootstrap → Server: starts · Launcher brings up the local Python backend
- Server → Entrypoint: loads · Server entrypoint configures runtime and app
- Entrypoint → API surface: exposes · Backend publishes HTTP and websocket APIs
- Entrypoint → Control: manages · Operational control and runtime state are initialized
- Control → Supervisor: coordinates · Control layer hands long-running work to supervisor
- API surface → Web app: serves · Static UI and API responses feed the browser client
- Web app → Live updates: subscribes · UI listens for live task and log updates
- Web app → API surface: calls · Client fetches data and sends user actions to backend
- API surface → Agent: dispatches · Incoming chat and task requests reach the agent
- Agent → Task pipeline: orchestrates · Agent routes work into the task pipeline
- Task pipeline → Loop: drives · Pipeline enters the reason-act execution loop
- Loop → LLM routing: queries · Loop selects providers and requests model output
- Loop → Tools: executes · Loop dispatches tool calls through the tool runtime
- Loop → Context: builds · Loop assembles and trims prompt context
- Context → Memory: reads/writes · Context is grounded in persistent memory and task history
- Agent → Safety: checks · Safety policy gates tool use and risky operations
- Tools → Safety: constrained by · Tool execution is filtered by policy and capability rules
- Agent → Skills: loads · Agent can invoke skill lifecycle and extension behavior
- Skills → Marketplace: installs from · External skills are fetched and staged through marketplace
- API surface → Local data: persists · Uploads, logs, and workspace data land in local storage
- Supervisor → Local data: tracks · Worker state, events, and repo operations are recorded locally
