Openwork Project Structure: A Complete Guide to the Monorepo Architecture

Openwork is organized as a pnpm workspace monoreo containing an Electron-based desktop client, a web-based Den control plane, shared TypeScript packages, and end-to-end evaluation suites that generate fraimz proofs, all orchestrated via TurboRepo and secured through the Warden static-analysis framework.

The Openwork repository (different-ai/openwork) implements a modern monorepo architecture that separates runnable applications from reusable libraries while enforcing strict security and testing standards. Understanding how this codebase is structured is essential for contributors extending the desktop client, adding OpenCode skills, or troubleshooting build pipelines.

Repository Layout Overview

The repository root organizes code into distinct functional domains. At the highest level, Openwork separates applications from shared libraries, testing infrastructure, and specialized configuration files.

Applications (apps/)

The apps/ directory houses the primary deliverables. The apps/desktop/ folder contains the Electron-based client with its main process, preload scripts, and renderer code. The apps/den/ folder hosts the web-based cloud control plane and API gateway. Each application maintains its own Vite configuration and entry points while importing shared components from the workspace.

Shared Packages (packages/)

Reusable TypeScript libraries live in packages/, including the React component library at packages/ui/ (based on shadcn/ui), state management stores, and API clients. These packages are published internally within the workspace and consumed by both the desktop and web applications.

Testing & Validation (evals/)

The evals/ directory contains end-to-end test suites that drive the Electron application via CDP (Chrome DevTools Protocol). These scripts generate fraimz proof-of-concept artifacts in evals/results/<run-id>/fraimz.html that serve as the canonical verification of UI behavior across changes.

Documentation & Examples

Supporting materials include docs/ for public documentation and tutorials, examples/ for reference projects demonstrating skill embedding, and prds/ containing product requirement documents that act as demo-first specifications for new features.

Configuration & Tooling

Infrastructure folders include .github/ for CI/CD workflows, .devcontainer/ for standardized VS Code development environments, and scripts/ for automation tasks like version bumping and changelog generation. The .opencode/ directory stores skill registries and MCP (Model Container Protocol) definitions consumed by the runtime at execution time.

Key Configuration Files

Several root-level files define how the monorepo behaves and orchestrates builds:

• pnpm-workspace.yaml: Declares all package locations, enabling pnpm to hoist shared dependencies and execute commands across the entire repository using pnpm dev or pnpm build.
• turbo.json: Configures TurboRepo pipelines with dependency graphs for install, build, lint, and test tasks, ensuring only modified packages trigger rebuilds and dramatically speeding up CI.
• warden.toml: Defines security policies for the Warden static-analysis framework, which performs automated diff-security reviews during pull requests by evaluating definitions in .warden/skills/.
• package.json: Contains root-level scripts, workspace metadata, and top-level dependencies that apply across all packages.
• AGENTS.md: Documents built-in Openwork agents, available skills, and MCP endpoints for the OpenCode integration.

How the Architecture Fits Together

The Openwork project structure follows a specific orchestration pattern that connects development, security, and runtime components:

1. Workspace Resolution: pnpm-workspace.yaml identifies all folders containing package.json files, establishing the pnpm workspace boundaries and internal package linking.

2. Build Orchestration: TurboRepo reads turbo.json to parallelize builds across the dependency graph, caching results to accelerate both local development and CI pipelines.

3. Security Enforcement: Warden evaluates warden.toml and .warden/skills/ definitions to lint code for security issues before merge, providing automated diff reviews.

4. Runtime Integration: The desktop client loads skills from .opencode/skills/ via MCP definitions referenced in AGENTS.md, enabling dynamic agent capabilities.

5. Verification: The evals/ suite launches the built Electron application, drives interactions through CDP, and generates fraimz HTML reports that verify UI behavior.

Working with the Openwork Codebase

Starting Development

Install dependencies and launch the default development profile:

pnpm install
pnpm dev

This starts the Vite dev server and Electron client, printing a banner with the CDP endpoint:

[openwork] dev profile=default cdp=http://127.0.0.1:9223

Running End-to-End Evaluations

Execute the evaluation suite to generate fraimz proof artifacts:

pnpm run eval:demo-flow

This script located in evals/demo-flow/ produces verification reports at evals/results/<run-id>/fraimz.html.

Adding a New UI Component

Create shared components using the workspace scaffolding:

pnpm exec nx generate @nrwl/react:library button --directory=packages/ui

Then import the component into the desktop application:

import { Button } from '@openwork/ui/button';

Registering an OpenCode Skill

Add skill descriptors to .opencode/skills/:

{
  "name": "my-skill",
  "description": "Performs a custom transformation on text.",
  "inputSchema": { "type": "object", "properties": { "text": { "type": "string" } } },
  "outputSchema": { "type": "object", "properties": { "result": { "type": "string" } } }
}

Reference the skill in AGENTS.md and commit to trigger automatic validation via the CI pipeline defined in .github/workflows/.

Summary

• Openwork uses a pnpm workspace monorepo structure separating apps/, packages/, and evals/ into distinct functional domains.
• TurboRepo orchestrates builds via turbo.json, caching incremental changes to optimize CI performance.
• Warden provides automated security analysis through warden.toml and .warden/skills/ definitions.
• The OpenCode runtime consumes skill definitions from .opencode/ and MCP configurations referenced in AGENTS.md.
• Fraimz proofs in evals/ provide end-to-end verification via CDP automation, generating HTML reports in evals/results/.

Frequently Asked Questions

What is the purpose of the Den application in Openwork?

The Den application (apps/den/) serves as the web-based cloud control plane and API gateway, complementing the desktop Electron client by providing browser-accessible management interfaces and backend services for remote skill orchestration.

How does Openwork handle package dependencies across the monorepo?

Openwork leverages pnpm workspaces defined in pnpm-workspace.yaml to hoist shared dependencies and link internal packages, allowing consistent versioning across apps/desktop/ and apps/den/ while preventing duplicate installations of common libraries like React or TypeScript.

What are fraimz proofs in the evals directory?

Fraimz proofs are HTML artifacts generated by end-to-end tests in evals/ that drive the Electron application via Chrome DevTools Protocol (CDP). These files provide visual and functional verification of UI behavior, serving as the definitive proof that features work correctly before merging changes.

Where are OpenCode skills defined in the repository?

Skills are defined as JSON descriptors in .opencode/skills/ and referenced in AGENTS.md. The desktop client loads these at runtime through the Model Container Protocol (MCP), enabling dynamic skill registration and extending agent capabilities without recompiling the application.

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