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

> Explore the OpenWork monorepo's packages. Understand the purpose of each npm package, from UI to automation, and how they build the system.

- Repository: [Different AI/openwork](https://github.com/different-ai/openwork)
- Tags: deep-dive
- Published: 2026-08-14

---

**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`](https://github.com/different-ai/openwork/blob/main/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`](https://github.com/different-ai/openwork/blob/main/packages/automations/src/schedule.ts).

```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`](https://github.com/different-ai/openwork/blob/main/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`](https://github.com/different-ai/openwork/blob/main/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`](https://github.com/different-ai/openwork/blob/main/packages/headless-threads/src/client.ts).

```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`](https://github.com/different-ai/openwork/blob/main/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`.

```bash

# 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`](https://github.com/different-ai/openwork/blob/main/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`](https://github.com/different-ai/openwork/blob/main/pnpm-workspace.yaml)) and **Turbo** ([`turbo.json`](https://github.com/different-ai/openwork/blob/main/turbo.json)).

## Frequently Asked Questions

### What build tools manage the OpenWork monorepo packages?

The monorepo uses **pnpm workspaces** defined in [`pnpm-workspace.yaml`](https://github.com/different-ai/openwork/blob/main/pnpm-workspace.yaml) to discover packages, and **Turbo** configured in [`turbo.json`](https://github.com/different-ai/openwork/blob/main/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.