# How to Contribute to different-ai/openwork: A Complete Developer Guide

> Learn how to contribute to different-ai/openwork with this developer guide. Fork the repo, install dependencies, run tests, and submit your pull request for seamless contributions.

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

---

**To contribute to different-ai/openwork, fork the repository, install dependencies with `pnpm install`, run `pnpm dev:worktree` for isolated development, make changes in the appropriate package layer, and open a pull request after running `pnpm test:e2e`.**

The **different-ai/openwork** repository is a comprehensive monorepo powering a desktop AI-workflow client, a cloud-hosted "Den" control plane, and a modular ecosystem of reusable skills and plugins. This guide walks you through every layer of the codebase and provides exact commands and file paths to start contributing confidently.

---

## Understanding the OpenWork Monorepo Architecture

OpenWork uses **pnpm workspaces** orchestrated by **TurboRepo** to manage dozens of interdependent packages. Knowing which layer handles what saves hours of exploration.

### Workspace and Build System

The root configuration defines how code moves from source to production:

- **[`pnpm-workspace.yaml`](https://github.com/different-ai/openwork/blob/main/pnpm-workspace.yaml)** – Declares all packages in the monorepo
- **[`turbo.json`](https://github.com/different-ai/openwork/blob/main/turbo.json)** – Configures parallel task pipelines (build, test, lint)

```bash

# See all workspace packages

cat pnpm-workspace.yaml

```

### Core Desktop Application (`@openwork/app`)

The Electron-based UI splits cleanly between front-end and native glue:

| Directory | Purpose |
|-----------|---------|
| `packages/app/src/react-app` | React components, routing, and state management |
| `packages/app/src/electron` | Electron main process and native integrations |

### OpenWork Den (Cloud Control Plane)

Enterprise-tier services live under `packages/ee/`:

- **`packages/ee/den-api`** – API server for authentication and model provisioning
- **`packages/ee/den-web`** – Web-based management interface
- **`packages/ee/den-db`** – Prisma schema and database migrations

### Skills and Plugins (OpenCode Integration)

Reusable AI capabilities ship as **OpenCode skills** in `.opencode/skills/`. Each skill folder contains a [`SKILL.md`](https://github.com/different-ai/openwork/blob/main/SKILL.md) that auto-registers with the runtime. Example: `.opencode/skills/build-a-witness` creates deterministic test witnesses for validation.

### Development and Testing Infrastructure

| Tool | Location | Purpose |
|------|----------|---------|
| `scripts/dev-local.mjs` | `scripts/` | Boots Den and desktop app simultaneously |
| `scripts/release/prepare.mjs` | `scripts/release/` | Automates version bumps and changelogs |
| `evals/runner/run.mjs` | `evals/` | End-to-end test orchestration |
| Package `test/` folders | Per-package | Unit tests using framework of choice |

---

## Step-by-Step Contribution Workflow

### 1. Fork and Clone the Repository

```bash
git clone https://github.com/<your-username>/openwork.git
cd openwork

```

### 2. Install Dependencies

OpenWork requires **pnpm** (not npm or yarn). The lockfile ensures reproducible installs:

```bash
pnpm install

```

### 3. Start the Local Development Environment

Two modes support different workflows:

**`pnpm dev`** – Single checkout, standard development
**`pnpm dev:worktree`** – Isolated profile for parallel instances (recommended for active contributors)

```bash

# Recommended: isolated worktree with unique profile

pnpm dev:worktree

# Output: [openwork] dev profile=worktree-123 cdp=http://127.0.0.1:9223

```

Environment variables for API keys and service endpoints are documented in the README's *Local development* section.

### 4. Make Targeted Changes

| Contribution Type | Target Directory |
|-------------------|----------------|
| UI components or React logic | `packages/app/src/react-app/...` |
| Electron native features | `packages/app/src/electron/...` |
| Den API endpoints | `packages/ee/den-api/...` |
| New OpenCode skill | `.opencode/skills/your-skill-name/` (include [`SKILL.md`](https://github.com/different-ai/openwork/blob/main/SKILL.md)) |

### 5. Run Appropriate Tests

**Unit tests for specific package:**

```bash
pnpm --filter @openwork/app test

# Replace @openwork/app with @openwork-ee/den-api, etc.

```

**Full end-to-end suite (mandatory before PR):**

```bash
pnpm test:e2e

# Launches Den, Electron, and executes all @openwork/testkit specifications

```

### 6. Commit and Open Pull Request

Follow the automatic PR template: describe changes, attach screenshots for UI modifications, and reference related issues. The CI pipeline validates lint, type-checking, and tests on every push.

---

## Practical Code Examples for Contributors

### Example 1: Creating a New OpenCode Skill

Skills auto-load when placed in `.opencode/skills/` with a [`SKILL.md`](https://github.com/different-ai/openwork/blob/main/SKILL.md):

```bash
mkdir -p .opencode/skills/hello-world

cat > .opencode/skills/hello-world/SKILL.md <<'EOF'

# Hello World Skill

## Description

Returns a greeting from the OpenWork runtime.

## Implementation

```ts
export async function run(context) {
  return "👋 Hello from OpenWork!"
}

```

EOF

```

Restart the dev server to register the new skill.

### Example 2: Publishing Package Updates

Maintainers use version-bump scripts with automatic changelog generation:

```bash

# Bump @openwork/app from 0.1.2 → 0.1.3

pnpm bump:patch

# Available: bump:patch, bump:minor, bump:major

```

---

## Essential Files Every Contributor Should Know

| File | Purpose | Direct Link |
|------|---------|-------------|
| [`README.md`](https://github.com/different-ai/openwork/blob/main/README.md) | Installation, dev commands, environment setup | [README.md](https://github.com/different-ai/openwork/blob/dev/README.md) |
| [`package.json`](https://github.com/different-ai/openwork/blob/main/package.json) | Workspace scripts and pnpm metadata | [package.json](https://github.com/different-ai/openwork/blob/dev/package.json) |
| [`pnpm-workspace.yaml`](https://github.com/different-ai/openwork/blob/main/pnpm-workspace.yaml) | Monorepo package registry | [pnpm-workspace.yaml](https://github.com/different-ai/openwork/blob/dev/pnpm-workspace.yaml) |
| [`turbo.json`](https://github.com/different-ai/openwork/blob/main/turbo.json) | TurboRepo pipeline configuration | [turbo.json](https://github.com/different-ai/openwork/blob/dev/turbo.json) |
| [`AGENTS.md`](https://github.com/different-ai/openwork/blob/main/AGENTS.md) | Agent model and interaction patterns | [AGENTS.md](https://github.com/different-ai/openwork/blob/dev/AGENTS.md) |
| [`TRANSLATIONS.md`](https://github.com/different-ai/openwork/blob/main/TRANSLATIONS.md) | Localization guidelines | [TRANSLATIONS.md](https://github.com/different-ai/openwork/blob/dev/TRANSLATIONS.md) |
| [`CODE_OF_CONDUCT.md`](https://github.com/different-ai/openwork/blob/main/CODE_OF_CONDUCT.md) | Community standards | [CODE_OF_CONDUCT.md](https://github.com/different-ai/openwork/blob/dev/CODE_OF_CONDUCT.md) |

---

## Advanced Development Patterns

### Running Multiple Dev Instances Simultaneously

The `pnpm dev:worktree` command generates isolated profiles with unique Chrome DevTools Protocol ports. This prevents state collision when testing multi-user scenarios or comparing feature branches side-by-side.

### Local Stack Orchestration

`scripts/dev-local.mjs` coordinates the Den control plane and desktop application in one terminal:

```bash
node scripts/dev-local.mjs

# Equivalent to manually starting den-api, den-web, and @openwork/app

```

---

## Summary

- **Fork, clone, and install** with `pnpm install` to begin contributing to different-ai/openwork
- **Use `pnpm dev:worktree`** for isolated development environments that support parallel instances
- **Target the correct layer**: React UI in `packages/app/src/react-app/`, API changes in `packages/ee/den-api/`, skills in `.opencode/skills/`
- **Always run `pnpm test:e2e`** before submitting pull requests to validate end-to-end behavior
- **Reference [`AGENTS.md`](https://github.com/different-ai/openwork/blob/main/AGENTS.md) and [`TRANSLATIONS.md`](https://github.com/different-ai/openwork/blob/main/TRANSLATIONS.md)** for specialized contribution types

---

## Frequently Asked Questions

### What package manager does openwork require?

**pnpm is mandatory.** The [`pnpm-workspace.yaml`](https://github.com/different-ai/openwork/blob/main/pnpm-workspace.yaml) and [`pnpm-lock.yaml`](https://github.com/different-ai/openwork/blob/main/pnpm-lock.yaml) files define the monorepo structure. Using npm or yarn will produce inconsistent dependency trees and fail CI validation.

### How do I test changes to an OpenCode skill?

Create your skill in `.opencode/skills/your-name/` with a [`SKILL.md`](https://github.com/different-ai/openwork/blob/main/SKILL.md) file, restart the dev server with `pnpm dev:worktree`, and invoke the skill through the OpenWork desktop app. The runtime auto-discovers any valid skill directory.

### What should I do before opening a pull request?

Run the full validation suite: `pnpm test:e2e` executes end-to-end tests across the Den, Electron, and skill systems. Additionally, ensure your branch passes `pnpm lint` and `pnpm type-check`—these run automatically in CI but catching errors locally speeds review.

### How does the Den control plane differ from the desktop app?

The **Den** (`packages/ee/den-*`) is a cloud-hosted service stack handling authentication, organization management, and model provisioning. The **desktop app** (`packages/app`) is a local Electron client that optionally connects to a Den instance. Contributing to Den requires database migrations in `packages/ee/den-db/`, while desktop work focuses on React and Electron code.