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

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.

# 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, 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.

# 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

pnpm dev

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

Named Profile for Parallel Development

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)

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, this mode supports the same OPENWORK_DEV_PROFILE isolation.

Worktree-Aware Development (Multiple Checkouts)

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.

Connect to a Local Den Stack (Optional)

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

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 implements this proxy logic for the pnpm dev:web-local command.

Complete Setup Script

#!/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:

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.

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