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

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.

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.

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 provides high-level architecture details, while 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. For isolated development that uses separate profiles, mock keychains, and auto-assigned ports, use the worktree script:

pnpm dev:worktree

Alternatively, run the standard development environment with:

pnpm dev

The 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 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 runs the same commands you should execute locally:

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:

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 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 descriptor and an index.ts implementation file:

// 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 to include your new skill path:

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

Reference the existing build-a-witness skill in .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
• Submitting PRs that reference the CI workflow in .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. 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.

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