different‑ai/openwork Architecture Explained: A Deep Dive into the Modular AI‑Assistant Platform

The different‑ai/openwork architecture is a modular, client‑first platform built on an Electron desktop client, a local workspace server, and an optional remote OpenWork Den control plane connected via the Message Capability Protocol (MCP).

OpenWork (different‑ai/openwork) is designed to run as a local‑first AI assistant that can optionally extend into team‑wide cloud infrastructure. Its architecture separates concerns across distinct layers—from the native UI down to skill definitions—enabling both offline productivity and seamless multi‑agent collaboration.

The Five Core Layers of OpenWork

Electron Desktop Client: The Native Interface

The desktop client provides the cross‑platform UI and the runtime environment for executing OpenWork capabilities. It is built on Electron and bundles a Vite‑powered development server for hot‑reloading during local development.

• Entry point: apps/desktop/ (Electron main process and renderer)
• Build tooling: turbo.json pipelines orchestrate the client build alongside other packages

When you run pnpm dev, the client boots and prints its profile and Chrome DevTools Protocol (CDP) endpoint:

pnpm dev

# [openwork] dev profile=/home/user/.openwork/worktrees/main cdp=http://127.0.0.1:9223

The OPENWORK_DEV_PROFILE environment variable, derived from the worktree path, isolates development state per checkout.

Local Workspace Server: MCP at the Core

Every OpenWork client runs an embedded HTTP server that manages:

• File‑system workspace state
• User settings and cached credentials
• The OpenWork MCP (Message Capability Protocol) endpoint

The local server implements the MCP specification defined in packages/mcp/, exposing capabilities that any attached agent can discover and invoke. This server is started automatically by the desktop client and listens on a local port.

Key directories:

• packages/workspace/ — workspace management and file operations
• packages/mcp/ — MCP protocol implementation

OpenWork Den: Optional Cloud Control Plane

OpenWork Den is the remote, multi‑tenant service that provides:

• Organization‑wide configuration
• Model provider credentials and routing
• Centralized skill marketplace
• Policy enforcement and audit logging

When Den is enabled, the local MCP forwards authenticated requests to https://api.openworklabs.com/mcp/agent. The desktop client connects transparently—skills remain accessible through the same search_capabilities and execute_capability calls regardless of whether they are local or remote.

• Implementation: apps/den/

Skills and Warden: Declarative Capabilities

Capabilities in OpenWork are declarative, versioned definitions stored in the .warden/skills/ directory. Each skill is a JSON or YAML file describing:

• Input/output schemas
• Execution environment (local shell, remote API, UI widget)
• Metadata for discoverability

The Warden runtime loads these definitions at startup and registers them with the MCP. Agents query capabilities through a unified interface without needing to know implementation details.

// Discover capabilities from a connected OpenWork client
import { search_capabilities } from 'openwork-mcp-client';

const caps = await search_capabilities({ query: 'summarize' });
// Returns: [{ capabilityId: 'summarize_document', ... }]

OpenCode Integration: Universal Agent Compatibility

OpenWork exposes its full capability surface to any OpenCode‑compatible agent (Claude Code, Cursor, Codex, etc.) through a configuration file. The opencode.json at the repository root registers OpenWork as a remote MCP server:

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

This bridges OpenWork’s local capabilities into external tools without code changes.

Data Flow: From User Action to Capability Execution

1. Bootstrap: Electron starts → local workspace server initializes → skills load from .warden/skills/
2. Discovery: Agent calls search_capabilities via MCP → Warden returns matching skill definitions
3. Execution: Agent calls execute_capability with arguments → local server resolves handler (local function or remote Den proxy)
4. Response: Result streams back through MCP → agent receives structured output

Monorepo Structure and Build System

OpenWork uses pnpm workspaces with the following conventions:

File	Purpose
pnpm-workspace.yaml	Defines workspace packages (apps/*, packages/*)
turbo.json	Task pipelines for build, test, and dev orchestration
packages/ui/	Shared shadcn/ui components across applications

This structure lets developers run pnpm dev from the root to start all interconnected services simultaneously.

Summary

• Client layer: Electron desktop app with embedded Vite dev server (apps/desktop/)
• Server layer: Local MCP‑enabled workspace server (packages/workspace/, packages/mcp/)
• Cloud layer: Optional OpenWork Den for team‑wide governance (apps/den/)
• Capability layer: Declarative skills managed by Warden (.warden/skills/)
• Integration layer: OpenCode MCP bridge (opencode.json)

Frequently Asked Questions

How does OpenWork handle offline usage?

The desktop client runs a complete local stack: Electron UI, workspace server, and embedded MCP. Skills stored in .warden/skills/ execute without network access. Cloud features are strictly optional and degrade gracefully—local capabilities remain fully functional.

What is the Message Capability Protocol (MCP) in OpenWork?

MCP is OpenWork's standardized capability‑discovery and execution protocol. Defined in packages/mcp/, it provides search_capabilities and execute_capability endpoints that any agent can consume. The protocol abstracts whether a capability runs locally or proxies to OpenWork Den.

Can I extend OpenWork with custom skills?

Yes. Add a JSON or YAML file to .warden/skills/ following the Warden schema. The server hot‑reloads definitions and registers them with the MCP automatically. Skills can shell out to local binaries, call remote APIs, or render custom UI components.

How do external agents connect to a running OpenWork instance?

External agents use the OpenCode configuration in opencode.json. Point the MCP URL to your local server (http://localhost:<port>/mcp) for development or https://api.openworklabs.com/mcp/agent for Den‑managed capabilities. Authentication flows through the oauth block if required.

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