Contributing to Openwork

Welcome to the Openwork community! Thank you for your interest in contributing to this open-source desktop automation assistant.

Getting Started

Fork the repository on GitHub

Clone your fork locally:

git clone https://github.com/YOUR_USERNAME/openwork.git

Install dependencies:
```
pnpm install
```

Create a feature branch:

git checkout -b feature/your-feature-name

Development Environment

Common Development Commands

# Run the desktop app in development mode
pnpm dev

# Run with clean start (clears stored data)
pnpm dev:clean

# Build all workspaces
pnpm build

# Build desktop app only
pnpm build:desktop

# Run TypeScript checks
pnpm typecheck

# Run linting
pnpm lint

# Clean build outputs
pnpm clean

Running E2E Tests

# Run Playwright E2E tests
pnpm -F @accomplish/desktop test:e2e

# Run E2E with UI mode
pnpm -F @accomplish/desktop test:e2e:ui

# Run E2E in debug mode
pnpm -F @accomplish/desktop test:e2e:debug

Project Overview

Openwork is a standalone desktop automation assistant built with Electron. The application features:

Local React UI bundled via Vite
Main process communication through contextBridge IPC
OpenCode CLI integration via node-pty for task execution
Multi-provider API support (Anthropic, OpenAI, Google, Groq)
Secure API key storage using OS keychain

Architecture

The project uses a monorepo structure:

apps/desktop/     # Electron app (main/preload/renderer)
packages/shared/  # Shared TypeScript types

Code Style Guidelines

TypeScript Requirements

TypeScript everywhere (no JavaScript for app logic)
Use pnpm -F @accomplish/desktop ... for desktop-specific commands
Shared types go in packages/shared/src/types/
Renderer state via Zustand store actions
IPC handlers must match the window.accomplish API in preload

Image Asset Handling

IMPORTANT: Always use ES module imports for images in the renderer, never absolute paths.

// CORRECT - Use ES imports
import logoImage from '/assets/logo.png';
<img src={logoImage} alt="Logo" />

// WRONG - Absolute paths break in packaged app
<img src="/assets/logo.png" alt="Logo" />

Static assets should be placed in apps/desktop/public/assets/.

Environment Variables

CLEAN_START=1 - Clear all stored data on app start
E2E_SKIP_AUTH=1 - Skip onboarding flow (for testing)

Bundled Node.js

The packaged app includes standalone Node.js v20.18.1 binaries to ensure MCP servers work on machines without Node.js installed.

Key Files for Node.js Integration

src/main/utils/bundled-node.ts - Utility to get bundled node/npm/npx paths
scripts/download-nodejs.cjs - Downloads Node.js binaries for all platforms
scripts/after-pack.cjs - Copies correct binary into app bundle during build

Community Guidelines

Code of Conduct

Be respectful and inclusive
Focus on constructive feedback
Help newcomers and share knowledge
Follow the project’s technical standards

Quality Standards

Ensure code builds without errors (pnpm build)
Pass all TypeScript checks (pnpm typecheck)
Follow existing code patterns and conventions
Write clear, descriptive commit messages
Update documentation when making changes

Reporting Issues

When reporting issues, please include:

Operating system and version
Steps to reproduce the issue
Expected vs actual behavior
Any error messages or logs
Screenshots if applicable

Feature Requests

We welcome feature requests! Please:

Check if the feature already exists
Provide clear use cases and requirements
Explain how the feature would benefit users
Consider implementation complexity if possible

Getting Help

GitHub Issues: Use for bug reports and feature requests
Discussions: For general questions and community discussions
Code Reviews: Participate in PR reviews to help maintain code quality

Security

If you discover a security vulnerability, please see SECURITY.md for responsible disclosure guidelines.

License

By contributing to Openwork, you agree that your contributions will be licensed under the MIT License.

Thank you for helping make Openwork better for everyone!