Main Modules and Packages in Openwork: Complete Monorepo Architecture

Openwork organizes its functionality into a pnpm workspace monorepo with self-contained packages including UI primitives (@openwork/ui), type definitions (@openwork/types), MCP client SDKs (@openwork/enterprise-mcp-client), and the Electron desktop app (apps/app), enabling code reuse across desktop, web, and agent interfaces.

Openwork is an open-source AI workspace platform built as a monorepo using pnpm workspaces. Understanding the main modules or packages in Openwork reveals how the project achieves clean separation between visual components, business logic, and communication protocols. The architecture supports multiple entry points—including an Electron desktop application, a web-based Den control plane, and headless agent interfaces—while maintaining type safety across all boundaries.

Core Package Architecture

The repository follows a strict layered architecture that prevents circular dependencies. At the foundation sit type definitions and UI primitives, which feed upward into communication protocols and finally into end-user applications.

The workspace divides into two primary categories: shared libraries (prefixed with @openwork/) and applications (located in apps/ and ee/apps/). This separation ensures that the desktop client, web admin interface, and MCP tooling all consume the same underlying logic.

UI and Type System Layers

@openwork/ui

The @openwork/ui package provides shared UI primitives built as React wrappers around Paper Design shaders. This module exports all visual components from packages/ui/src/react/index.ts, supplying deterministic gradients, roadmap visualizations, and layout primitives used by both the main desktop app and the Den web interface.

Components like PaperMeshGradient and OpenWorkRoadmap encapsulate complex WebGL shader logic while exposing simple React props. Both apps/app and ee/apps/den-web import these components to maintain visual consistency across platforms.

@openwork/types

The @openwork/types package serves as the central type hub for the entire system. Located in packages/types/src/index.ts, it defines Openwork’s core data model including workspace descriptors, URL schemas, provider configurations, desktop IPC contracts, and Den-specific administrative schemas.

Every other package in the monorepo imports from this module to ensure type-safe communication between the Electron main process, renderer, and remote MCP servers. Changes to the domain model propagate from this single source of truth.

Communication and Protocol Modules

@openwork/headless-threads

The @openwork/headless-threads package implements a lightweight protocol that allows agents to drive Openwork without instantiating a full UI. Located in packages/headless-threads/src/client.ts, it provides the wire format, transcript handling, and client utilities necessary for programmatic interaction.

This module is critical for automation scenarios where background processes need to create workspaces, execute tools, or monitor session state without user intervention.

@openwork/enterprise-mcp-client

The @openwork/enterprise-mcp-client package contains the SDK for communicating with Openwork's Model Control Plane (MCP). The main entry point is packages/enterprise-mcp-client/src/enterprise-mcp-client.ts, which exports the EnterpriseMcpClient class.

This client handles OAuth token exchange, requirements discovery, and tool-catalog lookups. It abstracts the HTTP transport layer, allowing consuming applications to call methods like discoverTools() without managing raw API contracts.

@openwork/connect-link

The @openwork/connect-link package provides helper utilities for generating deep links that embed Openwork-specific connection information. Located in packages/connect-link/src/index.ts, the createConnectLink function generates URLs that open specific sessions in the desktop app, optionally pre-populating model providers and workspace contexts.

Service and Automation Packages

@openwork/automations

The @openwork/automations package houses the scheduler engine that powers recurring background jobs. The core logic resides in packages/automations/src/engine.ts, implementing a tick-based system for state-driven workflows, scheduled tasks, and background maintenance operations.

This engine runs inside the Electron desktop context, managing cron-like schedules and event-driven automations without requiring external infrastructure.

@openwork/email

The @openwork/email package is a small templating library for HTML email generation. Located in packages/email/src/send-email.ts, it renders templates for desktop capabilities, onboarding flows, and notification digests, sending them via a configurable transport layer.

@openwork/enterprise-mcp-mock-server

The @openwork/enterprise-mcp-mock-server package provides a development and testing fixture that implements the full MCP protocol. The implementation in packages/enterprise-mcp-mock-server/src/runtime/mock-server.ts mimics OAuth flows, fault injection, and tool-catalog responses, enabling CI pipelines to test client logic without hitting production endpoints.

Utility Modules

@openwork/paths

The @openwork/paths package is a tiny helper library exporting path constants used throughout the repository. Defined in packages/paths/index.d.ts, it centralizes filesystem locations such as the Electron profile directory, ensuring consistent path resolution across Windows, macOS, and Linux builds.

