Disclaimer: This documentation is an independent community resource. It is not affiliated with, endorsed by, or associated with Accomplish Inc or the accomplish-ai/openwork project.

Document Validity

  • Target Commit: 8855d5f31ca0dd485379af1ad241071fe62052a0
  • Last Updated: 2026-01-15

Overview

Relevant source files

Openwork is a standalone desktop automation assistant built with Electron that runs locally on your machine. The app hosts a local React UI (bundled via Vite), communicating with the main process through contextBridge IPC. The main process spawns the OpenCode CLI (via node-pty) to execute user tasks. Users provide their own API key (Anthropic, OpenAI, Google, or Groq) on first launch, stored securely in the OS keychain.

Key Navigation:

  • Getting started: 2 Installation & Configuration
  • Architecture: 3 System Architecture
  • Development: 4 Development Guide
  • Features: 5 Feature Overview
  • Contributing: 6 Contribution Guide

What is Openwork?

Openwork addresses the fundamental challenge of AI-powered automation: keeping your data local while providing powerful AI capabilities. The system provides:

Three Core Principles

Principle Description Benefit
🖥️ Local Execution Your files stay on your machine Complete privacy and control
🔑 Bring Your Own AI Use your own API keys No subscriptions, full provider choice
📖 Open Source Every line of code is visible Trust, customization, and community-driven
⚡ Action-Oriented It acts, not just chats Real automation capabilities

Sources: README.md L21-86

Key Features

📁 File Management ✍️ Document Writing 🔗 Tool Connections
Sort, rename, and move files based on content or rules Prompt it to write, summarize, or rewrite documents Works with Notion, Google Drive, Dropbox, and more
     
⚙️ Custom Skills 🛡️ Full Control  
Define repeatable workflows, save them as skills You approve every action. You stay in control.  

Sources: README.md L89-103

System Architecture

Openwork implements a four-layer architecture integrating tightly with the Electron framework and OpenCode CLI:

Layer 1: User Interface

Entry Points:

flowchart TD

    User["User via Desktop App"]
    Electron["Electron App<br>React UI (Vite)"]
    Preload["Preload Script<br>contextBridge IPC"]

    User -.->|"User interactions"| Electron
    Electron -.->|"Secure API"| Preload

Three interaction modes:

  • Desktop Application: Primary interface (macOS DMG, Windows/Linux planned)
  • Command Line: Through OpenCode CLI integration
  • File System: Direct file operations with user permission

Sources: README.md L194-205

Layer 2: Electron Application

Core Components:

flowchart TD

    Main["Main Process<br>apps/desktop/src/main/index.ts"]
    Preload["Preload Script<br>apps/desktop/src/preload/index.ts"]
    Renderer["Renderer Process<br>React UI (Vite)"]
    IPC["IPC Handlers<br>task/settings/auth"]

    Renderer -.->|"window.accomplish.*"| Preload
    Preload -.->|"ipcRenderer.invoke"| Main
    Main -.->|"ipcRenderer.on"| Preload
    Preload -.->|"callbacks"| Renderer
    Main -.-> IPC

The Electron architecture handles:

  • Main Process: App lifecycle, IPC handlers, OpenCode CLI spawning, secure storage
  • Preload Script: Secure API exposure via contextBridge
  • Renderer Process: React UI with Zustand state management
  • IPC Communication: Typed communication between processes

Sources: apps/desktop/src/main/index.ts L1-212 apps/desktop/src/preload/index.ts L1-150

Layer 3: OpenCode Integration

CLI Spawning Architecture:

flowchart TD

    Electron["Electron Main<br>Process"]
    NodePTY["node-pty<br>Terminal Emulation"]
    OpenCode["OpenCode CLI<br>(Bundled)"]
    MCP["MCP Servers<br>Optional"]
    AI["AI Providers<br>Anthropic/OpenAI/Google/Groq"]

    Electron -.->|"spawn"| NodePTY
    NodePTY -.->|"PTY Session"| OpenCode
    OpenCode -.->|"Tasks"| MCP
    OpenCode -.->|"API Calls"| AI

Key integration features:

  • node-pty: Secure terminal session for OpenCode CLI
  • Bundled OpenCode: Multi-provider AI support (Anthropic, OpenAI, Google, Groq)
  • MCP Server Support: Extensible automation capabilities
  • API Key Management: Secure storage in OS keychain

Sources: CLAUDE.md L32-42

Layer 4: Storage & Security

Data Persistence:

