Get started with CoWork OS

Install the app, connect one working model and create a small result you can review. You do not need to clone the source repository for a normal desktop installation.

1. Download the desktop app

Download CoWork OS for your platform. Current releases require macOS 13 or newer, or Windows 10/11. Version 0.5.51 is the final release for macOS 12; consult the release notes if you need that older version.

On an Apple Silicon Mac you can also install from the terminal. This fetches the same release without the quarantine attribute browsers add to downloads, so the app opens without the Gatekeeper "Apple could not verify" dialog that the DMG shows on first launch:

curl -fsSL https://raw.githubusercontent.com/CoWork-OS/CoWork-OS/main/scripts/install-macos.sh | bash

2. Connect and test a model

Open Settings → AI & Models → Model Access. Choose an available sign-in route, enter your provider credentials in the app or connect a local model such as Ollama. Use Refresh Models and Test Connection, then select an available model. Account entitlements and model availability depend on the provider. Compare providers and costs.

3. Choose a workspace and access profile

Use the private starter workspace for your first task, or choose a folder containing the files you want to work with. Start with Ask for approval so you can review requested actions as the task runs. Model selection and task permissions are separate settings.

4. Create a result you can inspect

Try: “Create a spreadsheet with six columns and four example rows for a project tracker. Save it in this workspace.” Open the output, check the contents and ask for one revision. This is a suggested starter task, not a guaranteed completion time or a benchmark.

If the first task does not start

Run the connection test again, check that the selected model is available to your account and confirm the local model server is running if you chose one. Check the task’s approval request before retrying. Follow the detailed troubleshooting sections below for provider-specific errors.

Then explore documents, research, browser work and automations.

Troubleshooting

