# How to Contribute to the OpenWork Project: A Complete Developer Guide

> Learn how to contribute to the OpenWork project. Fork the repo, set up your environment with pnpm, run tests, and submit a pull request. Start contributing today!

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

---

**To contribute to the OpenWork project, fork the repository, set up your development environment with `pnpm`, run the test suite with `pnpm test:e2e`, and submit a pull request following the CI workflow defined in [`.github/workflows/ci-tests.yml`](https://github.com/different-ai/openwork/blob/main/.github/workflows/ci-tests.yml).**

OpenWork is an open-source desktop application that enables sharing AI workflows across agents, teams, and devices. The project is organized as a monorepo using pnpm workspaces, with the core desktop application residing in `apps/desktop` and the back-end control plane in `apps/den-web/`. Contributing to the OpenWork project requires setting up the Electron environment and following the validation workflows defined in the source code.

## Setting Up Your Development Environment

Start by forking the repository and cloning it locally. The project uses **pnpm** as its package manager, which is required to handle the workspace dependencies correctly.

```bash
git clone https://github.com/different-ai/openwork.git
cd openwork
pnpm install

```

After installation, verify your setup by reviewing the core documentation. The [`README.md`](https://github.com/different-ai/openwork/blob/main/README.md) provides high-level architecture details, while [`AGENTS.md`](https://github.com/different-ai/openwork/blob/main/AGENTS.md) describes the agent interaction philosophy and the **fraimz** validation workflow. These files are essential reading before you begin coding.

## Starting the Development Server

Launch the desktop application in development mode using the scripts defined in the root [`package.json`](https://github.com/different-ai/openwork/blob/main/package.json). For isolated development that uses separate profiles, mock keychains, and auto-assigned ports, use the worktree script:

```bash
pnpm dev:worktree

```

Alternatively, run the standard development environment with:

```bash
pnpm dev

```

The [`pnpm-workspace.yaml`](https://github.com/different-ai/openwork/blob/main/pnpm-workspace.yaml) file defines the monorepo structure, including `apps/*`, `packages/*`, and `packages/skills/*` directories. The desktop application entry point is located at [`apps/desktop/package.json`](https://github.com/different-ai/openwork/blob/main/apps/desktop/package.json) under the package name `@openwork/desktop`.

## Running the Test Suite

Before submitting changes, validate your code against the automated test pipeline. The CI workflow in [`.github/workflows/ci-tests.yml`](https://github.com/different-ai/openwork/blob/main/.github/workflows/ci-tests.yml) runs the same commands you should execute locally:

```bash
pnpm typecheck           # TypeScript validation across the monorepo

pnpm test:e2e            # End-to-end tests for the desktop UI

pnpm test:admin-scale    # Integration tests for the Den back-end

```

Running these commands ensures that your changes do not break existing functionality in the Electron application or the Den control plane.

## Contributing Code to OpenWork

### Creating a Feature Branch

Create a descriptive branch name that reflects your intended changes:

```bash
git checkout -b feature/my-new-skill

```

### Writing Code and Tests

Follow the project's TypeScript conventions, specifically avoiding the use of `any` types and utilizing **shadcn/ui** components for interface elements. When adding features, include corresponding unit or E2E tests that cover the new behavior.

For multi-profile testing scenarios, the repository includes a helper script at `scripts/dev-two-electron-demo.mjs` that runs two Electron instances side-by-side.

### Opening a Pull Request

Push your branch to your fork and open a Pull Request against the `dev` branch. The repository includes a PR template in [`.github/pull_request_template.md`](https://github.com/different-ai/openwork/blob/main/.github/pull_request_template.md) that you should follow. The CI will automatically run `pnpm test:e2e` and `pnpm typecheck` against your submission.

Address any review feedback iteratively. Once approved, maintainers will merge your PR using the release scripts located in `scripts/release/*.mjs`.

## Adding New Skills to OpenWork

Skills are reusable plugins stored in `.opencode/skills/`. To add a new skill, create a directory with a [`SKILL.md`](https://github.com/different-ai/openwork/blob/main/SKILL.md) descriptor and an [`index.ts`](https://github.com/different-ai/openwork/blob/main/index.ts) implementation file:

```typescript
// file: packages/skills/my-new-skill/SKILL.md
name: my-new-skill
description: "A demo skill that echoes back the input."

// file: packages/skills/my-new-skill/index.ts
export const run = async (input: string) => {
  return `Echo: ${input}`;
};

```

Update the workspace configuration in the root [`package.json`](https://github.com/different-ai/openwork/blob/main/package.json) to include your new skill path:

```json
{
  "workspaces": [
    "packages/*",
    "packages/skills/*"
  ]
}

```

Reference the existing **build-a-witness** skill in [`.opencode/skills/build-a-witness/SKILL.md`](https://github.com/different-ai/openwork/blob/main/.opencode/skills/build-a-witness/SKILL.md) for implementation patterns.

## Summary

Contributing to the OpenWork project involves forking the repository, installing dependencies with `pnpm`, and validating changes through the E2E test suite. Key steps include:

- Setting up the development environment using `pnpm install` and `pnpm dev:worktree`
- Running `pnpm test:e2e` and `pnpm typecheck` before submitting code
- Following the monorepo structure defined in [`pnpm-workspace.yaml`](https://github.com/different-ai/openwork/blob/main/pnpm-workspace.yaml)
- Submitting PRs that reference the CI workflow in [`.github/workflows/ci-tests.yml`](https://github.com/different-ai/openwork/blob/main/.github/workflows/ci-tests.yml)
- Adding new skills in `.opencode/skills/` with proper documentation

## Frequently Asked Questions

### What is the OpenWork project?

OpenWork is an open-source desktop application that lets you share AI workflows across agents, teams, and devices. It consists of an Electron-based desktop client and a Den back-end control plane for team management.

### Do I need to run tests before submitting a PR?

Yes, you must run `pnpm test:e2e` and `pnpm typecheck` locally to ensure your changes pass the same validation steps executed by the CI pipeline in [`.github/workflows/ci-tests.yml`](https://github.com/different-ai/openwork/blob/main/.github/workflows/ci-tests.yml). The test suite covers both the desktop UI and back-end integration points.

### How do I set up the desktop application for development?

Clone the repository, run `pnpm install` to install workspace dependencies, then execute `pnpm dev:worktree` to launch the desktop app in development mode. This script uses separate profiles and mock keychains to avoid conflicts with production data.

### Where can I find open issues to work on?

Visit the GitHub Issues page at `https://github.com/different-ai/openwork/issues` to find tasks ranging from UI bug fixes to new skill development. Look for issues labeled **good first issue** if you are new to the codebase.