# How to Set Up a Development Branch in OpenWork: A Complete Workflow Guide

> Learn how to set up a development branch in OpenWork. Clone the dev branch, create a worktree, and launch with pnpm dev or pnpm dev:worktree for efficient parallel development.

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

---

**Set up an OpenWork development branch by cloning the `dev` branch, creating a Git worktree for isolation, and launching with `pnpm dev` or `pnpm dev:worktree` for parallel development profiles.**

OpenWork's primary development line lives on the `dev` branch, and the repository provides specialized scripts to manage isolated development environments. Whether you're contributing a feature or testing a bug fix, this guide walks through the exact workflow used in the `different-ai/openwork` codebase.

## Clone and Sync the Dev Branch

Start by fetching the latest development code. The `dev` branch is always the target for new work, not `main`.

```bash

# Clone the repository

git clone https://github.com/different-ai/openwork.git
cd openwork

# Ensure you're on dev with latest changes

git checkout dev
git pull --ff-only origin dev

```

As noted in the [README.md](https://github.com/different-ai/openwork/blob/dev/README.md#local-development), running `pnpm dev` with no extra environment variables reuses the existing shared dev profile—suitable for single-checkout workflows.

## Create an Isolated Worktree (Recommended)

For parallel feature work, use a **Git worktree** to keep your main checkout clean. This creates a separate directory linked to the same repository.

```bash

# Create a worktree in a sibling folder

git worktree add ../openwork-feature dev
cd ../openwork-feature

```

The repository includes a dedicated `pnpm dev:worktree` command that automatically creates a worktree-based profile. This handles Chrome DevTools Protocol (CDP) port allocation and prevents conflicts between instances.

## Launch the Development Server

OpenWork supports multiple development modes depending on your needs.

### Standard Electron UI with Shared Profile

```bash
pnpm dev

```

This launches the Electron application with Vite hot-reload, reusing the default shared dev profile.

### Named Profile for Parallel Development

```bash
OPENWORK_DEV_PROFILE=my-feature \
OPENWORK_ELECTRON_REMOTE_DEBUG_PORT=0 \
PORT=0 pnpm dev

```

**Key environment variables:**
- `OPENWORK_DEV_PROFILE` — isolates settings, cache, and browser data
- `OPENWORK_ELECTRON_REMOTE_DEBUG_PORT=0` — auto-assigns CDP port
- `PORT=0` — auto-assigns Vite dev server port

### Headless Web UI (No Electron)

```bash
pnpm dev:headless-web

```

Runs only the browser-based UI without Electron. Useful for lightweight development or when Electron isn't needed. Per the [README](https://github.com/different-ai/openwork/blob/dev/README.md#headless-web-no-electron), this mode supports the same `OPENWORK_DEV_PROFILE` isolation.

### Worktree-Aware Development (Multiple Checkouts)

```bash
pnpm dev:worktree

```

The recommended approach when using worktrees. This script:
- Derives a stable profile name from the worktree path
- Auto-configures unique CDP and Vite ports
- Prevents cross-worktree conflicts

## Verify Your Setup

On successful startup, you'll see a banner similar to:

```

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

```

The `cdp=` URL exposes the **Chrome DevTools Protocol endpoint** for browser automation. This is critical for OpenWork's AI-driven testing and skills system, as documented in [.opencode/skills/browser-automation/SKILL.md](https://github.com/different-ai/openwork/blob/dev/.opencode/skills/browser-automation/SKILL.md).

## Connect to a Local Den Stack (Optional)

If you're running the Den control-plane server locally, proxy the web UI to it:

```bash
OPENWORK_DEV_DEN_PROXY_TARGET=http://127.0.0.1:3005 pnpm dev:web-local

```

Then point the Electron UI at this Den instance via **Settings → Developer Mode**. The [`scripts/dev-web-local.sh`](https://github.com/different-ai/openwork/blob/main/scripts/dev-web-local.sh) implements this proxy logic for the `pnpm dev:web-local` command.

## Complete Setup Script

```bash
#!/bin/bash
set -e

# 1. Clone and sync dev branch

git clone https://github.com/different-ai/openwork.git
cd openwork
git checkout dev && git pull --ff-only origin dev

# 2. Create isolated worktree

git worktree add ../openwork-feature dev
cd ../openwork-feature

# 3. Choose your launch mode:

# Option A: Electron with named profile

OPENWORK_DEV_PROFILE=my-feature \
OPENWORK_ELECTRON_REMOTE_DEBUG_PORT=0 \
PORT=0 pnpm dev

# Option B: Headless web only

# pnpm dev:headless-web

# Option C: Worktree-aware (recommended for multiple branches)

# pnpm dev:worktree

# 4. Optional: Local Den stack

# OPENWORK_DEV_DEN_PROXY_TARGET=http://127.0.0.1:3005 pnpm dev:web-local

```

## Clean Up

Stop processes with `Ctrl-C`, then remove the worktree when finished:

```bash
cd ..
git worktree remove openwork-feature

```

## Summary

- **Target the `dev` branch** — all development work branches from here, not `main`
- **Use Git worktrees** — keeps your primary checkout clean and enables parallel features
- **Leverage `pnpm dev:worktree`** — automatically handles profile and port isolation
- **Set `OPENWORK_DEV_PROFILE`** — essential for running multiple OpenWork instances without data collision
- **Watch for the CDP banner** — confirms successful startup and provides the automation endpoint

## Frequently Asked Questions

### What branch should I base my OpenWork development work on?

Always use the `dev` branch. The `different-ai/openwork` repository maintains `dev` as the primary development line, with `main` reserved for stable releases. The README explicitly directs contributors to `git checkout dev` before starting work.

### How do I prevent conflicts when running multiple OpenWork development instances?

Set a unique `OPENWORK_DEV_PROFILE` environment variable for each instance. This isolates browser data, settings, and cache directories. For worktrees, use `pnpm dev:worktree` which automatically derives a profile name from the worktree path and assigns non-conflicting ports.

### What's the difference between `pnpm dev` and `pnpm dev:worktree`?

**`pnpm dev`** uses a shared default profile unless you manually override environment variables. **`pnpm dev:worktree`** is designed for Git worktrees—it automatically creates a stable profile based on your worktree's directory path and handles CDP/Vite port allocation without manual configuration.

### Can I develop OpenWork without running Electron?

Yes. Run `pnpm dev:headless-web` to launch only the browser-based UI. This mode is documented in the README's "Headless web (no Electron)" section and supports the same environment variables for profile isolation and Den proxying.