# waishnav/devspace architecture

> Architecture diagram of the GitHub repository waishnav/devspace, 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/waishnav/devspace
- Repository: https://github.com/waishnav/devspace

## Overview

DevSpace is a self-hosted MCP server that gives connected coding hosts scoped access to local projects. The main workflow is: a user configures allowed roots and credentials, starts the server, approves a host connection, opens a workspace, then invokes tools to inspect or change files and run commands. The server also provides Git-based change review and optional delegation to local coding agents. Edges reflect the documented workflow and sampled server/tool ownership; subsystem internals not shown in excerpts are represented at their exact source paths without speculative call chains.

Main entry points: [`src/server.ts`](https://github.com/waishnav/devspace/blob/main/src/server.ts) (MCP server), [`src/tool-surfaces/index.ts`](https://github.com/waishnav/devspace/blob/main/src/tool-surfaces/index.ts) (Tool surfaces), [`src/local-agent-manager.ts`](https://github.com/waishnav/devspace/blob/main/src/local-agent-manager.ts) (Agent manager), [`src/workspaces.ts`](https://github.com/waishnav/devspace/blob/main/src/workspaces.ts) (Workspace registry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_access["Access and setup"]
  node_cli["CLI<br/>[cli.ts]"]
  node_onboarding["Onboarding<br/>[onboarding.ts]"]
  node_configuration["Configuration<br/>[config.ts]"]
  node_server["MCP server<br/>[server.ts]"]
  node_oauth["OAuth provider<br/>[oauth-provider.ts]"]
  node_roots["Allowed roots<br/>[roots.ts]"]
end

subgraph group_workspace["Workspace coding"]
  node_workspace_registry["Workspace registry<br/>[workspaces.ts]"]
  node_tool_surface["Tool surfaces<br/>[index.ts]"]
  node_processes["Command sessions"]
  node_git_worktrees["Git worktrees<br/>[git-worktrees.ts]"]
  node_skills["Project skills<br/>[skills.ts]"]
  node_artifacts["Artifact exchange<br/>[artifact-tools.ts]"]
end

subgraph group_agents["Local agents"]
  node_agent_manager["Agent manager"]
  node_agent_client["Agent daemon client"]
  node_agent_daemon["Agent daemon"]
  node_agent_runtime["Agent runtimes"]
end

subgraph group_review["Review and presentation"]
  node_review_checkpoints["Review checkpoints"]
  node_review_ui["Change cards<br/>[review-payload.tsx]"]
  node_workspace_ui["Workspace app<br/>[workspace-app.tsx]"]
end

subgraph group_state["Persistent state"]
  node_workspace_store[("Workspace sessions<br/>[workspace-store.ts]")]
  node_agent_store[("Agent sessions")]
  node_database[("SQLite state<br/>[client.ts]")]
end

node_user(("User"))
node_host(("MCP host"))

node_user -->|"configures"| node_cli
node_cli -->|"starts setup"| node_onboarding
node_onboarding -->|"writes settings"| node_configuration
node_user -->|"requests coding"| node_host
node_host -->|"MCP requests"| node_server
node_server -->|"loads settings"| node_configuration
node_server -->|"authenticates"| node_oauth
node_server -->|"checks scope"| node_roots
node_server -->|"opens workspace"| node_workspace_registry
node_server -->|"registers tools"| node_tool_surface
node_tool_surface -->|"resolves workspace"| node_workspace_registry
node_tool_surface -->|"runs commands"| node_processes
node_tool_surface -->|"manages worktrees"| node_git_worktrees
node_tool_surface -->|"discovers skills"| node_skills
node_tool_surface -->|"handles artifacts"| node_artifacts
node_server -->|"creates review manager"| node_review_checkpoints
node_review_checkpoints -->|"provides diff data"| node_review_ui
node_server -->|"serves app resources"| node_workspace_ui
node_server -->|"coordinates agents"| node_agent_manager
node_agent_manager -->|"starts agent runs"| node_agent_client
node_agent_client -->|"sends requests"| node_agent_daemon
node_agent_daemon -->|"dispatches turns"| node_agent_runtime
node_agent_manager -->|"persists turns"| node_agent_store
node_workspace_registry -->|"persists sessions"| node_workspace_store
node_workspace_store -->|"uses SQLite"| node_database
node_agent_store -->|"uses SQLite"| node_database

click node_cli "https://github.com/waishnav/devspace/blob/main/src/cli.ts"
click node_onboarding "https://github.com/waishnav/devspace/blob/main/src/onboarding.ts"
click node_configuration "https://github.com/waishnav/devspace/blob/main/src/config.ts"
click node_server "https://github.com/waishnav/devspace/blob/main/src/server.ts"
click node_oauth "https://github.com/waishnav/devspace/blob/main/src/oauth-provider.ts"
click node_roots "https://github.com/waishnav/devspace/blob/main/src/roots.ts"
click node_workspace_registry "https://github.com/waishnav/devspace/blob/main/src/workspaces.ts"
click node_workspace_store "https://github.com/waishnav/devspace/blob/main/src/workspace-store.ts"
click node_tool_surface "https://github.com/waishnav/devspace/blob/main/src/tool-surfaces/index.ts"
click node_processes "https://github.com/waishnav/devspace/blob/main/src/process-sessions.ts"
click node_git_worktrees "https://github.com/waishnav/devspace/blob/main/src/git-worktrees.ts"
click node_skills "https://github.com/waishnav/devspace/blob/main/src/skills.ts"
click node_artifacts "https://github.com/waishnav/devspace/blob/main/src/artifact-tools.ts"
click node_review_checkpoints "https://github.com/waishnav/devspace/blob/main/src/review-checkpoints.ts"
click node_review_ui "https://github.com/waishnav/devspace/blob/main/src/ui/review-payload.tsx"
click node_workspace_ui "https://github.com/waishnav/devspace/blob/main/src/ui/workspace-app.tsx"
click node_agent_manager "https://github.com/waishnav/devspace/blob/main/src/local-agent-manager.ts"
click node_agent_client "https://github.com/waishnav/devspace/blob/main/src/local-agent-client.ts"
click node_agent_daemon "https://github.com/waishnav/devspace/blob/main/src/local-agent-daemon.ts"
click node_agent_runtime "https://github.com/waishnav/devspace/blob/main/src/local-agent-runtime.ts"
click node_agent_store "https://github.com/waishnav/devspace/blob/main/src/local-agent-store.ts"
click node_database "https://github.com/waishnav/devspace/blob/main/src/db/client.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_cli,node_onboarding,node_configuration,node_server,node_oauth,node_roots,node_user toneBlue
class node_workspace_registry,node_tool_surface,node_processes,node_git_worktrees,node_skills,node_artifacts toneAmber
class node_agent_manager,node_agent_client,node_agent_daemon,node_agent_runtime toneMint
class node_review_checkpoints,node_review_ui,node_workspace_ui toneRose
class node_workspace_store,node_agent_store,node_database,node_host toneIndigo
```

## Components

### Access and setup

- [CLI](https://github.com/waishnav/devspace/blob/main/src/cli.ts): `src/cli.ts`
- [Onboarding](https://github.com/waishnav/devspace/blob/main/src/onboarding.ts): `src/onboarding.ts`
- [Configuration](https://github.com/waishnav/devspace/blob/main/src/config.ts): `src/config.ts`
- [MCP server](https://github.com/waishnav/devspace/blob/main/src/server.ts): `src/server.ts`
- [OAuth provider](https://github.com/waishnav/devspace/blob/main/src/oauth-provider.ts): `src/oauth-provider.ts`
- [Allowed roots](https://github.com/waishnav/devspace/blob/main/src/roots.ts): `src/roots.ts`

### Workspace coding

- [Workspace registry](https://github.com/waishnav/devspace/blob/main/src/workspaces.ts): `src/workspaces.ts`
- [Tool surfaces](https://github.com/waishnav/devspace/blob/main/src/tool-surfaces/index.ts): `src/tool-surfaces/index.ts`
- [Command sessions](https://github.com/waishnav/devspace/blob/main/src/process-sessions.ts): `src/process-sessions.ts`
- [Git worktrees](https://github.com/waishnav/devspace/blob/main/src/git-worktrees.ts): `src/git-worktrees.ts`
- [Project skills](https://github.com/waishnav/devspace/blob/main/src/skills.ts): `src/skills.ts`
- [Artifact exchange](https://github.com/waishnav/devspace/blob/main/src/artifact-tools.ts): `src/artifact-tools.ts`

### Local agents

- [Agent manager](https://github.com/waishnav/devspace/blob/main/src/local-agent-manager.ts): `src/local-agent-manager.ts`
- [Agent daemon client](https://github.com/waishnav/devspace/blob/main/src/local-agent-client.ts): `src/local-agent-client.ts`
- [Agent daemon](https://github.com/waishnav/devspace/blob/main/src/local-agent-daemon.ts): `src/local-agent-daemon.ts`
- [Agent runtimes](https://github.com/waishnav/devspace/blob/main/src/local-agent-runtime.ts): `src/local-agent-runtime.ts`

### Review and presentation

- [Review checkpoints](https://github.com/waishnav/devspace/blob/main/src/review-checkpoints.ts): `src/review-checkpoints.ts`
- [Change cards](https://github.com/waishnav/devspace/blob/main/src/ui/review-payload.tsx): `src/ui/review-payload.tsx`
- [Workspace app](https://github.com/waishnav/devspace/blob/main/src/ui/workspace-app.tsx): `src/ui/workspace-app.tsx`

### Persistent state

- [Workspace sessions](https://github.com/waishnav/devspace/blob/main/src/workspace-store.ts): `src/workspace-store.ts`
- [Agent sessions](https://github.com/waishnav/devspace/blob/main/src/local-agent-store.ts): `src/local-agent-store.ts`
- [SQLite state](https://github.com/waishnav/devspace/blob/main/src/db/client.ts): `src/db/client.ts`

### Other components

- **User**
- **MCP host**

## Connections

- User → CLI: configures
- CLI → Onboarding: starts setup
- Onboarding → Configuration: writes settings
- User → MCP host: requests coding
- MCP host → MCP server: MCP requests
- MCP server → Configuration: loads settings
- MCP server → OAuth provider: authenticates
- MCP server → Allowed roots: checks scope
- MCP server → Workspace registry: opens workspace
- MCP server → Tool surfaces: registers tools
- Tool surfaces → Workspace registry: resolves workspace
- Tool surfaces → Command sessions: runs commands
- Tool surfaces → Git worktrees: manages worktrees
- Tool surfaces → Project skills: discovers skills
- Tool surfaces → Artifact exchange: handles artifacts
- MCP server → Review checkpoints: creates review manager
- Review checkpoints → Change cards: provides diff data
- MCP server → Workspace app: serves app resources
- MCP server → Agent manager: coordinates agents
- Agent manager → Agent daemon client: starts agent runs
- Agent daemon client → Agent daemon: sends requests
- Agent daemon → Agent runtimes: dispatches turns
- Agent manager → Agent sessions: persists turns
- Workspace registry → Workspace sessions: persists sessions
- Workspace sessions → SQLite state: uses SQLite
- Agent sessions → SQLite state: uses SQLite