What Are the Packages in the OpenWork Monorepo? A Complete Technical Breakdown

The OpenWork monorepo organizes its architecture into over a dozen independently versioned npm packages under packages/, each owning a distinct slice of the system—from UI primitives and headless thread clients to automation logic and desktop bootstrapping.

OpenWork is a monorepo managed with pnpm workspaces and Turbo that groups loosely-coupled npm packages into a unified desktop and cloud platform. Each package under packages/ is independently versioned and serves a specific technical responsibility, producing modular builds for the desktop app and the Den control plane.

UI, Frontend, and Interaction Packages

These packages handle everything the user sees and touches, from shader-backed React components to voice-driven experiments.

@openwork/ui: Shared Design System

@openwork/ui supplies the shared React primitives used across every OpenWork front-end, including the desktop app and web UI. The package wraps Paper Design shaders—exposing components like PaperMeshGradient and PaperGrainGradient—and implements deterministic "seed" logic so visual output can be reproduced consistently across applications. It also exports the OpenWorkRoadmap component used in landing pages and documentation.

The component implementations live in packages/ui/src/react/paper/*.

@openwork/handsfree: Voice-Driven Interaction

@openwork/handsfree is an experimental package that demonstrates hands-free, voice-driven UI interaction. It includes end-to-end benchmark pages and demo scripts for testing audio-first workflows.

@openwork/connect-link: Deep Link Protocol

@openwork/connect-link abstracts the "connect-link" protocol that the desktop app uses to open remote workspaces. The small library—centered in packages/connect-link/src/index.ts—provides a simple API for constructing deep links that launch the app with a specific workspace context.

Automation and Execution Packages

These packages define the core logic for scheduled jobs, sandboxed code execution, and messaging.

@openwork/automations: Scheduling and Recurrence Engine

@openwork/automations holds the core domain model for the Automation feature consumed by the Den cloud control plane. It defines contracts for schedule calculation, recurrence, DST handling, and idempotent execution, but intentionally holds no runtime; the Den supplies persistence, leases, and model adapters. This separation lets both hosted cloud and on-prem automation engines share the same logic.

The core schedule calculations are implemented in packages/automations/src/schedule.ts.

import { computeSchedule, scheduleState } from "@openwork/automations";

const schedule = computeSchedule({
  start: "2024-01-01",
  frequency: "weekly",
  dayOfWeek: "mon",
  locale: "en-US",
});

console.log(schedule); // array of UTC timestamps for each occurrence

@openwork/codemode: Sandboxed Code Runtime

@openwork/codemode provides the runtime for the "CodeMode" sandbox that evaluates user-written code safely. It supplies a deterministic ToolError hierarchy, async execution helpers, and test suites such as stdlib.test.ts. The OpenWork server uses this package to run user code in isolation, with key error handling logic living in packages/codemode/src/tool-error.ts.

@openwork/email: Notification Transport

@openwork/email is a thin helper for sending email notifications, for example from Den automation jobs. It wraps transport configuration and templating into a reusable package.

Thread and MCP Client Packages

These packages expose typed clients for driving OpenWork sessions and communicating with the Multi-Capability Provider gateway.

@openwork/headless-threads: Programmatic Thread Client

@openwork/headless-threads is a typed client for driving an OpenWork "thread" (session) without any UI. It wraps low-level HTTP calls with a high-level contract that includes createThread, sendTurn, waitForThread, and exportTranscript. This guarantees deterministic behavior for automation, benchmarking, or agent-only workloads.

The API wrapper lives in packages/headless-threads/src/client.ts.

import { createHeadlessThreadClient } from "@openwork/headless-threads";

const client = createHeadlessThreadClient({
  baseUrl: "http://127.0.0.1:8787",
  workspaceId: "ws_1",
  token: process.env.OPENWORK_TOKEN,
  defaultModel: { providerId: "anthropic", modelId: "claude-sonnet-5" },
});

async function demo() {
  const thread = await client.createThread({
    title: "Refund policy",
    prompt: "A customer wants a refund after 40 days. What are their options?"
  });

  await client.waitForThread(thread.id, { timeoutMs: 120_000 });

  const followUp = await client.sendTurn(thread.id, {
    prompt: "They also lost the receipt."
  });

  const result = await client.waitForThread(thread.id, {
    timeoutMs: 120_000,
    since: followUp,
  });

  if (result.outcome === "settled") {
    const transcript = await client.exportTranscript(thread.id);
    console.log(transcript.finalAssistantText);
  }
}
demo();

@openwork/enterprise-mcp-client: Enterprise Capability Gateway

@openwork/enterprise-mcp-client is the client library that talks to the real MCP server for enterprise-grade features. It handles authentication, capability discovery, and execution of remote capabilities. The implementation is rooted in packages/enterprise-mcp-client/src/index.ts.

@openwork/openwork-ui-mcp: UI Transport Layer

@openwork/openwork-ui-mcp is a minimal Multi-Capability Provider client that exposes UI capabilities to the OpenWork MCP gateway. It implements the thin transport layer that lets the MCP server invoke UI-side actions.

@openwork/enterprise-mcp-mock-server: Local Testing Backend

@openwork/enterprise-mcp-mock-server provides a mock implementation of the MCP server used for local testing of enterprise-only features. It simulates remote MCP endpoints so developers can test enterprise integrations without a real backend.

Bootstrap, Types, and Infrastructure Packages

These utility packages wire the system together, manage installation, and centralize shared definitions.

@openwork/openwork-bootstrap: Desktop Bootstrap CLI

@openwork/openwork-bootstrap is a small CLI that bootstraps the OpenWork desktop app and optionally onboards a cloud org. It installs the openwork-bootstrap binary into a user-writable location, downloads and verifies desktop artifacts (DMG, AppImage, EXE, etc.), and provides a cloud onboard flow that creates a Den org, invites teammates, and registers a starter skill.

The entry point is packages/openwork-bootstrap/bin/openwork.mjs.

# Install the binary into ~/.local/bin

openwork-bootstrap install --bin-dir ~/.local/bin --install-dir ~/.openwork/bootstrap

# Install the desktop app (example manifest URL)

openwork-bootstrap install app --manifest https://example.com/openwork-install-manifest.json

@openwork/types: Shared TypeScript Definitions

@openwork/types centralizes shared TypeScript type definitions used throughout the codebase. It exports types for workspace URLs, provider descriptors, OpenWork context, and IPC messages from files like packages/types/src/openwork-context.ts, giving every package a single source of truth.

@openwork/paths: Filesystem Utilities

@openwork/paths provides helper utilities for dealing with filesystem paths and workspace roots. Its public API lives in packages/paths/src/index.mjs and includes a tiny surface—validated in paths.test.mjs—for creating temporary workspace directories in tests. The package guarantees cross-platform path handling for both the desktop and server.

@openwork/install-config: Install Manifest Management

@openwork/install-config handles configuration files that the bootstrap process writes, such as ~/.openwork/bootstrap. It provides a small API for reading and writing JSON install manifests.

Summary

• The OpenWork monorepo splits its system into independently versioned npm packages under packages/.
• UI and frontend concerns live in @openwork/ui, @openwork/handsfree, and @openwork/connect-link.
• Automation and execution logic is centralized in @openwork/automations, @openwork/codemode, and @openwork/email.
• Programmatic clients for threads and enterprise MCP are provided by @openwork/headless-threads, @openwork/enterprise-mcp-client, and related transport packages.
• Infrastructure and tooling packages—@openwork/openwork-bootstrap, @openwork/types, @openwork/paths, and @openwork/install-config—wire the desktop app, server, and cloud control plane together.
• Build orchestration relies on pnpm workspaces (pnpm-workspace.yaml) and Turbo (turbo.json).

Frequently Asked Questions

What build tools manage the OpenWork monorepo packages?

The monorepo uses pnpm workspaces defined in pnpm-workspace.yaml to discover packages, and Turbo configured in turbo.json to orchestrate builds across the dependency graph. This setup lets the full desktop and server builds combine independently versioned packages at build time.

Can I use @openwork/headless-threads outside of the OpenWork desktop app?

Yes. @openwork/headless-threads is designed as a standalone typed client for driving OpenWork sessions without any UI. You can import createHeadlessThreadClient from the package, point it at any OpenWork server API, and programmatically create threads, send turns, and export transcripts for automation or benchmarking workloads.

What is the difference between @openwork/automations and the Den control plane?

@openwork/automations defines the core domain model for schedules, recurrence, DST handling, and idempotent execution, but it intentionally contains no runtime or persistence layer. The Den cloud control plane provides the actual runtime, leases, and model adapters, while importing the shared logic from this package so that hosted and on-prem engines behave identically.

Where does the OpenWork desktop bootstrap CLI install its files?

The @openwork/openwork-bootstrap package installs the openwork-bootstrap binary into a user-writable directory—commonly ~/.local/bin—and writes install manifests to ~/.openwork/bootstrap. It also downloads platform-specific desktop artifacts such as DMG, AppImage, or EXE files and verifies them before installation.

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