# Typical Workflow for Developers Using Openwork: From Clone to Production

> Discover the typical Openwork developer workflow from cloning the repo to production. Learn to launch dev servers, manage isolated profiles, and publish skills to the MCP layer efficiently.

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

---

**The typical Openwork developer workflow involves cloning the pnpm monorepo, running `pnpm dev` to launch the Electron client and Vite dev servers, optionally using `pnpm dev:worktree` for isolated profiles, and iterating through code changes, tests, and builds entirely locally before publishing skills to the MCP layer.**

The `different-ai/openwork` repository is a local-first, multi-package monorepo that combines an Electron-based desktop client with a programmable MCP (Model Context Protocol) layer. Understanding the typical workflow for developers using Openwork ensures you can efficiently build, test, and publish new skills while maintaining isolated development environments.

## Step-by-Step Openwork Development Workflow

### 1. Clone the Repository and Install Dependencies

Start by cloning the repository and installing dependencies using pnpm workspaces.

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

```

The `pnpm install` command reads the [`pnpm-workspace.yaml`](https://github.com/different-ai/openwork/blob/main/pnpm-workspace.yaml) file to create a shared `node_modules` tree across all packages in the monorepo.

### 2. Start the Development Session

Launch the default development environment using the `dev` script defined in the root [`package.json`](https://github.com/different-ai/openwork/blob/main/package.json):

```bash
pnpm dev

```

This command, located in [[`package.json`](https://github.com/different-ai/openwork/blob/main/package.json)](https://github.com/different-ai/openwork/blob/dev/package.json#L27) at line 27, simultaneously starts the Electron UI and Vite dev servers for the web interface. Upon startup, the terminal displays a banner indicating the dev profile and Chrome DevTools Protocol (CDP) port:

```

[openwork] dev profile=default cdp=http://127.0.0.1:9223

```

The Electron main process initialization resides in [[`apps/electron/main.ts`](https://github.com/different-ai/openwork/blob/main/apps/electron/main.ts)](https://github.com/different-ai/openwork/blob/dev/apps/electron/main.ts), which handles the dev profile configuration.

### 3. Use Worktrees for Parallel Development

For feature work requiring isolated environments, use the worktree command:

```bash
pnpm dev:worktree

```

This sets `OPENWORK_DEV_PROFILE=auto`, creating a separate Electron profile with its own CDP port. This allows multiple instances to run side-by-side without conflicts, as documented in the [Local development](https://github.com/different-ai/openwork/blob/dev/README.md#local-development) section of the README.

### 4. Edit Code with Hot Reloading

Modify code within the relevant package directories:

- **Skills**: `packages/skills/*` — Each skill is a self-contained module auto-exposed via MCP
- **Web UI**: `apps/web/*` — React components with Vite hot module replacement
- **Electron Main**: [`apps/electron/main.ts`](https://github.com/different-ai/openwork/blob/main/apps/electron/main.ts) — Desktop client logic

Changes trigger automatic reloading through the Vite dev server.

### 5. Run the Test Suite

Validate changes using the testkit runner:

```bash
pnpm test

```

Tests are defined in `evals/specs/**/*.test.ts` and powered by `@openwork/testkit`. This agent-first verification approach ensures skills behave correctly before publication, as outlined in [[`AGENTS.md`](https://github.com/different-ai/openwork/blob/main/AGENTS.md)](https://github.com/different-ai/openwork/blob/dev/AGENTS.md).

### 6. Build Production Bundles

Create production-ready artifacts:

```bash
pnpm build

```

This script, found at line 31 in [[`package.json`](https://github.com/different-ai/openwork/blob/main/package.json)](https://github.com/different-ai/openwork/blob/dev/package.json#L31), generates optimized bundles for both the desktop client and web UI, outputting to the `dist/` directory.

### 7. Publish Skills

Add new capabilities by creating a skill in `packages/skills/`:

```typescript
// packages/skills/hello-world/skill.ts
export const helloWorld = {
  name: "hello-world",
  description: "Returns a friendly greeting",
  run: async () => "👋 Hello from OpenWork!"
}

```

The MCP layer automatically exposes local skills to connected agents. Configure the skill in [`warden.toml`](https://github.com/different-ai/openwork/blob/main/warden.toml) or publish to the OpenWork marketplace for remote access.

## Key Configuration Files

Understanding these files streamlines the workflow:

- **[`pnpm-workspace.yaml`](https://github.com/different-ai/openwork/blob/main/pnpm-workspace.yaml)**: Declares monorepo packages and controls dependency hoisting
- **[`warden.toml`](https://github.com/different-ai/openwork/blob/main/warden.toml)**: Configures agent settings, skill loading, and MCP endpoints
- **[`package.json`](https://github.com/different-ai/openwork/blob/main/package.json) (root)**: Defines workspace scripts (`dev`, `dev:worktree`, `test`, `build`)
- **`evals/specs/`**: Houses E2E test specifications for agent verification

## Summary

- Openwork uses a **pnpm workspace** monorepo structure with shared dependency management via [`pnpm-workspace.yaml`](https://github.com/different-ai/openwork/blob/main/pnpm-workspace.yaml)
- **Local-first development** requires only `pnpm dev` to launch the Electron client and Vite servers
- **Worktree profiles** (`pnpm dev:worktree`) enable parallel development with isolated Electron instances and unique CDP ports
- The **MCP layer** automatically exposes skills from `packages/skills/` to connected agents
- **Agent-first verification** via `pnpm test` runs specifications from `evals/specs/` before code reaches production

## Frequently Asked Questions

### What are the prerequisites for the Openwork developer workflow?

You need Git, Node.js, and pnpm installed locally. The repository relies on pnpm workspaces to manage the multi-package structure, so npm or yarn will not work correctly with the existing [`pnpm-workspace.yaml`](https://github.com/different-ai/openwork/blob/main/pnpm-workspace.yaml) configuration. The setup is designed to be entirely local-first, requiring no external services to begin development.

### How do I run multiple Openwork instances simultaneously for different features?

Use the `pnpm dev:worktree` command, which automatically sets `OPENWORK_DEV_PROFILE=auto` to create isolated profiles. Each instance receives its own Electron profile directory and CDP port, preventing conflicts when testing different branches or features side-by-side. The startup banner indicates the specific profile and port assigned to each instance.

### Where do I add new skills in the Openwork codebase?

Create a new directory under `packages/skills/` containing your skill definition with an exported run function. The MCP system automatically discovers and exposes these local skills to any connected agent according to the [`warden.toml`](https://github.com/different-ai/openwork/blob/main/warden.toml) configuration. For production deployment, you can publish skills to the OpenWork marketplace where they become available to other users.

### What testing framework does Openwork use for verification?

Openwork uses `@openwork/testkit` to run agent-first verification tests located in `evals/specs/**/*.test.ts`. Running `pnpm test` executes these specifications, ensuring that skills and UI components meet the expected behavioral contracts before merging. This agent-first approach means tests simulate real agent interactions rather than just unit testing isolated functions.