# yuezhihuafou/devspace-verge architecture

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

- Interactive diagram: https://gitdiagram.com/yuezhihuafou/devspace-verge
- Repository: https://github.com/yuezhihuafou/devspace-verge

## Overview

DevSpace Verge exposes configured local coding workspaces to coding agents through an MCP server and companion workspace UI. The main flow is an agent opening a workspace, invoking tools for code/process/Git work, then retrieving bounded results or reviewing changes. Durable tasks and run logs support detached work and later inspection; semantic navigation and local-agent integrations add separate capabilities. The server excerpt establishes orchestration and selected dependencies; README documents the broader feature set, but unsampled tool implementations and wiring are not inferred.

Main entry points: [`src/server.ts`](https://github.com/yuezhihuafou/devspace-verge/blob/main/src/server.ts) (MCP server), [`src/compact-runtime/run-store.ts`](https://github.com/yuezhihuafou/devspace-verge/blob/main/src/compact-runtime/run-store.ts) (Run storage), [`src/local-agent-manager.ts`](https://github.com/yuezhihuafou/devspace-verge/blob/main/src/local-agent-manager.ts) (Local-agent manager), [`src/ui/workspace-app.tsx`](https://github.com/yuezhihuafou/devspace-verge/blob/main/src/ui/workspace-app.tsx) (Workspace UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Agent Interface"]
  node_mcp["MCP server<br/>[server.ts]"]
  node_surfaces["Tool surfaces<br/>[index.ts]"]
  node_ui["Workspace UI<br/>[workspace-app.tsx]"]
end

subgraph group_workspace["Workspace Operations"]
  node_workspaces["Workspace registry<br/>[workspaces.ts]"]
  node_config["Configuration<br/>[config.ts]"]
  node_process["Process sessions"]
  node_git["Git operations<br/>[git.ts]"]
  node_worktrees["Git worktrees<br/>[git-worktrees.ts]"]
  node_patch["Patch handling<br/>[apply-patch.ts]"]
  node_semantic["Semantic navigation<br/>[serena-semantic.ts]"]
end

subgraph group_runs["Long-Running Work"]
  node_durable["Durable task manager<br/>[durable-tasks.ts]"]
  node_runaccess["Run log access<br/>[run-log-access.ts]"]
  node_runstore["Run storage<br/>[run-store.ts]"]
  node_retention["Log retention<br/>[retention.ts]"]
end

subgraph group_agents["Local Agents"]
  node_agentmgr["Local-agent manager"]
  node_agentclient["Daemon client"]
  node_daemon["Agent daemon"]
  node_providers["Agent adapters"]
end

subgraph group_state["Persistence and Review"]
  node_db[("SQLite database<br/>[client.ts]")]
  node_workspace_store["Workspace state<br/>[workspace-store.ts]"]
  node_review["Review checkpoints"]
end

node_agent(("Coding agent"))
node_git_service(("Git"))
node_serena(("Serena / LSP"))

node_agent -->|"sends MCP requests"| node_mcp
node_mcp -->|"selects tools"| node_surfaces
node_mcp -->|"loads settings"| node_config
node_mcp -->|"serves workspace tools"| node_workspaces
node_mcp -->|"manages sessions"| node_process
node_mcp -->|"manages tasks"| node_durable
node_mcp -->|"creates manager"| node_semantic
node_mcp -->|"creates manager"| node_review
node_mcp -->|"builds provider status"| node_agentmgr
node_mcp -->|"provides app results"| node_ui
node_mcp -->|"reads run results"| node_runaccess
node_process -->|"stores run output"| node_runstore
node_durable -->|"uses run storage"| node_runstore
node_runaccess -->|"locates runs"| node_runstore
node_retention -->|"prunes stored runs"| node_runstore
node_mcp -->|"manages worktrees"| node_worktrees
node_mcp -->|"applies patches"| node_patch
node_semantic -.->|"queries semantics"| node_serena
node_review -->|"reads and updates refs"| node_git
node_git -->|"executes Git"| node_git_service
node_agentmgr -->|"runs through daemon"| node_agentclient
node_agentclient -->|"sends protocol requests"| node_daemon
node_daemon -->|"dispatches provider work"| node_providers
node_agentmgr -->|"persists agent records"| node_db
node_workspaces -->|"persists workspace state"| node_workspace_store
node_ui -->|"renders tool cards"| node_agent

click node_mcp "https://github.com/yuezhihuafou/devspace-verge/blob/main/src/server.ts"
click node_surfaces "https://github.com/yuezhihuafou/devspace-verge/blob/main/src/tool-surfaces/index.ts"
click node_ui "https://github.com/yuezhihuafou/devspace-verge/blob/main/src/ui/workspace-app.tsx"
click node_workspaces "https://github.com/yuezhihuafou/devspace-verge/blob/main/src/workspaces.ts"
click node_config "https://github.com/yuezhihuafou/devspace-verge/blob/main/src/config.ts"
click node_process "https://github.com/yuezhihuafou/devspace-verge/blob/main/src/process-sessions.ts"
click node_git "https://github.com/yuezhihuafou/devspace-verge/blob/main/src/git.ts"
click node_worktrees "https://github.com/yuezhihuafou/devspace-verge/blob/main/src/git-worktrees.ts"
click node_patch "https://github.com/yuezhihuafou/devspace-verge/blob/main/src/apply-patch.ts"
click node_semantic "https://github.com/yuezhihuafou/devspace-verge/blob/main/src/serena-semantic.ts"
click node_durable "https://github.com/yuezhihuafou/devspace-verge/blob/main/src/durable-tasks.ts"
click node_runaccess "https://github.com/yuezhihuafou/devspace-verge/blob/main/src/compact-runtime/run-log-access.ts"
click node_runstore "https://github.com/yuezhihuafou/devspace-verge/blob/main/src/compact-runtime/run-store.ts"
click node_retention "https://github.com/yuezhihuafou/devspace-verge/blob/main/src/compact-runtime/retention.ts"
click node_agentmgr "https://github.com/yuezhihuafou/devspace-verge/blob/main/src/local-agent-manager.ts"
click node_agentclient "https://github.com/yuezhihuafou/devspace-verge/blob/main/src/local-agent-client.ts"
click node_daemon "https://github.com/yuezhihuafou/devspace-verge/blob/main/src/local-agent-daemon.ts"
click node_providers "https://github.com/yuezhihuafou/devspace-verge/blob/main/src/local-agent-adapters.ts"
click node_db "https://github.com/yuezhihuafou/devspace-verge/blob/main/src/db/client.ts"
click node_workspace_store "https://github.com/yuezhihuafou/devspace-verge/blob/main/src/workspace-store.ts"
click node_review "https://github.com/yuezhihuafou/devspace-verge/blob/main/src/review-checkpoints.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_mcp,node_surfaces,node_ui toneBlue
class node_workspaces,node_config,node_process,node_git,node_worktrees,node_patch,node_semantic toneAmber
class node_durable,node_runaccess,node_runstore,node_retention toneMint
class node_agentmgr,node_agentclient,node_daemon,node_providers toneRose
class node_db,node_workspace_store,node_review,node_agent,node_git_service,node_serena toneIndigo
```

## Components

### Agent Interface

- [MCP server](https://github.com/yuezhihuafou/devspace-verge/blob/main/src/server.ts): `src/server.ts`
- [Tool surfaces](https://github.com/yuezhihuafou/devspace-verge/blob/main/src/tool-surfaces/index.ts): `src/tool-surfaces/index.ts`
- [Workspace UI](https://github.com/yuezhihuafou/devspace-verge/blob/main/src/ui/workspace-app.tsx): `src/ui/workspace-app.tsx`

### Workspace Operations

- [Workspace registry](https://github.com/yuezhihuafou/devspace-verge/blob/main/src/workspaces.ts): `src/workspaces.ts`
- [Configuration](https://github.com/yuezhihuafou/devspace-verge/blob/main/src/config.ts): `src/config.ts`
- [Process sessions](https://github.com/yuezhihuafou/devspace-verge/blob/main/src/process-sessions.ts): `src/process-sessions.ts`
- [Git operations](https://github.com/yuezhihuafou/devspace-verge/blob/main/src/git.ts): `src/git.ts`
- [Git worktrees](https://github.com/yuezhihuafou/devspace-verge/blob/main/src/git-worktrees.ts): `src/git-worktrees.ts`
- [Patch handling](https://github.com/yuezhihuafou/devspace-verge/blob/main/src/apply-patch.ts): `src/apply-patch.ts`
- [Semantic navigation](https://github.com/yuezhihuafou/devspace-verge/blob/main/src/serena-semantic.ts): `src/serena-semantic.ts`

### Long-Running Work

- [Durable task manager](https://github.com/yuezhihuafou/devspace-verge/blob/main/src/durable-tasks.ts): `src/durable-tasks.ts`
- [Run log access](https://github.com/yuezhihuafou/devspace-verge/blob/main/src/compact-runtime/run-log-access.ts): `src/compact-runtime/run-log-access.ts`
- [Run storage](https://github.com/yuezhihuafou/devspace-verge/blob/main/src/compact-runtime/run-store.ts): `src/compact-runtime/run-store.ts`
- [Log retention](https://github.com/yuezhihuafou/devspace-verge/blob/main/src/compact-runtime/retention.ts): `src/compact-runtime/retention.ts`

### Local Agents

- [Local-agent manager](https://github.com/yuezhihuafou/devspace-verge/blob/main/src/local-agent-manager.ts): `src/local-agent-manager.ts`
- [Daemon client](https://github.com/yuezhihuafou/devspace-verge/blob/main/src/local-agent-client.ts): `src/local-agent-client.ts`
- [Agent daemon](https://github.com/yuezhihuafou/devspace-verge/blob/main/src/local-agent-daemon.ts): `src/local-agent-daemon.ts`
- [Agent adapters](https://github.com/yuezhihuafou/devspace-verge/blob/main/src/local-agent-adapters.ts): `src/local-agent-adapters.ts`

### Persistence and Review

- [SQLite database](https://github.com/yuezhihuafou/devspace-verge/blob/main/src/db/client.ts): `src/db/client.ts`
- [Workspace state](https://github.com/yuezhihuafou/devspace-verge/blob/main/src/workspace-store.ts): `src/workspace-store.ts`
- [Review checkpoints](https://github.com/yuezhihuafou/devspace-verge/blob/main/src/review-checkpoints.ts): `src/review-checkpoints.ts`

### Other components

- **Coding agent**
- **Git**
- **Serena / LSP**

## Connections

- Coding agent → MCP server: sends MCP requests
- MCP server → Tool surfaces: selects tools
- MCP server → Configuration: loads settings
- MCP server → Workspace registry: serves workspace tools
- MCP server → Process sessions: manages sessions
- MCP server → Durable task manager: manages tasks
- MCP server → Semantic navigation: creates manager
- MCP server → Review checkpoints: creates manager
- MCP server → Local-agent manager: builds provider status
- MCP server → Workspace UI: provides app results
- MCP server → Run log access: reads run results
- Process sessions → Run storage: stores run output
- Durable task manager → Run storage: uses run storage
- Run log access → Run storage: locates runs
- Log retention → Run storage: prunes stored runs
- MCP server → Git worktrees: manages worktrees
- MCP server → Patch handling: applies patches
- Semantic navigation → Serena / LSP: queries semantics
- Review checkpoints → Git operations: reads and updates refs
- Git operations → Git: executes Git
- Local-agent manager → Daemon client: runs through daemon
- Daemon client → Agent daemon: sends protocol requests
- Agent daemon → Agent adapters: dispatches provider work
- Local-agent manager → SQLite database: persists agent records
- Workspace registry → Workspace state: persists workspace state
- Workspace UI → Coding agent: renders tool cards