Application Layer

apps/app (Electron Desktop)

The apps/app package is the primary Electron desktop application. Its entry point at apps/app/src/index.react.tsx bootstraps the React renderer, wires together the IPC bridge, and imports @openwork/ui, @openwork/types, and the MCP client to provide the complete Openwork UI/UX.

This application composes all lower-level packages into the end-user experience, handling window management, system tray integration, and native OS interactions.

ee/apps/den-web (Web Admin Interface)

The ee/apps/den-web package (located in the enterprise ee folder) implements the web-only "Den" control plane UI. Administrators use this interface to manage teams, configure model providers, and curate skill marketplaces. It reuses @openwork/ui components and the MCP client, demonstrating how the shared packages support both desktop and web deployment targets.

apps/ui-demo (Component Showcase)

The apps/ui-demo package provides a lightweight React environment for rapid UI iteration. Located in apps/ui-demo/src/app.tsx, this standalone application showcases UI primitives without invoking Electron, allowing designers and developers to test visual changes quickly.

Code Examples

Using the UI library in a custom component:

import { PaperMeshGradient, OpenWorkRoadmap } from '@openwork/ui/react';

export const MyWelcome = () => (
  <div className="h-screen w-full">
    {/* Deterministic gradient based on a seed */}
    <PaperMeshGradient seed="om_01kmhbscaze02vp04ykqa4tcsb" />
    {/* Re-use the shared roadmap visual */}
    <OpenWorkRoadmap />
  </div>
);

Creating a connect link that opens a new Openwork session:

import { createConnectLink } from '@openwork/connect-link';

const link = createConnectLink({
  workspaceId: 'ws_123',
  sessionName: 'Demo',
  // optional: pre-populate a model provider
  provider: { id: 'anthropic', model: 'claude-3-5-sonnet' },
});

console.log('Open this URL to start a session:', link);

Calling the MCP client to discover available tools:

import { EnterpriseMcpClient } from '@openwork/enterprise-mcp-client';

async function listTools() {
  const client = new EnterpriseMcpClient({ url: 'https://api.openworklabs.com/mcp/agent' });
  const tools = await client.discoverTools();   // → { tools: [{ name, description, ... }] }
  console.table(tools);
}
listTools();

Summary

• Openwork uses a pnpm workspace monorepo to share code between desktop, web, and agent interfaces.
• @openwork/types in packages/types/src/index.ts provides the central type definitions that enforce contracts across all modules.
• @openwork/ui delivers React components wrapping Paper Design shaders, consumed by both apps/app and ee/apps/den-web.
• Communication modules include headless-threads for agent protocols, enterprise-mcp-client for remote model control, and connect-link for deep linking.
• Service packages like automations and email handle background jobs and notifications, while enterprise-mcp-mock-server enables testing without external dependencies.
• The application layer consists of the Electron desktop app (apps/app), the web admin interface (ee/apps/den-web), and a UI demo environment (apps/ui-demo).

Frequently Asked Questions

What is the purpose of the @openwork/types package?

The @openwork/types package defines the canonical data models for workspaces, URLs, provider descriptors, and IPC contracts used throughout the Openwork ecosystem. Located in packages/types/src/index.ts, it ensures that the desktop app, web interface, and MCP clients all reference identical TypeScript interfaces, preventing runtime mismatches during cross-process communication.

How does the headless-threads module enable agent automation?

The @openwork/headless-threads module, implemented in packages/headless-threads/src/client.ts, provides a wire protocol that allows external agents to interact with Openwork without rendering a UI. It handles transcript management, session state, and tool invocation, making it possible for background processes or CLI tools to drive Openwork programmatically.

What is the difference between apps/app and ee/apps/den-web?

apps/app is the Electron desktop application that runs natively on Windows, macOS, and Linux, providing the full Openwork experience with system-level integrations. ee/apps/den-web is a web-only React application for enterprise administrators to manage teams and model providers; it runs in a browser and shares UI components with the desktop app via @openwork/ui, but lacks native filesystem access and Electron APIs.

How does the enterprise-mcp-mock-server support development?

The @openwork/enterprise-mcp-mock-server package, found in packages/enterprise-mcp-mock-server/src/runtime/mock-server.ts, implements a compliant MCP server that mimics production OAuth flows and tool catalogs. Developers use this mock server in automated tests and local development to validate client behavior without requiring live credentials or network access to remote model providers.

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