# How to Contribute to OpenWork Development: A Complete Contributor Guide

> Ready to contribute to OpenWork development? Fork the repo, install dependencies, and run locally. Learn how to submit pull requests with our complete contributor guide.

- Repository: [Different AI/openwork](https://github.com/different-ai/openwork)
- Tags: how-to-guide
- Published: 2026-08-01

---

**Fork the repository, install dependencies with `pnpm install`, and run `pnpm dev` to start the Electron desktop application locally before submitting changes via pull request.**

OpenWork is an open-source desktop application for sharing AI workflows, organized as a monorepo that uses pnpm workspaces to manage multiple packages. Contributing to OpenWork development requires understanding its Electron-based architecture, the skills system, and the evaluation framework. This guide walks you through setting up your local environment, navigating the codebase, and submitting high-quality contributions that pass the project's continuous integration pipeline.

## Understanding the OpenWork Architecture

OpenWork follows a monorepo structure defined in [`pnpm-workspace.yaml`](https://github.com/different-ai/openwork/blob/main/pnpm-workspace.yaml), separating concerns between the desktop client, cloud control plane, and extensible plugins.

### Desktop Application (apps/app)

The main OpenWork client is an Electron application with a clear separation between processes. The entry points reside in [`apps/app/main.ts`](https://github.com/different-ai/openwork/blob/main/apps/app/main.ts) for the main process and [`apps/app/renderer.tsx`](https://github.com/different-ai/openwork/blob/main/apps/app/renderer.tsx) for the renderer. The renderer uses React with Tailwind CSS for the user interface. When contributing to the desktop app, you will modify files within `apps/app/src/` and add corresponding tests in `apps/app/tests/`.

### OpenWork Den Control Plane (ee/apps/den-web)

The cloud-side control plane lives under `ee/apps/den-web`, exposing REST endpoints and a Next.js-based UI for organization management. Contributors working on multi-user features or dashboard functionality will focus on this enterprise edition directory, specifically within `ee/apps/den-web/app/(den)/dashboard`.

### Skills and Plugins System

OpenWork extends functionality through skills defined in `.warden/skills/*` and packaged plugins under `packages/plugins/`. The system communicates via `search_capabilities` and `execute_capability` APIs. When adding new AI workflow capabilities, you will create or modify files in these directories to expose new functionalities to the MCP (remote agent).

### Testing and Evaluation Framework

Quality assurance relies on the `evals` package and the **fraimz** skill, which records frame-by-frame proof of behavior for end-to-end testing. Test definitions reside in the `evals/` directory, ensuring that UI changes and skill modifications maintain expected behaviors across different scenarios.

## Setting Up Your Development Environment

Before contributing to OpenWork development, ensure you have Node.js 18 or higher installed, along with pnpm.

1. **Fork and clone the repository:**

   ```bash
   git clone https://github.com/<YOUR_USERNAME>/openwork.git
   cd openwork
   ```

2. **Install dependencies:**

   ```bash
   pnpm install
   ```

3. **Start the development server:**

   The project supports two development modes. For standard development, run:

   ```bash
   pnpm dev
   ```

   For parallel branch development using worktree mode, use:

   ```bash
   pnpm dev:worktree
   ```

   These commands are defined in the root [`package.json`](https://github.com/different-ai/openwork/blob/main/package.json) and leverage the shared dev profile to launch the Electron window.

4. **Verify your setup:**

   Run the full quality check suite to ensure your environment is ready:

   ```bash
   pnpm test
   pnpm run lint
   pnpm run typecheck
   ```

## Contribution Workflow

OpenWork follows a standard fork-branch-pull request workflow with strict quality gates enforced via GitHub Actions in `.github/workflows/`.

### Creating Your Feature Branch

Always branch from the `dev` branch to isolate your changes:

```bash
git checkout -b my-feature

```

### Making Changes and Maintaining Quality

When modifying code in packages like `apps/app` or `packages/plugins`, adhere to the project's strict TypeScript standards (avoiding `any` types) and Tailwind styling conventions. Before committing, run the formatter and linter:

```bash
pnpm format
pnpm lint

```

### Adding Tests

New functionality must include unit or e2e tests. Place test files alongside your code, such as `apps/app/tests/*.test.ts`, or within the `evals/` directory for behavioral evaluations using the fraimz framework.

### Submitting Your Pull Request

1. **Commit your changes** with clear, descriptive messages

2. **Push to your fork:** `git push origin my-feature`

3. **Open a pull request** against the `dev` branch using the template in [`.github/PULL_REQUEST_TEMPLATE.md`](https://github.com/different-ai/openwork/blob/main/.github/PULL_REQUEST_TEMPLATE.md)

4. **Wait for CI** to complete linting, type-checking, and testing

The GitHub Actions pipeline automatically validates every pull request, and maintainers review code before merging into the main codebase.

## Practical Example: Adding a UI Component

Below is a minimal example demonstrating how to add a React component to the desktop application. This example creates a banner component and integrates it into the main app.

Create the component file at [`apps/app/src/components/HelloBanner.tsx`](https://github.com/different-ai/openwork/blob/main/apps/app/src/components/HelloBanner.tsx):

```tsx
import React from 'react';

export const HelloBanner = () => (
  <div className="p-4 bg-indigo-100 text-center rounded">
    👋 Hello, OpenWork!
  </div>
);

```

Import and use the component in [`apps/app/src/App.tsx`](https://github.com/different-ai/openwork/blob/main/apps/app/src/App.tsx):

```tsx
import { HelloBanner } from './components/HelloBanner';

export const App = () => (
  <>
    <HelloBanner />
    {/* existing UI ... */}
  </>
);

```

After saving, run `pnpm dev` to see the changes in the Electron window. Add a corresponding test file at [`apps/app/tests/HelloBanner.test.tsx`](https://github.com/different-ai/openwork/blob/main/apps/app/tests/HelloBanner.test.tsx) to verify the component renders correctly before submitting your contribution.

## Summary

- **OpenWork** is a pnpm monorepo with an Electron desktop app (`apps/app`), Next.js control plane (`ee/apps/den-web`), and extensible skills system (`.warden/skills/`)
- **Local setup** requires Node 18+, `pnpm install`, and running `pnpm dev` or `pnpm dev:worktree` for development
- **Quality standards** include strict TypeScript typing, Tailwind CSS for styling, and comprehensive testing via the `evals` package and fraimz framework
- **Contribution workflow** follows fork-branch-PR pattern with mandatory CI checks for linting, type-checking, and tests defined in `.github/workflows/`
- **Documentation** for agent architecture and development philosophy is available in [`AGENTS.md`](https://github.com/different-ai/openwork/blob/main/AGENTS.md) and the [`README.md`](https://github.com/different-ai/openwork/blob/main/README.md)

## Frequently Asked Questions

### What Node.js version is required to contribute to OpenWork?

OpenWork requires Node.js 18 or higher to run the development server and build processes. The project uses pnpm as its package manager, which you should install globally before running `pnpm install` in the repository root.

### How do I test my changes before submitting a pull request?

Run the complete verification suite using `pnpm test`, `pnpm run lint`, and `pnpm run typecheck` from the repository root. For behavioral validation, the project uses the fraimz skill within the `evals/` package to record frame-by-frame proofs of UI behavior, ensuring your changes do not break existing workflows.

### Where should I add new AI workflow capabilities?

Add new skills to the `.warden/skills/` directory or create packaged plugins under `packages/plugins/`. These integrate with the MCP (remote agent) via the `search_capabilities` and `execute_capability` APIs. Refer to [`AGENTS.md`](https://github.com/different-ai/openwork/blob/main/AGENTS.md) for the "demo-first" development philosophy governing skill creation.

### What is the difference between `pnpm dev` and `pnpm dev:worktree`?

Use `pnpm dev` for standard single-checkout development, which launches the Electron application using the shared dev profile. Use `pnpm dev:worktree` when working with parallel Git branches, as it supports worktree mode for simultaneous development on multiple features without switching branches.