# Understanding the Architecture of different-ai/openwork: A Modular Client-First Platform

> Explore the modular client-first architecture of different-ai/openwork. Discover its Electron client, MCP server, and optional OpenWork Den cloud control plane.

- Repository: [Different AI/openwork](https://github.com/different-ai/openwork)
- Tags: architecture
- Published: 2026-08-04

---

**The openwork codebase implements a local-first, extensible AI workspace with an Electron desktop client, a built-in MCP server for skill discovery and execution, and an optional cloud control plane called OpenWork Den.**

The **different-ai/openwork** repository delivers a hybrid architecture that prioritizes user control while enabling team collaboration. At its core, openwork runs as a standalone desktop application that manages its own workspace, executes AI-powered skills, and exposes capabilities through the Message Capability Protocol (MCP). Teams can optionally connect to **OpenWork Den** for centralized skill distribution and policy enforcement.

## Core Architectural Components

The openwork platform consists of five interconnected layers, each implemented as a distinct package or application within the pnpm monorepo.

### Desktop Client (Electron)

The **desktop client** provides the native user interface and hosts the local runtime environment. Built on Electron, this component bundles the workspace server and renders a Vite-powered frontend for rapid development.

- Entry point: `apps/desktop/`
- Implements hot-reloading via Vite dev server
- Boots a local HTTP API for agent integration
- Prints dev profile path on startup: `[openwork] dev profile=...`

The client initializes its workspace context through the `OPENWORK_DEV_PROFILE` environment variable, creating isolated environments per worktree.

### Local Workspace Server

Embedded within the desktop client, the **workspace server** manages file system operations, caches skill definitions, and exposes the primary MCP endpoint. This server enables offline operation and local agent discovery.

| Responsibility | Implementation Location |
|---------------|------------------------|
| File system abstraction | `packages/workspace/` |
| Settings persistence | Profile directory |
| MCP endpoint registration | `packages/mcp/` |
| Capability caching | In-memory + filesystem |

The workspace server responds to two fundamental MCP operations: `search_capabilities` for discovery and `execute_capability` for invocation.

### OpenWork Den (Remote Control Plane)

**OpenWork Den** serves as the optional cloud layer for organizational deployment. When enabled, the desktop client's MCP forwards requests to Den for team-wide skill resolution and authentication.

- Server implementation: `apps/den/`
- Handles org-wide model provider credentials
- Manages skill marketplace and policy enforcement
- Authenticates users via OAuth

Connection to Den transforms a local-first installation into a managed workspace without requiring code changes to the client.

### Skills System (Warden)

Skills in openwork are **declarative capabilities** defined through JSON or YAML configurations. The Warden runtime loads these definitions from the `.warden/skills/` directory and exposes them through the MCP.

```typescript
// Skill discovery via MCP
import { search_capabilities } from 'openwork-mcp-client';

const caps = await search_capabilities({ query: 'translate' });
// Returns: [{ id: 'translate_text', description: '...', parameters: {...} }]

```

```typescript
// Skill execution
import { execute_capability } from 'openwork-mcp-client';

const result = await execute_capability({
  capabilityId: 'translate_text',
  args: { text: 'Hello world', targetLang: 'es' }
});
// Returns: '¡Hola mundo!'

```

Skill definitions include parameter schemas, permission requirements, and execution handlers that can reference local binaries or remote endpoints.

### OpenCode Integration Layer

The **OpenCode integration** enables external agents to consume openwork capabilities through a standardized configuration file. The [`opencode.json`](https://github.com/different-ai/openwork/blob/main/opencode.json) at repository root registers openwork's MCP with Claude Code, Cursor, Codex, and compatible tools.

```json
{
  "mcp": {
    "openwork": {
      "type": "remote",
      "enabled": true,
      "url": "https://api.openworklabs.com/mcp/agent",
      "oauth": {}
    }
  }
}

```

This configuration allows agents to discover and execute openwork skills without direct workspace access.

## Data Flow and Execution Model

Understanding how components interact clarifies the architecture's flexibility:

1. **Startup**: Electron boots → workspace server initializes → MCP endpoint binds to local port
2. **Skill Loading**: Warden scans `.warden/skills/` → registers capabilities with MCP registry
3. **Local Execution**: Agent calls `search_capabilities` → receives matching skills → invokes `execute_capability` → workspace server processes directly
4. **Remote Execution**: Den-enabled client forwards request → Den authenticates → resolves skill from org marketplace → returns result through same MCP channel
5. **State Persistence**: All workspace files, cached credentials, and user settings write to the profile directory identified at startup

This flow supports seamless fallback: if Den is unreachable, the client continues operating with locally cached skills.

## Monorepo Structure and Build System

The openwork repository uses **pnpm workspaces** with Turborepo for task orchestration. Key configuration files include:

| File | Purpose |
|------|---------|
| [`pnpm-workspace.yaml`](https://github.com/different-ai/openwork/blob/main/pnpm-workspace.yaml) | Defines workspace packages (`apps/*`, `packages/*`) |
| [`turbo.json`](https://github.com/different-ai/openwork/blob/main/turbo.json) | Configures build pipelines and caching |
| `packages/*` | Shared libraries (UI components, MCP protocol, workspace logic) |
| `apps/desktop/` | Electron application |
| `apps/den/` | Cloud control plane server |

The shad-cn/ui component library provides consistent design primitives across desktop and web interfaces.

## Development and Extension Patterns

### Starting a Local Development Instance

```bash

# From repository root

pnpm dev

# Output includes:

# [openwork] dev profile=/path/to/profile cdp=http://127.0.0.1:9223

```

The `cdp` URL refers to the Chrome DevTools Protocol endpoint for debugging the embedded browser context.

### Adding Custom Skills

Create a new skill definition in `.warden/skills/`:

```yaml

# .warden/skills/my_custom_skill.yaml

id: analyze_csv
name: CSV Data Analyzer
description: Parse and summarize CSV files
parameters:
  path:
    type: string
    description: Absolute path to CSV file
handler:
  type: node
  entry: ./handlers/csv_analyzer.js

```

Restart the dev server or trigger a capability reload to register the new skill.

## Summary

- **Openwork's architecture** centers on a local-first Electron client with an embedded MCP server
- **Four primary layers**: Desktop UI, Workspace Server, Warden Skills, and optional Den control plane
- **MCP protocol** standardizes capability discovery and execution across local and remote contexts
- **Declarative skills** in `.warden/skills/` enable rapid extension without core code changes
- **OpenCode integration** via [`opencode.json`](https://github.com/different-ai/openwork/blob/main/opencode.json) bridges openwork capabilities to external AI agents
- **Pnpm + Turborepo** monorepo structure supports scalable development across apps and packages

## Frequently Asked Questions

### What is the Message Capability Protocol (MCP) in openwork?

MCP is openwork's standardized protocol for skill discovery and execution. It defines `search_capabilities` and `execute_capability` operations that work identically whether calling a local workspace server or a remote Den instance. The protocol enables interchangeable backends while presenting a consistent interface to agents.

### Can openwork run completely offline?

Yes. The desktop client embeds the full workspace server and can load skills from `.warden/skills/` without network connectivity. Offline operation includes skill execution, file management, and local agent integration. Den connection is purely optional for team features.

### How does openwork differ from other AI workspace tools?

Openwork's **client-first architecture** distinguishes it from cloud-only alternatives. Users retain full control of their workspace files and can audit all skill definitions locally. The MCP-based extension model also allows third-party agents to consume openwork capabilities, rather than locking users into a proprietary ecosystem.

### Where are user settings and cached data stored?

Openwork stores all state in a **dev profile directory** dynamically determined at startup. The path prints as `[openwork] dev profile=/absolute/path` when running `pnpm dev`. This isolation enables multiple worktrees with independent configurations and prevents cross-contamination between projects.