# vibicer/xu-harness architecture

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

- Interactive diagram: https://gitdiagram.com/vibicer/xu-harness
- Repository: https://github.com/vibicer/xu-harness

## Overview

Xu is a personal AI agent harness: a Svelte web shell communicates with a Python brain daemon over one localhost WebSocket. The user’s main workflow is to compose a session turn, have the agent reason with a configured model and invoke tools, then inspect the response and agent activity in the workspace. The brain also exposes session, memory, skills, orchestration, plugin, and backup capabilities. UI and agent details are partly inferred from the README and tree; sampled excerpts confirm plugin extension points, subagent persistence, tool search, and backup behavior, but do not establish every runtime call path.

Main entry points: [`brain/xu_brain/features/agent/loop.py`](https://github.com/vibicer/xu-harness/blob/main/brain/xu_brain/features/agent/loop.py) (Agent loop), [`brain/xu_brain/features/tools`](https://github.com/vibicer/xu-harness/tree/main/brain/xu_brain/features/tools) (Tool runtime), [`web/src/lib/store.svelte.ts`](https://github.com/vibicer/xu-harness/blob/main/web/src/lib/store.svelte.ts) (UI state and RPC), [`brain/xu_brain/core/runtime.py`](https://github.com/vibicer/xu-harness/blob/main/brain/xu_brain/core/runtime.py) (Brain daemon)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_shell["Web shell"]
  node_workspace["Workspace UI<br/>[App.svelte]"]
  node_chat["Chat and sessions<br/>[Chat.svelte]"]
  node_ui_state["UI state and RPC<br/>[store.svelte.ts]"]
end

subgraph group_brain["Brain runtime"]
  node_brain_daemon["Brain daemon<br/>[runtime.py]"]
  node_websocket["WebSocket API<br/>[web.py]"]
  node_api_events["Events and context<br/>[events.py]"]
end

subgraph group_agent["Agent execution"]
  node_agent_loop["Agent loop<br/>[loop.py]"]
  node_agent_orchestration["Turn orchestration<br/>[orchestrator.py]"]
  node_model_provider["Model providers<br/>[provider.py]"]
  node_tool_runtime["Tool runtime"]
end

subgraph group_features["Product features"]
  node_session_feature["Sessions"]
  node_memory_feature["Memory"]
  node_skills_feature["Skills"]
  node_presets_feature["Presets"]
  node_backup_feature["Backup and undo<br/>[manager.py]"]
  node_backup_db[("Undo journal<br/>[manager.py]")]
  node_plugin_host["Plugin host<br/>[host.py]"]
  node_plugin_api["Plugin API<br/>[context.py]"]
  node_mcp_client["MCP client<br/>[client.py]"]
end

node_user(("User"))
node_model_service(("Model service"))
node_tool_targets(("Tool targets"))
node_mcp_server(("MCP server process"))

node_user -->|"composes turns"| node_chat
node_chat -->|"updates state"| node_ui_state
node_ui_state -->|"sends RPC"| node_websocket
node_websocket -->|"dispatches requests"| node_brain_daemon
node_brain_daemon -->|"runs agent"| node_agent_loop
node_agent_loop -->|"requests completion"| node_model_provider
node_model_provider -->|"calls model"| node_model_service
node_agent_loop -->|"invokes tools"| node_tool_runtime
node_tool_runtime -->|"accesses resources"| node_tool_targets
node_agent_loop -->|"delegates subagents"| node_agent_orchestration
node_agent_loop -->|"uses sessions"| node_session_feature
node_agent_loop -->|"uses memory"| node_memory_feature
node_agent_loop -->|"uses skills"| node_skills_feature
node_agent_loop -->|"uses presets"| node_presets_feature
node_tool_runtime -->|"backs up mutations"| node_backup_feature
node_backup_feature -->|"journals snapshots"| node_backup_db
node_brain_daemon -->|"loads plugins"| node_plugin_host
node_plugin_host -->|"provides context"| node_plugin_api
node_tool_runtime -.->|"bridges tools"| node_mcp_client
node_mcp_client -.->|"speaks stdio"| node_mcp_server
node_websocket -->|"streams events"| node_ui_state
node_ui_state -->|"updates transcript"| node_chat

click node_workspace "https://github.com/vibicer/xu-harness/blob/main/web/src/App.svelte"
click node_chat "https://github.com/vibicer/xu-harness/blob/main/web/src/lib/components/Chat.svelte"
click node_ui_state "https://github.com/vibicer/xu-harness/blob/main/web/src/lib/store.svelte.ts"
click node_brain_daemon "https://github.com/vibicer/xu-harness/blob/main/brain/xu_brain/core/runtime.py"
click node_websocket "https://github.com/vibicer/xu-harness/blob/main/brain/xu_brain/core/web.py"
click node_api_events "https://github.com/vibicer/xu-harness/blob/main/brain/xu_brain/api/events.py"
click node_agent_loop "https://github.com/vibicer/xu-harness/blob/main/brain/xu_brain/features/agent/loop.py"
click node_agent_orchestration "https://github.com/vibicer/xu-harness/blob/main/brain/xu_brain/features/agent/orchestrator.py"
click node_model_provider "https://github.com/vibicer/xu-harness/blob/main/brain/xu_brain/features/agent/provider.py"
click node_tool_runtime "https://github.com/vibicer/xu-harness/tree/main/brain/xu_brain/features/tools"
click node_session_feature "https://github.com/vibicer/xu-harness/tree/main/brain/xu_brain/features/session"
click node_memory_feature "https://github.com/vibicer/xu-harness/tree/main/brain/xu_brain/features/memory"
click node_skills_feature "https://github.com/vibicer/xu-harness/tree/main/brain/xu_brain/features/skills"
click node_presets_feature "https://github.com/vibicer/xu-harness/tree/main/brain/xu_brain/features/presets"
click node_backup_feature "https://github.com/vibicer/xu-harness/blob/main/brain/xu_brain/features/backup/manager.py"
click node_backup_db "https://github.com/vibicer/xu-harness/blob/main/brain/xu_brain/features/backup/manager.py"
click node_plugin_host "https://github.com/vibicer/xu-harness/blob/main/brain/xu_brain/core/host.py"
click node_plugin_api "https://github.com/vibicer/xu-harness/blob/main/brain/xu_brain/api/context.py"
click node_mcp_client "https://github.com/vibicer/xu-harness/blob/main/brain/xu_brain/plugins/builtin/mcp/client.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_workspace,node_chat,node_ui_state,node_user toneBlue
class node_brain_daemon,node_websocket,node_api_events toneAmber
class node_agent_loop,node_agent_orchestration,node_model_provider,node_tool_runtime,node_mcp_server toneMint
class node_session_feature,node_memory_feature,node_skills_feature,node_presets_feature,node_backup_feature,node_backup_db,node_plugin_host,node_plugin_api,node_mcp_client toneRose
class node_model_service,node_tool_targets toneIndigo
```

## Components

### Web shell

- [Workspace UI](https://github.com/vibicer/xu-harness/blob/main/web/src/App.svelte): `web/src/App.svelte`
- [Chat and sessions](https://github.com/vibicer/xu-harness/blob/main/web/src/lib/components/Chat.svelte): `web/src/lib/components/Chat.svelte`
- [UI state and RPC](https://github.com/vibicer/xu-harness/blob/main/web/src/lib/store.svelte.ts): `web/src/lib/store.svelte.ts`

### Brain runtime

- [Brain daemon](https://github.com/vibicer/xu-harness/blob/main/brain/xu_brain/core/runtime.py): `brain/xu_brain/core/runtime.py`
- [WebSocket API](https://github.com/vibicer/xu-harness/blob/main/brain/xu_brain/core/web.py): `brain/xu_brain/core/web.py`
- [Events and context](https://github.com/vibicer/xu-harness/blob/main/brain/xu_brain/api/events.py): `brain/xu_brain/api/events.py`

### Agent execution

- [Agent loop](https://github.com/vibicer/xu-harness/blob/main/brain/xu_brain/features/agent/loop.py): `brain/xu_brain/features/agent/loop.py`
- [Turn orchestration](https://github.com/vibicer/xu-harness/blob/main/brain/xu_brain/features/agent/orchestrator.py): `brain/xu_brain/features/agent/orchestrator.py`
- [Model providers](https://github.com/vibicer/xu-harness/blob/main/brain/xu_brain/features/agent/provider.py): `brain/xu_brain/features/agent/provider.py`
- [Tool runtime](https://github.com/vibicer/xu-harness/tree/main/brain/xu_brain/features/tools): `brain/xu_brain/features/tools`

### Product features

- [Sessions](https://github.com/vibicer/xu-harness/tree/main/brain/xu_brain/features/session): `brain/xu_brain/features/session`
- [Memory](https://github.com/vibicer/xu-harness/tree/main/brain/xu_brain/features/memory): `brain/xu_brain/features/memory`
- [Skills](https://github.com/vibicer/xu-harness/tree/main/brain/xu_brain/features/skills): `brain/xu_brain/features/skills`
- [Presets](https://github.com/vibicer/xu-harness/tree/main/brain/xu_brain/features/presets): `brain/xu_brain/features/presets`
- [Backup and undo](https://github.com/vibicer/xu-harness/blob/main/brain/xu_brain/features/backup/manager.py): `brain/xu_brain/features/backup/manager.py`
- [Undo journal](https://github.com/vibicer/xu-harness/blob/main/brain/xu_brain/features/backup/manager.py): `brain/xu_brain/features/backup/manager.py`
- [Plugin host](https://github.com/vibicer/xu-harness/blob/main/brain/xu_brain/core/host.py): `brain/xu_brain/core/host.py`
- [Plugin API](https://github.com/vibicer/xu-harness/blob/main/brain/xu_brain/api/context.py): `brain/xu_brain/api/context.py`
- [MCP client](https://github.com/vibicer/xu-harness/blob/main/brain/xu_brain/plugins/builtin/mcp/client.py): `brain/xu_brain/plugins/builtin/mcp/client.py`

### Other components

- **User**
- **Model service**
- **Tool targets**
- **MCP server process**

## Connections

- User → Chat and sessions: composes turns
- Chat and sessions → UI state and RPC: updates state
- UI state and RPC → WebSocket API: sends RPC
- WebSocket API → Brain daemon: dispatches requests
- Brain daemon → Agent loop: runs agent
- Agent loop → Model providers: requests completion
- Model providers → Model service: calls model
- Agent loop → Tool runtime: invokes tools
- Tool runtime → Tool targets: accesses resources
- Agent loop → Turn orchestration: delegates subagents
- Agent loop → Sessions: uses sessions
- Agent loop → Memory: uses memory
- Agent loop → Skills: uses skills
- Agent loop → Presets: uses presets
- Tool runtime → Backup and undo: backs up mutations
- Backup and undo → Undo journal: journals snapshots
- Brain daemon → Plugin host: loads plugins
- Plugin host → Plugin API: provides context
- Tool runtime → MCP client: bridges tools
- MCP client → MCP server process: speaks stdio
- WebSocket API → UI state and RPC: streams events
- UI state and RPC → Chat and sessions: updates transcript