How OpenWork Achieves Development Profile Isolation Using Git Worktrees

OpenWork achieves development profile isolation by deriving unique profile identifiers from Git worktree absolute paths, routing each instance to dedicated Electron user-data directories, and enabling mock keychains to prevent OS credential collisions.

OpenWork is an Electron-based desktop application designed for parallel development workflows using Git worktrees. To prevent configuration collisions when running multiple feature branches simultaneously, the codebase implements a robust development profile isolation system that segregates cookies, caches, and platform credentials. This architecture ensures that each Git worktree operates as a completely independent development environment with its own persistent storage.

Environment-Variable-Driven Profile Naming

The isolation mechanism begins in the dev:worktree script defined in [package.json](https://github.com/different-ai/openwork/blob/dev/package.json#L6‑L8). When you invoke pnpm dev:worktree, the script automatically sets OPENWORK_DEV_PROFILE=auto, triggering the CLI to derive a stable profile name from the absolute file system path of the current Git worktree.

This path-based hashing guarantees that each worktree receives a unique, deterministic identifier. Developers can override this behavior by manually specifying OPENWORK_DEV_PROFILE=<name> when they need predictable profile names for CI pipelines or specific testing scenarios.

Isolating Persistent Storage with Separate User-Data Directories

Once the profile name is established, the main Electron process resolves the user-data folder using the resolveUserDataPath function implemented in apps/desktop/electron/main.mjs. The function incorporates the computed OPENWORK_DEV_PROFILE value into the directory path, ensuring each worktree maintains its own ~/Library/Application Support/<app>.dev-<hash> directory on macOS (or the equivalent location on Windows and Linux).

This separation guarantees that cookies, localStorage, and application cache remain isolated between worktrees. Developers can further customize this behavior using the OPENWORK_ELECTRON_USERDATA environment variable to specify an explicit directory path when needed.

Mock Keychain for Conflict-Free Credential Storage

To prevent macOS from displaying the real "Login" keychain prompt when launching a fresh development instance, OpenWork utilizes a mock keychain mechanism controlled by the OPENWORK_ELECTRON_USE_MOCK_KEYCHAIN environment variable. As implemented in apps/desktop/electron/main.mjs, setting this flag to 1 (the default for dev:worktree) intercepts keychain calls and routes them to an ephemeral storage layer instead of the system keychain.

This approach provides a pristine credential environment for each new profile while allowing developers to disable the mock (=0) when testing integrated authentication flows that require access to the actual OS credential store.

Preventing Concurrent Profile Access

The system includes safeguards against accidental profile sharing. According to the documentation in [README.md](https://github.com/different-ai/openwork/blob/dev/README.md#L98‑L101), when a second instance attempts to start with a profile already in use, the startup banner displays a lock failure and exits cleanly. This prevents port conflicts, data races, and the corruption of SQLite databases or cached state that could occur if multiple processes wrote to the same user-data directory simultaneously.

Practical Usage Examples

The following commands demonstrate how to leverage development profile isolation across different workflows:

# Run a single checkout using the default shared profile

pnpm dev

# Launch with automatic profile isolation based on worktree path

# Sets OPENWORK_DEV_PROFILE=auto and enables mock keychain

pnpm dev:worktree

# Use an explicit profile name for scripted environments

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

# Disable mock keychain to test with real OS credentials while maintaining isolation

OPENWORK_ELECTRON_USE_MOCK_KEYCHAIN=0 OPENWORK_DEV_PROFILE=auto pnpm dev

Summary

• Path-derived profiles: The OPENWORK_DEV_PROFILE=auto setting generates unique identifiers from Git worktree paths, ensuring each checkout receives a distinct identity.
• Directory isolation: The resolveUserDataPath function in main.mjs routes each profile to separate Electron user-data directories, preventing cache and cookie collisions.
• Credential sandboxing: The mock keychain (OPENWORK_ELECTRON_USE_MOCK_KEYCHAIN=1) blocks OS-level credential prompts for fresh profiles while remaining optional for integration testing.
• Process safety: Built-in locking mechanisms prevent multiple instances from accessing the same profile concurrently, eliminating data race conditions.

Frequently Asked Questions

How does OpenWork prevent two development instances from using the same profile?

When a second process attempts to start with a profile already locked by a running instance, the application detects the conflict during startup and exits cleanly after displaying a lock failure banner. This mechanism prevents port conflicts and database corruption by ensuring only one Electron main process accesses a given user-data directory at a time.

Can I use the system keychain instead of the mock keychain in an isolated profile?

Yes. While pnpm dev:worktree defaults to OPENWORK_ELECTRON_USE_MOCK_KEYCHAIN=1 to suppress macOS Login prompts, you can override this by setting OPENWORK_ELECTRON_USE_MOCK_KEYCHAIN=0 when launching the application. This maintains the isolated user-data directory while allowing the app to read and write credentials to the actual operating system keychain.

What happens if I move a Git worktree to a different directory?

Since OpenWork derives the profile name from the absolute file system path, moving the worktree changes the computed hash and creates a new, empty profile. The application will treat the moved directory as a fresh development environment with no cached data or credentials from the previous location.

Is the development profile isolation compatible with Windows and Linux?

Yes. While the mock keychain specifically addresses macOS "Login" keychain prompts, the profile isolation mechanism itself is platform-agnostic. The resolveUserDataPath function calculates the appropriate Electron user-data directory for each operating system, ensuring that Windows (%APPDATA%) and Linux (~/.config) paths remain segregated between worktrees just like macOS (~/Library/Application Support).

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