How joi-lab/ouroboros-desktop works
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: server_web.py API surface · agent.py Agent · loop.py Loop · server_entrypoint.py Entrypoint
Components 20
Desktop launcher
Native app shell and startup boundary
Python server
Backend runtime, APIs, and orchestration
- Server · Top-level backend entrypoint
server.py - Entrypoint · Creates and configures the Starlette/uvicorn runtime
ouroboros/server_entrypoint.py - API surface · Web, history, uploads, and live event endpoints
ouroboros/server_web.py - Control · Runtime state and operational control for the backend
ouroboros/server_control.py - Supervisor · Queues, workers, events, and crash recovery
supervisor/workers.py - Local data · Durable working area, logs, uploads, and embedded repo under ~/Ouroboros/
Agent core
Loop, context, memory, and safety
- Agent · Coordinates task execution and agent state
ouroboros/agent.py - Task pipeline · Turns messages into tracked work items and continuations
ouroboros/agent_task_pipeline.py - Loop · Main iterate-call-tool-repeat execution loop
ouroboros/loop.py - LLM routing · Provider selection, pricing, and model catalog lookup
ouroboros/llm.py - Memory · Persistent identity and long-term memory store
ouroboros/memory.py - Context · Context assembly and compaction for prompts
ouroboros/context.py - Safety · Runtime mode, tool policy, and destructive-action guardrails
ouroboros/safety.py - Tools · Auto-discovered execution surface for shell, git, browser, search, and skill tools
ouroboros/tools/registry.py - Skills · Installable behavior extensions with lifecycle and review
ouroboros/skill_loader.py - Marketplace · Fetches, verifies, and installs external skill packages
ouroboros/marketplace/install.py
Web UI
Browser client and live presentation
- Web app · Static JS client that renders chat, files, settings, logs, and marketplace views
web/app.js - Live updates · Subscribes to backend events and task progress
web/modules/ws.js
Connections 22
- 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