flowchart TD

    Keytar["keytar<br>OS Keychain"]
    ElectronStore["electron-store<br>Local Settings"]
    TaskHistory["Task History<br>Persistent Storage"]

    Main -.->|"API Keys"| Keytar
    Main -.->|"App Settings"| ElectronStore
    Main -.->|"Task Logs"| TaskHistory

Security layers:

  • OS Keychain: Secure API key storage (macOS Keychain, Windows Credential Vault, Linux Secret Service)
  • Local Settings: User preferences, debug mode, onboarding state
  • Task History: Persistent task execution logs and results

Sources: CLAUDE.md L38-42

Technology Stack

Component Technology Purpose
Desktop Framework Electron Cross-platform desktop application
Frontend React + Vite Modern UI with fast development
State Management Zustand Lightweight client-side state
IPC Communication contextBridge Secure process communication
Terminal Emulation node-pty CLI process spawning
Storage keytar + electron-store Secure + local storage
Type Safety TypeScript End-to-end type safety
Testing Playwright E2E testing framework
Package Manager pnpm Fast, disk-space efficient
Bundled Runtime Node.js v20.18.1 Standalone MCP server support

Sources: CLAUDE.md L67-73

Key Behaviors

Single Instance Enforcement

  • Second instance focuses existing window
  • Prevents multiple app instances running simultaneously
  • macOS dock icon integration

Secure API Key Management

  • API keys stored in OS keychain with native encryption
  • Validation via test request to respective provider API
  • Multi-provider support (Anthropic, OpenAI, Google, Groq)

Task Execution Flow

  1. User provides task description via UI
  2. Main process spawns OpenCode CLI via node-pty
  3. OpenCode CLI executes task with user’s AI provider
  4. Progress streamed through task:update and task:progress events
  5. Permission requests bridge to UI for user approval

Bundled Node.js Runtime

  • Packaged app includes Node.js v20.18.1 binaries
  • Ensures MCP servers work on machines without Node.js installed
  • Critical for spawning npx/node in main process

Sources: CLAUDE.md L158-163 CLAUDE.md L109-155

How to Use It

Takes 2 minutes to set up.

Step Action Details
1 Install the App Download the DMG and drag it into Applications
2 Connect Your AI Use your own OpenAI or Anthropic API key. No subscriptions.
3 Give It Access Choose which folders it can see. You stay in control.
4 Start Working Ask it to summarize a doc, clean a folder, or create a report. You approve everything.

Sources: README.md L105-122

Development Setup 

pnpm install
pnpm dev

That’s it.

Prerequisites

  • Node.js 20+
  • pnpm 9+

All Commands

Command Description
pnpm dev Run desktop app in dev mode
pnpm dev:clean Dev mode with clean start
pnpm build Build all workspaces
pnpm build:desktop Build desktop app only
pnpm lint TypeScript checks
pnpm typecheck Type validation
pnpm -F @accomplish/desktop test:e2e Playwright E2E tests

Sources: README.md L148-178

Environment Variables

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

Sources: README.md L181-188

Architecture Overview 

flowchart TD

    User["User"]
    Electron["Electron App<br>React UI"]
    Main["Main Process<br>IPC Handlers"]
    Preload["Preload Script<br>contextBridge"]
    OpenCode["OpenCode CLI<br>node-pty"]
    MCP["MCP Servers"]
    AI["AI Providers<br>Anthropic/OpenAI<br>Google/Groq"]
    Storage["OS Keychain<br>Local Settings"]

    User -.->|"Interacts with"| Electron
    Electron -.->|"window.accomplish API"| Preload
    Preload -.->|"Secure IPC"| Main
    Main -.->|"Spawns"| OpenCode
    Main -.->|"Stores in"| Storage
    OpenCode -.->|"Executes tasks via"| MCP
    OpenCode -.->|"Calls APIs"| AI
    MCP -.->|"Extends"| OpenCode

Why Openwork?

Privacy First: Your files and data never leave your machine. You control which folders the app can access.

Provider Freedom: Use any AI provider you want with your own API keys. No lock-in.

Open & Transparent: Every line of code is open source. MIT licensed.

Action-Oriented: It doesn’t just chat - it actually does work on your files and systems.

Community Driven: Built with contributions from the open source community.

Sources: README.md L21-86

Contributing

Contributions welcome! Feel free to open a PR.

# Fork → Clone → Branch → Commit → Push → PR
git checkout -b feature/amazing-feature
git commit -m 'Add amazing feature'
git push origin feature/amazing-feature

Sources: README.md L212-225

License

MIT License - see LICENSE

Credits

Built by Accomplish

Your AI coworker that lives on your desktop.

The boulder never stops rolling until your work is done.

Back to top

OpenWork Documentation - Community documentation for accomplish-ai/openwork