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

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.

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

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

// 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 at repository root registers openwork's MCP with Claude Code, Cursor, Codex, and compatible tools.

{
  "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	Defines workspace packages (apps/*, packages/*)
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

# 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/:

# .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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}