How to Contribute to OpenWork Development: A Complete Contributor Guide

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, 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 for the main process and 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:

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

2. Install dependencies:

   pnpm install

3. Start the development server:

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

   pnpm dev

   For parallel branch development using worktree mode, use:

   pnpm dev:worktree

   These commands are defined in the root 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:

   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:

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:

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

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:

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:

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 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 and the 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 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.

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