🌐 Openwork - Open Browser Automation Agent

Openwork spawns the OpenCode CLI as an external process using node-pty pseudo-terminal emulation, enabling local execution of AI-driven browser automation tasks without cloud infrastructure. The Electron main process manages the CLI lifecycle, captures stdout/stderr streams, and marshals task results back to the React renderer via IPC, creating a fully local execution model where the AI provider (Anthropic, OpenAI, Google, Groq) is user-supplied via API keys.

Openwork stores AI provider API keys in OS-native secure storage (macOS Keychain, Windows Credential Vault, Linux Secret Service) via the keytar library, ensuring credentials are encrypted at rest and never persisted as plaintext JSON. The secure storage layer is abstracted in the main process and exposed to the renderer via IPC, preventing the Chromium renderer from ever accessing raw credentials.

Openwork generates OpenCode CLI configuration by reading app settings (provider, model, API key reference) and injecting them as environment variables or command-line arguments before spawning the CLI subprocess. The configuration generator validates that required settings are present (API key in keychain, provider selected) and constructs the CLI invocation with proper escaping and quoting. This approach keeps CLI configuration logic decoupled from Openwork, allowing the CLI to evolve independently.

Openwork implements a permission system that tracks which folders the user has granted access to, storing folder paths in app settings. When a task requires file system access, the main process checks if the target folder is in the permitted list; if not, it prompts the user via OS-native file picker (macOS NSOpenPanel, Windows IFileDialog) to grant access. Granted folders are stored persistently and reused for subsequent tasks without re-prompting.

Openwork maintains a task history log using electron-store with debounced writes to JSON files in the app's userData directory. The main process accumulates task records in memory and flushes to disk on a debounce timer (typically 1-2 seconds), reducing I/O overhead while ensuring eventual persistence. Task records include execution metadata (timestamps, status, provider used, token counts) and are queryable via the React UI for task replay and audit trails.

Openwork provides a React-based renderer process UI built with Zustand for state management, enabling users to create tasks, monitor execution progress, view task history, and configure AI provider settings. The renderer communicates with the main process via IPC for all side effects (spawning CLI, accessing credentials, persisting history), maintaining strict separation between UI state and system state. Zustand stores handle local UI state (form inputs, modal visibility) while IPC messages synchronize with authoritative main process state.

Openwork bundles a Node.js runtime within the Electron application and implements intelligent PATH resolution to locate the OpenCode CLI binary. The system PATH utilities search bundled runtime directories, system PATH environment variable, and fallback locations, enabling the app to function on systems without Node.js installed. The CLI path resolution is performed in the main process before spawning the CLI subprocess, with caching to avoid repeated PATH searches.

Openwork implements strict process isolation using Electron's three-process model: main process (Node.js), preload script (isolated context), and renderer process (Chromium). The preload script uses contextBridge to expose a curated API surface to the renderer, forwarding IPC messages to the main process for all privileged operations (spawning CLI, accessing credentials, file system). This architecture prevents the Chromium renderer from directly accessing system resources, credentials, or spawned processes.

Openwork provides a unified configuration interface for selecting AI providers (Anthropic, OpenAI, Google, Groq) and models, with provider-specific API key management. The configuration is stored in electron-store and exposed via the React UI, enabling users to switch providers without code changes. The main process reads the selected provider and model at task execution time, passing them to the OpenCode CLI via environment variables or command-line arguments.

Openwork implements a guided onboarding flow that walks users through initial setup: API key configuration (with secure storage via keytar), folder permission grants (for file system access), and provider/model selection. The onboarding state is tracked in electron-store and the React UI conditionally renders the onboarding flow on first launch. Folder permissions are requested via native OS dialogs (macOS file picker) and stored as app settings for subsequent task execution.

Openwork captures stdout and stderr streams from the spawned OpenCode CLI process in real-time using node-pty, forwarding execution logs to the React renderer via IPC messages. The main process buffers log lines and sends them to the renderer on a batching interval (typically 100-500ms) to reduce IPC overhead. The renderer displays logs in a scrollable task monitor UI, enabling users to observe task progress, debug failures, and track token usage in real-time.

Openwork implements a fresh install cleanup mechanism that resets application state (onboarding flag, debug mode, selected model) while optionally retaining task history and secure credentials. The cleanup is triggered via a manual reset action in the settings UI or automatically on major version upgrades. The main process clears electron-store entries selectively, preserving keytar credentials and task history unless explicitly purged by the user.