• If Test Connection fails with 401/403, verify the API key or token and the account permissions behind it.
• If the Claude model list is empty, click Refresh Models after entering your API key or supported account token.
• If a provider endpoint changes, override the Base URL in Settings (custom providers or Groq/xAI/Kimi/OpenRouter).
• If Ollama fails to connect, confirm the service is running and the base URL is correct (default http://localhost:11434).
• If MLX-LM is unavailable, confirm that CoWork is running natively on an Apple Silicon Mac, install mlx-lm with the same python3 interpreter CoWork can find, and restart the app. See MLX-LM Local Inference.
• If cowork run asks for a missing token, confirm you did not pass --remote. Local CLI tasks should run without COWORK_CONTROL_PLANE_TOKEN.
• If cowork reports missing build artifacts in a source checkout, run npm run build:cli.
• If npm run setup fails on macOS with Killed: 9, macOS terminated the native build due to memory pressure. The setup script retries automatically (with exponential backoff); if it still fails, close other apps and run npm run setup again.
• Account-based routes can have different eligibility, quotas, and billing rules from first-party apps. Check the provider's current terms and Model Providers before relying on an account plan for third-party harness usage.

Optional: Try another visible workflow

After reviewing your first output, try a document, presentation, web page, or browser task:

• create a sample Word document
• create a two-slide presentation
• create a simple HTML landing page
• go to example.com and test the website as a normal user
• open my local app and test the main flow at desktop, tablet, and mobile sizes

Generated documents, spreadsheets, presentations, and web pages appear as artifact cards and open in the right sidebar or fullscreen workbench. Live website testing opens the Browser Workbench, where you can follow browser actions and review the resulting page.

<p align="center"> <img src="../resources/branding/images/cowork-os-4.webp" alt="Task execution timeline" width="700"> <br><em>The task feed shows each turn's progress, the files it changed, and its outputs in one view.</em> </p>

Optional: Set up Workspace Kit

Workspace Kit is not required for your first task. To add durable workspace context later, open Settings > Memory > Settings > Advanced > Workspace kit and initialize the kit for a workspace. It creates .cowork/ context files, including project-specific guidance under .cowork/projects/. Review and maintain those files like other project instructions. Use npm run kit:lint in a development checkout to check freshness and missing or sensitive files. See Workspace Memory Flow.

Orientation: Where The New Product Surfaces Live

Once the app opens, the most important places to know are:

• Home: quick launch plus recent sessions and recent automation activity. In the Calm visual style, Home is Today: what needs you, one decision per card, then what was handled without you. See Today, Work and Team.
• Everything Workbench: generated documents, spreadsheets, decks, web pages, PDFs, and previews open from task output cards into resizable sidebar or fullscreen artifact workspaces. Use this as the default place for everyday generated knowledge work: review or edit the file, then ask the agent for changes without switching to a separate Word, Excel, PowerPoint, browser, or chat app. See Everything Workbench.
• Uploaded PDFs: attach a PDF to a task or chat turn when you want CoWork to summarize it, answer questions from it, extract clauses, or transform it. The first prompt includes only a compact PDF excerpt plus page/extraction metadata and the workspace-relative path; CoWork reads the full PDF on demand with the document parser. PDF excerpts are treated as untrusted document data, and visual layout questions use the visual PDF reader instead.
• Long-document reviews: ask for a read-only review of named .docx, .pdf, .md, or .txt files to use bounded extraction, full coverage accounting, and evidence reduction. Requests that edit the source remain on the normal task path. See Long-Document Analysis.
• Message box shortcuts: type / in the main message box to search app commands and skill-backed workflow shortcuts in one menu. Use /side to ask read-only questions about the selected running session from the right panel, /schedule for standalone scheduled tasks, /schedule here for scheduled follow-ups in the selected thread, /clear to clear the current task view without deleting history, /plan <task> for the Plan runtime override, /cost <task> for estimates, /multitask [N] <task> for bounded parallel lane work, or shortcuts such as /strategy, /batch-rename, and /gmail-summary-drive from the bundled CoWork Shortcuts pack. Skill-backed selections insert the slash token first so you can add context before sending; Claude-for-Legal workflows can then show structured matter-context cards in the task view. See Message Box Shortcuts, Side Chat, Multitask Command, and Claude-for-Legal Workflows.
• Task menu: open a task and use the three-dot menu beside the title for pin/rename/archive, copy working directory/task ID/deeplink/Markdown, fork session, view outputs, or turn the current task into a same-thread or new-task automation. See Task Automations.
• Automations: open the main-sidebar Automation Studio to discover templates, build a versioned structured flow, test it without external writes, turn it on, and inspect step-level activity. See Automation Studio.
• Workspace agents: select Bots on the left icon rail and expand Workspace agents to create and inspect reusable managed agents (called Agents Hub before 0.5.60). The clicked-agent detail page is for configuration and actions, not a separate chat. Test this agent, Preview, and starter prompts start a normal managed-session task and open it in the main task window, where follow-ups, approvals, responses, and outputs work like any other task. See Managed Agents.
• Bots: select Bots on the left icon rail to open the Bots page and the bot list, create reusable bot identities and keep multiple conversations under each one. Selecting a bot reuses its latest unarchived conversation or opens a dormant one; the first message starts execution. Edit the profile from the bot row or conversation header, and use conversation history for older streams. See Bots, conversations, and tasks.
• More > Devices (in the Calm theme, Team, then a device): manage the local machine and saved remote CoWork nodes, run remote tasks, and inspect remote task history
• Work and Team (Calm only, on the icon rail): every session in one list, and everyone who works for you with what they wait on you for. See Today, Work and Team.
• Settings > Automations: advanced prompt-based Routines, Task Queue, Workflow Intelligence, Scheduled Tasks, Webhooks, and Event Triggers; Daily Briefing has its own Settings > Daily Briefing tab
• Settings > System & Security > Profiles: create, switch, export, and import isolated app profiles
• More > Mission Control: company and operator monitoring, Heartbeat-agent state, global runtime queue status, workspace Mission Board, feed, and Ops view
• Settings > Skills: Skill Store imports plus optional external read-only skill directories
• Settings > WhatsApp, Telegram, Slack and More Channels: Slack multi-workspace setup, Telegram group routing, Discord guild allowlists, channel/chat/thread specialization, and enterprise channels such as Feishu/Lark and WeCom
• Settings → Tools → Computer use (macOS): Accessibility + Screen Recording onboarding, built-in tool toggles, and context for desktop automation
• Settings → Tools → Chronicle: primary Chronicle setup for consent-gated recent-screen context, pause/resume, capture scope, OCR status, and linked memory behavior. The dedicated chronicle tool category still lives in Settings → Tools → Built-in tools. See Chronicle.
• Spreadsheet artifacts: when a task creates a spreadsheet, use the output card's Open action. Excel workbooks and CSV/TSV files open in the right sidebar; native Numbers, Google Sheets shortcut, ODS, and XLSB files use external-app/folder actions. Use fullscreen mode for editable spreadsheets with copy/save/zoom, row/column selection, attachments, voice input, and follow-up prompts. See Spreadsheet Artifacts.
• Document artifacts: when a task creates a Word-style document, the output card appears in the task feed. DOCX opens directly in the right-sidebar editor with Google Docs-style controls and save/copy actions; DOC, RTF, ODT, OTT, Pages, and related formats use best-effort preview or external-app/folder actions. Fullscreen mode keeps the follow-up composer and refreshes the preview after requested edits. See Document Artifacts.
• Presentation artifacts: when a task creates a PowerPoint deck, the output card appears in the task feed. PPTX opens in the right-sidebar presentation viewer with thumbnails, slide navigation, zoom, speaker notes, and fast text-first loading while slide images render or load from cache. Fullscreen mode keeps the follow-up composer so you can request deck edits and see the preview refresh after the file is updated. See Presentation Artifacts and PPTX Preview.
• Web page artifacts: when a task creates .html / .htm or built React output such as dist/index.html, the output card appears in the task feed. The main Open action opens a sandboxed web preview in the right sidebar; fullscreen mode keeps the follow-up composer so you can request page edits and see the preview refresh after the file or build output is updated. React-style projects without built output show a build-output-needed state instead of starting a dev server. See Web Page Artifacts.

If you are just getting started, do not configure everything at once. Set up an LLM provider, run one local task, then add Devices or Automations as needed.

Optional: Try Chronicle

Use this if you want CoWork OS to understand vague on-screen references from the desktop app.

1. Open Settings > Tools > Chronicle.
2. Turn on Chronicle (Research Preview) and accept the consent prompt.
3. Grant Screen Recording for CoWork OS if macOS prompts for it.
4. Optional but useful: grant Accessibility so Chronicle can attach better frontmost app/window metadata.
5. Confirm Settings > Tools > Built-in tools still has Chronicle enabled.
6. Restart the app if you changed Screen Recording.
7. Put a window with distinctive visible text on screen for 15-30 seconds.
8. Start a fresh task with the per-task Chronicle ON toggle left enabled and ask:

Use screen_context_resolve now. Tell me what app and window are on screen and what text is visible on the right side.

Once that works, try vaguer prompts such as what is this on screen or why is this failing. You can later pause Chronicle from the Chronicle settings card or the tray menu instead of turning it off entirely.

See Chronicle for the full guide and Troubleshooting if it does not trigger.

Optional: Add A Remote Device

Use this when you want CoWork OS to run tasks on another machine, such as a Mac mini or remote workstation.

1. Start CoWork on the remote machine and enable the Control Plane.
2. Decide how you will reach it:
   • same LAN
   • SSH tunnel
   • Tailscale
   • reverse proxy only when the Control Plane stays loopback/private and COWORK_CONTROL_PLANE_ALLOWED_ORIGINS is set
3. On your main machine, open More > Devices (in the Calm theme, Team > Add a device).
4. Click Add new device.
5. Enter the gateway URL, token, display name, and purpose.
6. Connect the device and confirm it appears in the device list.
7. Select that device and run a small test task.

After connection, you can browse remote workspaces, attach files from the remote machine, and inspect remote task history from the same Devices surface.

For VPS/headless deployments, prefer SSH tunnels or Tailscale. Direct 0.0.0.0/:: Control Plane binds fail closed unless Tailscale, private container context, or an explicit break-glass override is configured.

Optional: Set Up Profiles

Use profiles when you want separate CoWork environments for personal work, clients, staging, or isolated channel credentials.

Typical profile workflow:

1. Open Settings > System & Security > Profiles.
2. Create a new profile or duplicate your current one.
3. Switch into that profile before configuring channels, providers, or skills.
4. Use Export Profile to create a transferable profile bundle.
5. Use Import Profile on another machine or install to restore the same setup, with optional rename on import.

Each profile keeps its own local database, encrypted settings, managed skills, channel configs, and session history.

Optional: Turn On Automations

Open Automations in the main sidebar when you want to build a structured flow. Start from a template, a conservative prompt-generated draft, or a blank flow; test it with sample JSON; review its scopes and approvals; save the draft; and select Turn on only after validation passes. See Automation Studio.

Open Settings > Automations for advanced queue policy, prompt-based Routines, lower-level schedules/hooks/triggers, and Workflow Intelligence, and Settings > Daily Briefing for the briefing.

Recommended order:

1. Automation Studio: create one safe flow, keep it manual at first, run a dry test, then turn it on and inspect Activity.
2. Task Queue: confirm concurrency and timeout defaults for wider background execution.
3. Routines: use a prompt-based routine only when a deterministic multi-step graph is unnecessary.
4. Daily Briefing: enable a daily summary if you want background context generation.
5. Webhooks / Event Triggers: connect inbound automation only after you have a stable workspace and provider setup, and only when you need the lower-level surfaces directly.
6. Workflow Intelligence: enable reviewable Next actions once you have at least one stable workflow target. Dreaming tidies the memory folder about once a day; review changes to your own notes in Settings > Memory > Review. Code-change auto-create works best on trusted git-backed workspaces where worktrees are available.

Rule of thumb:

• use Automation Studio for a structured multi-step flow with variables, branches, testing, approvals, and step-level activity
• use prompt-based Routines for one saved instruction block with target, policy, outputs, and run history
• use Scheduled Tasks, Webhooks, or Event Triggers directly only when you specifically need the advanced underlying engine
• use a task's three-dot menu and Add automation... when a task you just ran should become a recurring automation; this creates a task-sourced routine, continues the same thread by default, and preserves a source task/deeplink reference

Example Tasks to Try

1. File Organization

Title: Organize Downloads
Description: Organize all files in this folder by type. Create folders for Images, Documents, Spreadsheets, and Other. Move files into appropriate folders.

2. Create a Spreadsheet

Title: Create sales report
Description: Create an Excel spreadsheet with monthly sales data for Q1-Q4. Include columns for Month, Revenue, Expenses, and Profit. Add a summary row with totals.

3. Create a Document

Title: Write project summary
Description: Create a Word document summarizing our project. Include sections for Overview, Goals, Timeline, and Next Steps. Use professional formatting.

4. Create a Presentation

Title: Create quarterly report
Description: Create a PowerPoint presentation with 5 slides covering Q1 2024 highlights. Include: Title slide, Overview, Key Metrics, Challenges, and Next Steps.

When the task completes, the .pptx appears as a presentation artifact card. Click Open to inspect it in the right-sidebar viewer with thumbnails, slide navigation, zoom, extracted speaker notes, and a white slide canvas. CoWork shows slide text immediately, then loads cached or freshly rendered slide images in the background. Use fullscreen mode when you want to request follow-up deck edits from the same viewer.

5. Web Research (works out of the box; optional paid providers for richer results)

Title: Research AI trends
Description: Search the web for the latest trends in AI for 2024 and create a summary document with the top 5 findings.

6. Browser Automation

Title: Screenshot a webpage
Description: Navigate to https://example.com and take a screenshot. Save it as example-screenshot.png.

Interactive browser tasks use the visible Browser Workbench by default. For form testing or JavaScript-heavy apps, the agent should navigate, call browser_snapshot, and then use refs for click/fill/type/read actions. For responsive checks, use browser_emulate before screenshots or snapshots so the shared workbench and saved captures reflect the tested desktop/tablet/mobile viewport. Launching Chrome with your signed-in system profile is explicit opt-in, and attaching to an already-running Chrome or Edge is refused; the default workspace browser profile does not reuse system Chrome cookies.

Browser Use Cloud stealth browsers are available only as an explicit opt-in backend. Configure BROWSER_USE_API_KEY, then request browser_provider: "browser-use-cloud" for a public HTTP(S) site. Cloud mode is blocked for localhost, private networks, file: URLs, generated local HTML artifacts, and intranet-style hostnames; use the default visible Browser Workbench for those targets. Browser Use Cloud sessions are stopped by browser_close, and retryable pending-stop results include the Browser Use session id if the stop API fails.

For sign-in, use Passwords & autofill (the key button) in the local Browser Workbench or ask CoWork to sign in and answer its private dialog. It supports one-use or saved logins, 1Password/Bitwarden CLI access, and verification codes. Addresses and local cards use approved autofill; a card fill never authorizes an order. Keep secrets out of chat. See setup and approval rules.

7. Inspect An Uploaded Video

Attach an .mp4, .mov, or .webm file and ask:

Title: Inspect the demo recording
Description: Review the attached video. Summarize the visible UI states, any failures, and the final outcome.

CoWork samples the video into representative still frames for image-capable models. The task timeline shows the extracted contact sheet and representative full frame as inline image artifacts, so you can inspect the same screenshots the agent used. See Video Attachments.

Understanding the UI

Sidebar (Left)

• Icon rail: Home, Inbox, Bots and Automations, plus Work, Team and Library in the Calm visual style. More holds Devices, Mission Control, Add tools and, in Calm, Build; pin any of them to the rail. Use Cmd/Ctrl+number to jump to a rail item, and drag or Alt+Up/Down to reorder. Settings is at the bottom of the rail and opens inside the app window.
• Session panel: New session, an always-visible search (Cmd/Ctrl+K), Running and Needs you filters, sessions grouped by day (Today, Yesterday, and so on), and a collapsed Automated sessions section for scheduled, hook, API and heartbeat runs.
  • In the Calm visual style the panel keeps pinned items, your projects and the five most recent other sessions, then All work opens Work, which lists every session, automated ones included. Searching or filtering the panel still lists everything.
• Notices: one dismissable notice area above Automated sessions, for tips such as the use-case gallery.

Today, Work and Team (Calm)

In the Calm visual style, Home opens on Today. Under the greeting, one line says how much needs you ("2 things need you. The rest is handled."), then each decision is a card, most pressing first. Three cards show at a time; Show N more lists the rest. The bell, the session panel's Needs you badge, the Bots page and Mission Control's Brief count the same decisions.

• Approvals: Review opens the approval's own review dialog over Today, with the same checks as in the session.
• Questions: a question with two to four plain options is answered right on the card; other questions open the session.
• Paused sessions say why they stopped (for example, an approval that timed out); Open or Reply continues in the session.
• Commitments due soon: Mark done, or Work on it to draft a prompt in the composer.
• Suggestions: Start runs the exact prompt shown on the card; Not now hides it for a day; Edit puts the prompt in the composer; Dismiss stops showing it. A follow-up can be kept with Add as commitment (due a day later), and a suggestion about making time can Hold the next free stretch on your calendar.
• Calendar (with Google Workspace connected): conflicts between two events in the next three days (Decline the later one when you were invited to it, Keep both, or Open in Calendar), a suggested 90-minute focus hold before a commitment is due, inside working hours (9:00 to 18:00), and prep for a meeting with other people in the next day (Prepare runs the prompt shown on the card). A hold is private and busy, with nobody invited; declining tells the organizer, as declining in Google Calendar does.
• Reply drafts (opt-in): see Reply drafts on Today.

Offers, such as a suggested hold, meeting prep or the offer to draft replies, use a quieter card and aren't counted as needing you. Below the cards, the handled rows list what got done: your actions on the cards, automated sessions that finished in the last day, and commitments memory closed because they looked done, each with Undo to reopen it.

Work lists every session, automated ones included, grouped by project. Filter by status, Started by and Owner, or search. Repeated runs of the same work are collapsed into one row, and the detail panel shows the next decision, where the work runs, its last activity, result and outputs.

Team shows each agent, bot, scheduled task and automation as a teammate: what it is responsible for, what it is waiting on you for, its recent work and how it is set up. For an agent, May do alone sets its access limit, and Edit agent opens its full settings (seniority, capabilities, tools, model and personality). Schedules can be paused or resumed here, and your devices (this computer and paired remote nodes) are listed with the work running on each.

Task View (Right)

• Task Header: Title and metadata
• Task Description: What you asked for
• Activity Timeline: Real-time execution log showing:
  • Task created
  • Plan created
  • Steps started/completed
  • Tool calls
  • Files created/modified
  • Errors

Approvals

When an action falls outside what the selected access profile allows without asking (for example deleting files, bulk operations or a command-tool call), the task shows an inline approval card in the task feed with:

• What it wants to do
• Why it needs to do it
• Deny and Allow once buttons

A card that gets no answer times out after 5 minutes. Unattended runs (schedules, triggers) deny instead of waiting. See Access Profiles.

Configuring Providers

Model Providers

Open Settings > AI & Models > Model Access:

Prompt caching is enabled by default on supported Anthropic and GPT-style routes. CoWork automatically keeps stable session prompt sections cacheable and dynamic turn context uncached, so follow-ups can reuse the provider-side prefix without caching the clock, recall, or one-off guidance.

Compatible / Gateway Providers

Configure these in Settings > AI & Models > Model Access by entering API keys or tokens, model IDs, and base URLs when required.

Advanced override: prompt caching can be disabled manually with promptCaching.mode: "off" in the saved LLM settings payload or by launching the app with COWORK_PROMPT_CACHE_MODE=off.

Search Providers (Optional — DuckDuckGo works out of the box)

Web search works immediately via the built-in DuckDuckGo provider (free, no API key). For richer results (news, images, AI-optimized ranking), configure a paid provider in Settings > AI & Models > Web Search:

Channel Integrations (Optional)

WhatsApp Bot

1. Open Settings > WhatsApp
2. Click Add WhatsApp Channel
3. A QR code will appear
4. Open WhatsApp on phone → Settings > Linked Devices > Link a Device
5. Scan the QR code
6. Once connected, enable Self-Chat Mode if using your personal number
7. Set a Response Prefix (e.g., "🤖") to distinguish bot messages

After connection, WhatsApp uses the shared gateway message lifecycle: send normal text to start or follow up on a task, /new for a fresh next task, /new temp for a scratch temporary session, /stop to cancel, and /commands for the current remote command catalog. See Using CoWork from WhatsApp and Other Channels for examples and best practices.

For shared groups or dedicated operational channels, use Channel Specialization in the channel settings to default a channel, group, or topic/thread to a workspace, agent role, prompt guidance, tool restrictions, and optional shared-memory policy.

Telegram Bot

1. Create bot with @BotFather
2. Open Settings > Telegram
3. Enter bot token
4. Optionally set a group routing mode (all, mentionsOnly, mentionsOrCommands, commandsOnly)
5. Optionally add allowed Telegram group chat IDs if the bot should only respond in specific groups
6. Enable and test

Discord Bot

1. Create app at Discord Developer Portal
2. Open Settings > More Channels > Discord
3. Enter bot token and application ID
4. Invite bot to server
5. Optionally add allowed Guild IDs if the bot should ignore other servers
6. Enable and test

Slack Bot

1. Create app at Slack API Apps
2. Enable Socket Mode and create App-Level Token (xapp-...)
3. Add OAuth scopes: app_mentions:read, chat:write, im:history, im:read, im:write, users:read, files:write
4. Subscribe to events: app_mention, message.im
5. Install to workspace and copy Bot Token (xoxb-...)
6. Open Settings > Slack
7. Enter Bot Token and App-Level Token
8. Repeat Add Slack Workspace if you want more than one Slack installation in the same CoWork profile
9. Enable and test

Feishu / Lark

1. Create a bot/app in the Feishu or Lark developer console
2. Copy the App ID, App Secret, verification token, and event encryption key
3. Open Settings > More Channels > Feishu / Lark
4. Enter credentials, set the webhook/event callback URL shown by CoWork, then enable and test

WeCom

1. Create a WeCom app in the WeCom admin console
2. Copy the Corp ID, Agent ID, Secret, token, and EncodingAESKey
3. Open Settings > More Channels > WeCom
4. Enter credentials, configure the callback URL shown by CoWork in WeCom, then enable and test

App Integrations (Optional)

Open Settings > Integrations and click any card to configure productivity and storage tools:

• Notion — search and manage pages
• Box — search and manage files
• OneDrive — search and manage files
• Google Workspace (Gmail, Calendar, Drive, Docs, Sheets, Slides, Tasks, Chat) — shared OAuth
• Dropbox — list, search, and manage files
• SharePoint — search sites and manage drive items

After an integration is configured, type @ in the main message box to pick it from the grouped Agents, Integrations, and Files menu. Google Workspace appears as service-specific options such as Gmail, Google Drive, Google Calendar, Google Docs, Google Sheets, Google Slides, Google Tasks, and Google Chat when native or MCP-backed tools are available. Selecting an integration inserts an icon+name chip and sends soft routing metadata with the prompt. See Composer Mentions.

Google Workspace uses one shared OAuth connection for built-in tools and the Google Workspace MCP connector. If an existing connection is missing newer scopes for services such as Calendar MCP tools, Tasks, or Slides, reconnect from Settings > Integrations > Google Workspace and leave the default scope set enabled.

For slash-searchable app commands and workflow shortcuts, type / in the same message box. The / picker is separate from @ mentions and uses the skills/plugin-pack system for workflow aliases. Selecting a skill-backed workflow inserts the command into the composer so you can add more text before sending. Legal practice workflows can also ask for structured matter details in the main task view. See Message Box Shortcuts and Claude-for-Legal Workflows.

Enterprise MCP Connectors (Optional)

Install enterprise connectors from Settings > Integrations > Connectors (or browse connectors, MCP servers, plugins and skills together in Settings > Add tools):

Most service connectors provide tools like search, get, create, and update for their respective APIs. Local creative connectors provide app-specific tools for Rhino, Blender, and ComfyUI; their file arguments must stay inside COWORK_ARCH_PROJECT_ROOT or COWORK_WORKSPACE_ROOT. Available connectors include Stripe, Tavily, Grafana, Metabase, Socket, Home Assistant, Rhino, Blender, ComfyUI, and more. See the generated Connector Inventory for the full list and Enterprise Connectors for setup.

Development Workflow

Making Changes

The app supports hot reload:

1. React UI Changes: Edit files in src/renderer/ - auto-refreshes
2. Electron Main Changes: Edit files in src/electron/ - auto-restarts
3. Shared Types: Edit src/shared/types.ts - both reload

Project Structure

src/
├── electron/          # Backend (Node.js)
│   ├── main.ts       # App entry point
│   ├── agent/        # AI agent logic
│   │   ├── llm/      # LLM providers
│   │   ├── search/   # Search providers
│   │   ├── browser/  # Browser V2 session manager and workbench bridge
│   │   ├── tools/    # Tool implementations
│   │   └── skills/   # Document skills
│   ├── gateway/      # WhatsApp, Telegram, Discord & Slack
│   └── database/     # SQLite storage
├── renderer/         # Frontend (React)
│   ├── App.tsx       # Main component
│   └── components/   # UI components
└── shared/           # Shared between both
    └── types.ts      # TypeScript types

Debugging

Renderer Process (UI):

• DevTools open automatically in dev mode
• Use console.log() - shows in DevTools Console

Main Process (Backend):

• Use console.log() - shows in terminal
• Check logs:
  • macOS: ~/Library/Application Support/cowork-os/
  • Windows: %APPDATA%\\cowork-os\\

Database

SQLite database location:

• macOS: ~/Library/Application Support/cowork-os/cowork-os.db
• Windows: %APPDATA%\\cowork-os\\cowork-os.db

View it with any SQLite browser or:

# macOS
sqlite3 ~/Library/Application\ Support/cowork-os/cowork-os.db
.tables
SELECT * FROM tasks;

# Windows (PowerShell)
sqlite3 "$env:APPDATA\cowork-os\cowork-os.db"
.tables
SELECT * FROM tasks;

Building for Production

# Build both renderer and electron
npm run build

# Package desktop app
npm run package

Output: release/*.dmg (macOS) and release/*.exe (Windows)

Common Issues

Issue: "No LLM provider configured"

Solution: Open Settings > AI & Models > Model Access and configure at least one supported model route.

Issue: Electron won't start

Solution: Clear and reinstall:

rm -rf node_modules dist
npm run setup
npm run dev

Issue: "Permission denied" for workspace

Solution: Choose a folder you have write access to, like:

• ~/Documents/cowork-test
• ~/Downloads/test

Don't use system folders like /System or /Applications.

Issue: Tasks fail immediately

Solution: Check:

1. LLM provider is configured in Settings
2. API key is valid
3. Workspace has proper permissions
4. Network connection for API calls
5. Check console for error messages

Issue: Ollama connection failed

Solution:

1. Make sure Ollama is running: ollama serve
2. Check URL is correct (default: http://localhost:11434)
3. Make sure you've pulled a model: ollama pull llama3.2

Tips for Best Results

1. Be Specific: Clear task descriptions work better
2. Start Small: Test with a few files before bulk operations
3. Review Plans: Check the execution plan before it runs
4. Respond Carefully: Read approval requests and structured input prompts before accepting or submitting
5. Monitor Progress: Watch the timeline to understand what's happening, especially when parallel tool groups collapse into summary lanes
6. Use Local Models: Ollama and MLX-LM can run inference without a hosted-model charge and can work offline after the required models and dependencies are installed

Next Steps

Try Advanced Features

1. Web Search: Configure a search provider and ask research questions
2. Browser Automation: Have the agent navigate websites and extract data
3. Remote Access: Set up WhatsApp, Telegram, Discord, or Slack bot for mobile/remote access
4. Document Creation: Create professional Excel, Word, PDF, or PowerPoint files
5. Goal Mode: Define success criteria and let the agent auto-retry until verification passes
6. Custom Skills: Create reusable workflows with custom prompts in Settings > Skills > Custom Skills
7. MCP Servers: Connect to external tools via MCP in Settings > MCP Servers
8. Enterprise Connectors: Install shipped connectors (Salesforce, Jira, HubSpot, Stripe, Tavily, Grafana, Rhino, Blender, ComfyUI, and more) via Settings > Integrations > Connectors
9. Cloud Storage/Productivity: Connect Notion, Box, OneDrive, Google Workspace (Gmail/Calendar/Drive/Docs/Sheets/Slides/Tasks/Chat), Dropbox, or SharePoint — click their cards in Settings > Integrations
10. Parallel Tasks: Run multiple tasks concurrently (configure in Settings > Automations > Task Queue)
11. Safety limits: Set token/cost budgets and blocked commands in Settings > System & Security > Safety Limits

Learn More

• Full README - Complete documentation
• Implementation Summary - Technical details
• Project Status - Feature status

Getting Help

• Check console output for errors
• Review the task timeline for clues
• Read error messages in the UI
• Report issues at GitHub Issues