Typical Workflow for Developers Using Openwork: From Clone to Production

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.

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

The pnpm install command reads the 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:

pnpm dev

This command, located in [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/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:

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 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 — Desktop client logic

Changes trigger automatic reloading through the Vite dev server.

5. Run the Test Suite

Validate changes using the testkit runner:

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/dev/AGENTS.md).

6. Build Production Bundles

Create production-ready artifacts:

pnpm build

This script, found at line 31 in [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/:

// 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 or publish to the OpenWork marketplace for remote access.

Key Configuration Files

Understanding these files streamlines the workflow:

• pnpm-workspace.yaml: Declares monorepo packages and controls dependency hoisting
• warden.toml: Configures agent settings, skill loading, and MCP endpoints
• 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
• 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 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 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.

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