What Are the Core Components of the Openwork Project?

The Openwork project is organized as a monorepo containing six core architectural components: an Electron-based desktop client, a cloud-native Den server, a shared React UI library, an MCP client for AI agent integration, a hands-free voice control layer, and modular automation skill packages.

The Openwork project maintained by different-ai is an open-source productivity platform structured as a Turborepo monorepo. Understanding the core components of the Openwork project reveals how it bridges local-first desktop applications with cloud-native AI agent capabilities, enabling seamless integration between user interfaces and automated workflows.

Desktop Client (Electron)

The desktop client provides the native macOS, Windows, and Linux user interface for Openwork. Located in apps/desktop, this Electron application hosts a local CDP (Chrome DevTools Protocol) server that allows AI agents to interact with the UI programmatically.

The entry point for the desktop process is apps/desktop/main.ts, which initializes the Electron window and sets up the local agent bridge. You can launch the desktop client using the monorepo scripts defined in the root package.json:

# Start the desktop application

pnpm dev

# Run isolated worktree for side-by-side instances

pnpm dev:worktree

The dev:worktree command automatically creates a separate profile, enabling multiple instances to run simultaneously without conflicts.

OpenWork Den Server

The OpenWork Den serves as the cloud-native control plane API. Located in apps/server, this component stores organizational data, team configurations, and model provider settings. It also publishes skills and MCP (Model Control Plane) endpoints that agents consume.

The server bootstrap code resides in apps/server/src/index.ts. To start the Den server locally with its required infrastructure:

pnpm dev:den

This command executes scripts/dev-local.mjs, which orchestrates Docker containers via packaging/docker/docker-compose.web-local.yml and initializes the MySQL database before launching the Express-style server.

Shared UI Library (@openwork/ui)

The @openwork/ui package in packages/ui provides a shadcn-style React component library used by both the desktop client and web interfaces. This shared library ensures consistent styling and behavior across all Openwork interfaces.

The component exports are centralized in packages/ui/src/react/index.ts. Import components into any React application within the monorepo:

import { Button } from '@openwork/ui/react'

export default function Example() {
  return <Button onClick={() => alert('Hello')}>Click me</Button>
}

MCP Integration Client

The Model Control Plane (MCP) client, located in packages/openwork-ui-mcp, wraps remote Openwork MCP endpoints. This allows external AI agents such as Claude Code or Cursor to invoke Openwork capabilities without running the full desktop application.

The client initialization code is found in packages/openwork-ui-mcp/src/index.ts. To configure an external agent, add the remote MCP endpoint to your agent configuration:

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

Once configured, agents can call search_capabilities and execute_capability against the Openwork ecosystem.

Hands-Free Voice Layer

The @openwork/handsfree package in packages/handsfree implements speech-to-text and command parsing functionality. This layer enables voice-driven agent control, allowing users to trigger automations through spoken commands.

The voice processing pipelines are initialized from packages/handsfree/src/index.ts. Start the voice server independently using:

pnpm --filter @openwork/handsfree dev

This starts a local server that agents query for voice command interpretation and routing.

Automation Skill Packages

Beyond the core applications, Openwork organizes reusable business logic into skill packages located throughout packages/*. These include integrations for email processing, connect-link workflows, and enterprise MCP clients. Each skill maintains its own src/ directory and package.json, exposing standardized interfaces that the Den server and desktop client consume.

Configuration and Tooling

Several root-level files govern the monorepo structure:

• warden.toml – Defines workspace configuration and internal tooling settings
• package.json (root) – Contains monorepo scripts (pnpm dev, pnpm dev:den) and workspace package definitions
• AGENTS.md – Documents the high-level architecture philosophy and agent interaction patterns

These files collectively manage the Turborepo workspace, ensuring consistent builds across the desktop, server, and package boundaries.

Summary

• Desktop Client: Electron app in apps/desktop/main.ts providing native UI and local CDP server
• Den Server: Cloud API in apps/server/src/index.ts handling organizations and MCP publishing
• UI Library: Shared React components in packages/ui/src/react/index.ts used across applications
• MCP Client: Agent integration layer in packages/openwork-ui-mcp/src/index.ts for external AI tools
• Voice Layer: Speech processing in packages/handsfree/src/index.ts enabling hands-free control
• Configuration: Managed via warden.toml and root package.json with orchestration scripts in scripts/dev-local.mjs

Frequently Asked Questions

What technology stack powers the Openwork project?

The Openwork project uses TypeScript throughout, with Electron for the desktop client, Express/Node.js for the Den server, React for the UI layer, and Turborepo for monorepo management. The architecture implements the Model Control Plane (MCP) protocol to standardize AI agent interactions.

How do I run the Openwork desktop application in development mode?

Execute pnpm dev from the repository root to start the Electron desktop client. For isolated testing with separate user profiles, use pnpm dev:worktree instead. Both commands reference the entry point at apps/desktop/main.ts.

What is the purpose of the Den server component?

The Den server acts as the cloud-native control plane that stores multi-user data including organizations, teams, and model provider configurations. It exposes skills and capabilities via MCP endpoints, allowing remote agents to execute Openwork functions without local installation.

How does Openwork integrate with external AI agents like Claude or Cursor?

Through the MCP client package located at packages/openwork-ui-mcp/src/index.ts. By adding the Openwork MCP endpoint configuration to your agent's settings (such as opencode.json), external agents can discover and execute capabilities published by the Den server via standardized MCP protocol calls.

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