DOCSEARCHbyAlgolia
Submit Docs

Coworker Documentation

repository·main·Indexed 27 days ago

https://github.com/accomplish-ai/coworker

An open-source AI desktop agent designed to automate local file management, document creation, and browser-based tasks. It features a local-first approach allowing users to provide their own AI models via API keys or local providers like Ollama. The project includes the @coworker_ai/agent-core library for managing tasks, storage, permissions, and skills, as well as the dev-browser-mcp server for browser interaction via Builtin or Remote CDP modes.

Tokens
69.8K
Snippets
81
Records
359
Agent score
95%

What's inside Coworker

  1. Overview of Coworker™

    main
    Coworker is an open-source AI desktop agent designed to run locally on your machine. It automates file management, document creation, and browser-based tasks. Unlike chat-only AI, Coworker is an 'action-oriented' tool that can interact with your local filesystem and various web services. It follows a local-first privacy model where you control folder access and use your own AI models or API keys.

  2. Overview of Accomplish Architecture

    main
    Accomplish is an open-source AI automation assistant designed for desktop use (macOS, Windows, Linux). It allows users to delegate complex software engineering tasks to an AI agent capable of web browsing, code writing, command execution, and file management. The system follows a local-first approach where users provide their own API keys for various LLM providers.

  3. Overview of Coworker™ AI Desktop Agent

    main
    Coworker is an open-source AI desktop agent designed to run locally on your machine. It automates file management, document creation, and browser-based workflows. Unlike chat-only AI, Coworker can perform actions such as organizing files, renaming/moving files based on rules, and connecting to tools like Notion, Google Drive, and Dropbox via local APIs. It is built with a local-first privacy approach, meaning files stay on your machine and you control which folders the agent can access.

  4. Overview of Coworker capabilities

    main

    Coworker is designed to act as an autonomous agent for local tasks. Key capabilities include:

    • File Management: Sort, rename, and move files based on content or specific rules.
    • Document Writing: Prompt the agent to write, summarize, or rewrite documents.
    • Tool Connections: Connect to services like Notion, Google Drive, and Dropbox via local APIs.
    • Custom Skills: Define and save repeatable workflows as custom skills.
    • Browser Automation: Automate workflows such as research and form entry.

    Privacy Note: Coworker runs locally. You must explicitly choose which folders the agent is allowed to access, and you must approve every action the agent attempts to take.

  5. Understand the Accomplish Architecture Components

    main

    The Accomplish system is divided into five primary functional layers that manage the lifecycle of AI tasks, from user interaction to local execution:

    1. Electron Shell (apps/desktop): Handles UI-specific native concerns like the system tray, native dialogs, OAuth popups, and IPC forwarding. It acts as a thin client to the daemon.
    2. React UI (apps/web): The user interface for managing tasks, viewing execution progress (messages, todos, permissions), and configuring settings (skills, connectors, integrations).
    3. Standalone Daemon (apps/daemon): A Node.js process that serves as the primary execution engine. It manages the task lifecycle via TaskService, handles scheduling, and spawns individual opencode serve subprocesses for each task.
    4. Core Logic (packages/agent-core): The shared ESM substrate used by both the daemon and desktop. It contains critical logic for task management (TaskManager), the OpenCodeAdapter (the bridge to execution), security (SecureStorage), and database management (SQLite).
    5. Execution Subprocess (opencode serve): A per-task subprocess that provides the actual environment for the AI. It includes built-in tools (Bash, Read, Write, Edit, etc.), manages MCP server connections, and handles native permission and question flows.

  6. Architectural implementation details for Coworker

    main

    The system relies on several key architectural patterns for reliability and performance:

    • SQLite with WAL mode: Used to enable concurrent reads during writes, supporting the IPC-heavy architecture where the UI reads while tasks write.
    • Singleton settings rows: app_settings and provider_meta use a CHECK id=1 constraint to ensure only one configuration row exists.
    • JSON-in-TEXT columns: Provider credentials, model configs, and OAuth metadata are stored as serialized JSON in TEXT columns for easier schema evolution.
    • Denormalized favorites: task_favorites copies prompt and summary from tasks to allow independent display without complex JOINs.
    • In-memory completion state: CompletionFlowState is intentionally not persisted. If the app crashes mid-task, the task is marked as failed rather than attempting to reconstruct state.
    • Machine-derived encryption key: SecureStorage uses PBKDF2 with machine-specific inputs (platform, homedir, username) to avoid OS keychain permission prompts while remaining suitable for rotatable API keys.
    • Ephemeral React state: The Zustand store is purely derived from IPC events. On restart, task history is reloaded from SQLite, but in-flight execution state (e.g., currentTool, startupStage) is lost.

  7. Coworker architecture overview

    main

    Coworker is an Electron-based desktop application with a React interface built using Vite.

    Project Structure:

    • apps/desktop/: Contains the Electron application (main, preload, and renderer processes).
    • packages/shared/: Contains shared TypeScript types.

    Core Mechanics:

    • The main process executes the OpenCode CLI via node-pty to perform tasks.
    • API keys are stored in the operating system's secure storage.

  8. Understand Accomplish Desktop Data Storage

    main

    Accomplish Desktop uses a combination of persisted and ephemeral storage.

    Persisted to Disk:

    • SQLite DB: Stores Tasks, Messages, Todos, Providers, Skills, Connectors, and App Settings.
    • Secure Storage: Stores API Keys and OAuth Tokens using AES-256-GCM encryption.
    • Skills Directory: Contains SKILL.md files (both official and custom).

    In-Memory (Ephemeral):

    • Completion State: Tracks flow state and retry counts. This is lost on crash.
    • Permission Promises: Handles deferred HTTP responses with a 5-minute timeout.
    • React Store: Uses Zustand; rebuilt from IPC on restart.

    External Data:

    • OpenCode Data: Located at ~/.local/share/opencode/. Contains sessions, messages, and its own database.
    • opencode.json: A file generated per task containing the system prompt and MCP configuration.

  9. Understand the Accomplish System Scope and External Interactions

    main

    Accomplish is a local-first desktop application that acts as a bridge between users and AI agent capabilities. It runs entirely on the user's machine without a cloud backend. Orchestration, storage, and credential management are handled locally, while the system connects to external LLM providers and local model servers via the OpenCode CLI.

    External Entities and Interactions

    EntityTypeInteractionData ExchangedProtocol
    End UserStakeholderDesktop UITask prompts, settings, approvalsElectron UI
    LLM Cloud ProvidersExternal APIAPI calls via OpenCode CLIPrompts, completions, tool callsHTTPS
    Local Model ServersExternal ServiceAPI calls via OpenCode CLIPrompts, completionsHTTP (localhost)
    GitHubExternal PlatformOAuth, releases, CI/CDAuth tokens, build artifactsHTTPS
    MCP Tool ServersExternal ServiceMCP protocol via OpenCode CLITool invocations, resultsstdio / HTTPS
    FilesystemOS ResourceFile read/write by agentCode files, documentsOS API

  10. Security and Data Protection in Accomplish

    main

    Accomplish is a local-first desktop application. It does not use user accounts or cloud-based logins; the user running the app owns all data.

    Key Security Features:

    • Authentication: API keys and OAuth tokens (e.g., for GitHub Copilot or OpenAI) are stored using AES-256-GCM encryption with a machine-derived PBKDF2 key.
    • Agent Permissions: The OpenCode CLI requests explicit permission for dangerous operations like file writes or shell commands. Users must approve or deny these via the UI.
    • Data Protection: Files are stored with 0o600 permissions. There is no backend, so data is not sent to a central server, though LLM API calls are made via HTTPS to the respective providers.
    • Secrets Management: Uses a custom SecureStorage class rather than the OS Keychain to avoid macOS permission prompts.

  11. Understand Coworker architecture

    main

    Coworker is built using Electron with a React UI packaged via Vite. The architecture is organized as follows:

    • apps/desktop/: The Electron application containing the main process, preload scripts, and the renderer process.
    • packages/shared/: Shared TypeScript types used across the workspace.

    Key Technical Details:

    • The main process executes the OpenCode CLI using node-pty to perform tasks.
    • API keys are stored securely using the operating system's native keychain.

  12. Understand the Coworker architecture

    main

    Coworker is built using an Electron-based desktop application with a React UI bundled via Vite.

    Project Structure

    • apps/desktop/: Contains the Electron application (main, preload, and renderer processes).
    • packages/shared/: Contains shared TypeScript types.

    Core Components

    • Main Process: Uses node-pty to spawn the OpenCode CLI for task execution.
    • Security: API keys are stored securely in the operating system's keychain.