Getting Started
Getting Started with CoWork OS
Synced from github.com/CoWork-OS/CoWork-OS/docs
Quick Start
Step 1: Install Dependencies
git clone https://github.com/CoWork-OS/CoWork-OS.git
cd CoWork-OS
npm run setup
Step 2: Run the App
npm run dev
This will:
- Start the Vite dev server (React UI)
- Launch Electron with hot reload enabled
- Open DevTools automatically
Step 3: Configure Your LLM Provider
- Click the Settings icon (gear) in the sidebar
- Choose your LLM provider:
- Claude - Claude API key or Claude subscription token
- Google Gemini - Gemini models (requires API key from aistudio.google.com)
- OpenRouter - Multiple models (requires API key from openrouter.ai)
- OpenAI - GPT-4o, o1 models (requires API key from platform.openai.com)
- AWS Bedrock - Enterprise AWS (requires AWS credentials)
- Ollama - Local models (free, requires Ollama installed)
- If you choose Claude, pick one of these tabs:
- Claude API: paste an API key from console.anthropic.com
- Claude Subscription: install the provider's terminal app, run its token setup flow, and paste the generated
sk-ant-oat...token
- Click Refresh Models to load the live models available to your credential, then choose a model
- Click Test Connection to verify
- Save settings
Optional: Configure Fallback Chains
After your primary provider works, open:
- Settings > LLM to set ordered fallback providers/models
- Settings > Web Search to set primary and fallback search providers such as Tavily, Exa, Brave, SerpAPI, or Google
CoWork OS uses those ordered chains when a provider is unavailable, rate-limited, or lacks the needed capability for a task.
For LLM providers, retryable failures such as 429 rate limits immediately advance to the next configured fallback provider/model. In Settings > LLM > Provider Failover, Retry primary after (seconds) controls when CoWork OS should probe the primary route again after failover:
- blank uses the default 60-second cooldown
0retries the primary on the next route refresh- higher values keep the working fallback route active longer before retrying the primary
Optional: Configure Memory Hub And Supermemory
Before you start relying on long-term context, open Settings > Memory Hub and confirm how memory should behave for this profile.
- Workspace Kit initializes the local
.cowork/context files used for durable prompt injection and project guidance. - Memory settings control local capture, privacy mode, retention, preview of the
L0/L1memory payload, and the Memory Inspector for structured archive observations. - Memory Inspector lets you search observation metadata, inspect details and timelines, edit titles/narratives, promote useful entries to curated memory, mark entries private, suppress prompt recall, redact content, soft-delete entries, and rebuild deterministic metadata when needed.
- Supermemory is optional. If you want an external memory provider, enable it here, paste your API key, keep the default
cowork:{workspaceId}container template unless you need something else, save, and click Test Connection.
Supermemory does not replace CoWork's local memory system. It adds an external profile/search layer, explicit supermemory_* tools, optional prompt-time profile injection, and optional mirroring of non-private local memory captures. Local structured observations remain authoritative for privacy controls; private, redacted, and suppressed entries stay local. See Structured Memory Observations and Supermemory Integration.
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 Claude subscription 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
npm run setupfails on macOS withKilled: 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 runnpm run setupagain. - Note: as of April 4, 2026, third-party harnesses connected to your Claude account draw from extra usage instead of from your subscription. If you do not use them, nothing changes. If you do, the credit and bundles above have you covered.
Step 4: Create Your First Task
-
Select a Workspace
- Click "Select Folder"
- Choose a folder you want CoWork OS to work in
- This will be your workspace (e.g.,
~/Documents/test-workspace)
-
Initialize the Workspace Kit (Optional, Recommended)
- Open Settings > Memory Hub
- Under Workspace Kit, click Initialize
- This creates a
.cowork/directory in your workspace for durable context, prompt injection, and project scaffolding - The root kit can include shared workspace files such as
AGENTS.md,USER.md,MEMORY.md,TOOLS.md,IDENTITY.md,RULES.md,SOUL.md,VIBES.md, andLORE.md BOOTSTRAP.mdis a one-time onboarding checklist; once you complete onboarding, removing it marks onboarding complete and CoWork OS tracks that state in.cowork/workspace-state.jsonHEARTBEAT.mdis reserved for recurring heartbeat-only checks rather than general task context- Project-specific context lives under
.cowork/projects/<projectId>/, whereCONTEXT.mdcaptures project notes andACCESS.mdcaptures project access boundaries
Try The Everything Workbench
After the app is configured, try tasks that produce or use visible work surfaces:
create a small spreadsheet with 6 columns and 4 rowscreate a sample Word documentcreate a two-slide presentationcreate a simple HTML landing pagego to example.com and test the website as a normal user
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 the agent and user share the same Browser V2 in-app browser, with visible cursor movement, accessibility snapshot refs, diagnostics, screenshots, annotation, and follow-up controls.
- Changes to tracked kit files keep revision snapshots under
.cowork/**/.history/ - You can validate kit health, freshness, and secret/missing-file warnings locally with
npm run kit:lint
-
Create a Task
- Click "+ New Task"
- Title: "Organize my files"
- Description: "Please organize all files in this folder by file type (Images, Documents, etc.)"
- Click "Create Task"
-
Watch it Work
- The agent will create a plan
- Execute steps using available tools
- Show real-time progress in the timeline
- Request approval before destructive changes
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
- 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 first stop for generated knowledge work: review or lightly edit the file, then ask the agent for changes without switching to a separate office 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.
- Message box shortcuts: type
/in the main message box to search app commands and skill-backed workflow shortcuts in one menu. Use/schedulefor scheduled tasks,/clearto clear the current task view without deleting history,/plan <task>for Plan mode,/cost <task>for estimates, or shortcuts such as/strategy,/batch-rename, and/gmail-summary-drivefrom the bundled CoWork Shortcuts pack. See Message Box Shortcuts. - 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 scheduled automation. See Task Automations.
- Devices: manage the local machine and saved remote CoWork nodes, run remote tasks, and inspect remote task history
- Settings > Automations: Task Queue, Workflow Intelligence, Scheduled Tasks, Webhooks, Event Triggers, and Daily Briefing
- Settings > Profiles: create, switch, export, and import isolated app profiles
- Settings > Companies: company shell setup, goals, projects, issues, planner state, and linked operators
- Mission Control: company and operator monitoring, Kanban board, feed, and Ops view
- Settings > Skills: Skill Store imports plus optional external read-only skill directories
- Settings > Channels: Slack multi-workspace setup, Telegram group routing, Discord guild allowlists, 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 → Memory Hub → Chronicle: primary Chronicle setup for consent-gated recent-screen context, pause/resume, capture scope, OCR status, and linked memory behavior. The dedicated
chronicletool 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/.htmor built React output such asdist/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, Automations, or Companies as needed.
Optional: Try Chronicle
Use this if you want CoWork OS to understand vague on-screen references from the desktop app.
- Open Settings > Memory Hub > Chronicle.
- Turn on Chronicle (Research Preview) and accept the consent prompt.
- Grant Screen Recording for CoWork OS if macOS prompts for it.
- Optional but useful: grant Accessibility so Chronicle can attach better frontmost app/window metadata.
- Confirm Settings > Tools > Built-in tools still has Chronicle enabled.
- Restart the app if you changed Screen Recording.
- Put a window with distinctive visible text on screen for 15-30 seconds.
- 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.
- Start CoWork on the remote machine and enable the Control Plane.
- Decide how you will reach it:
- same LAN
- SSH tunnel
- Tailscale
- On your main machine, open the Devices tab.
- Click Add new device.
- Enter the gateway URL, token, display name, and purpose.
- Connect the device and confirm it appears in the device list.
- 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.
Optional: Set Up Profiles
Use profiles when you want separate CoWork environments for personal work, clients, staging, or isolated channel credentials.
Typical profile workflow:
- Open Settings > Profiles.
- Create a new profile or duplicate your current one.
- Switch into that profile before configuring channels, providers, or skills.
- Use Export Profile to create a transferable profile bundle.
- 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 Settings > Automations when you want CoWork OS to do background work without manually starting every task.
Recommended order:
- Task Queue: confirm concurrency and timeout defaults.
- Routines: create one safe routine with a manual or schedule trigger.
- Daily Briefing: enable a daily summary if you want background context generation.
- 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.
- Workflow Intelligence: enable reviewable Next actions once you have at least one stable workflow target. Code-change auto-create works best on trusted git-backed workspaces where worktrees are available.
Rule of thumb:
- use
Routinesfor saved automation with policy, outputs, and run history - use
Scheduled Tasks,Webhooks, orEvent Triggersdirectly 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 scheduled task; this creates a real cron job and preserves a source task/deeplink reference
Zero-Human Company Quick Start
If you want to use CoWork OS as a founder-operated autonomous company shell:
- Choose a real git-backed workspace.
- Open Settings > Memory Hub.
- Initialize Venture operator kit.
- Fill in the generated
.cowork/company files (COMPANY.md,OPERATIONS.md,KPIS.md,PRIORITIES.md,HEARTBEAT.md). - Open Settings > Companies.
- Create or select the company shell you want to operate.
- Click Open Digital Twins from that company.
- Activate:
Company PlannerFounder Office Operator
- Enable heartbeat for both operators.
- Return to Settings > Companies and confirm the operators are linked to the intended company.
- Open Mission Control from that company.
- In the planner strip, enable scheduling, set the planner agent, and click Run Planner.
- Use the
Opstab to monitor goals, projects, planner-managed issues, and linked execution runs.
See Zero-Human Company Operations for the full architecture, recipe, use cases, and operating model.
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. Real signed-in Chrome/Edge control is explicit opt-in through browser_attach; the default workspace browser profile does not reuse system Chrome cookies.
Understanding the UI
Sidebar (Left)
- Workspace Info: Shows current workspace name and path
- Settings Button: Configure LLM, search, and channel settings
- New Task Button: Create a new task
- Task List: All tasks sorted by creation date
- Task Status Indicators:
- Blue = Active (planning/executing)
- Green = Completed
- Red = Failed/Cancelled
- Gray = Pending
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
Approval Dialogs
When the agent needs permission for:
- Deleting files
- Bulk operations
- Shell commands
You'll see a dialog with:
- What it wants to do
- Why it needs to do it
- Approve or Deny buttons
Configuring Providers
LLM Providers
Open Settings > LLM:
| Provider | Setup |
|---|---|
| Claude | Use Claude API with a key from console.anthropic.com, or use Claude Subscription with a token from claude setup-token |
| Google Gemini | Enter API key from aistudio.google.com |
| OpenRouter | Enter API key from openrouter.ai |
| OpenAI (API Key) | Enter API key from platform.openai.com |
| OpenAI (ChatGPT) | Click "Sign in with ChatGPT" to use your subscription |
| AWS Bedrock | Enter AWS Access Key, Secret Key, and Region |
| Ollama | Install Ollama, pull a model, select it |
| Groq | Enter API key in Settings |
| xAI (Grok) | Enter API key in Settings |
| Kimi (Moonshot) | Enter API key in Settings |
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 > LLM Provider by entering API keys/tokens, model IDs, and base URLs when required.
| Provider | Setup |
|---|---|
| OpenCode Zen | API key + base URL in Settings |
| Google Vertex | Access token + base URL in Settings |
| Google Antigravity | Access token + base URL in Settings |
| Google Gemini CLI | Access token + base URL in Settings |
| Z.AI | API key + base URL in Settings |
| GLM | API key + base URL in Settings |
| Vercel AI Gateway | API key in Settings |
| Cerebras | API key in Settings |
| Mistral | API key in Settings |
| GitHub Copilot | GitHub token in Settings |
| Moonshot (Kimi) | API key in Settings |
| Qwen Portal | API key in Settings |
| MiniMax | API key in Settings |
| MiniMax Portal | API key in Settings |
| Xiaomi MiMo | API key in Settings |
| Venice AI | API key in Settings |
| Synthetic | API key in Settings |
| Kimi Code | API key in Settings |
| OpenAI-Compatible (Custom) | API key + base URL in Settings |
| Anthropic-Compatible (Custom) | API key + base URL in Settings |
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 > Web Search:
| Provider | Setup |
|---|---|
| DuckDuckGo | Built-in — no setup needed (automatic fallback) |
| Tavily | Enter API key from tavily.com |
| Exa | Enter API key from exa.ai |
| Brave | Enter API key from brave.com/search/api |
| SerpAPI | Enter API key from serpapi.com |
| Enter API key and Search Engine ID from Google Cloud Console |
Channel Integrations (Optional)
WhatsApp Bot
- Open Settings > WhatsApp
- Click Add WhatsApp Channel
- A QR code will appear
- Open WhatsApp on phone → Settings > Linked Devices > Link a Device
- Scan the QR code
- Once connected, enable Self-Chat Mode if using your personal number
- 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.
Telegram Bot
- Create bot with @BotFather
- Open Settings > Channels > Telegram
- Enter bot token
- Optionally set a group routing mode (
all,mentionsOnly,mentionsOrCommands,commandsOnly) - Optionally add allowed Telegram group chat IDs if the bot should only respond in specific groups
- Enable and test
Discord Bot
- Create app at Discord Developer Portal
- Open Settings > Channels > Discord
- Enter bot token and application ID
- Invite bot to server
- Optionally add allowed Guild IDs if the bot should ignore other servers
- Enable and test
Slack Bot
- Create app at Slack API Apps
- Enable Socket Mode and create App-Level Token (xapp-...)
- Add OAuth scopes:
app_mentions:read,chat:write,im:history,im:read,im:write,users:read,files:write - Subscribe to events:
app_mention,message.im - Install to workspace and copy Bot Token (xoxb-...)
- Open Settings > Channels > Slack
- Enter Bot Token and App-Level Token
- Repeat Add Slack Workspace if you want more than one Slack installation in the same CoWork profile
- Enable and test
Feishu / Lark
- Create a bot/app in the Feishu or Lark developer console
- Copy the App ID, App Secret, verification token, and event encryption key
- Open Settings > Channels > Feishu / Lark
- Enter credentials, set the webhook/event callback URL shown by CoWork, then enable and test
WeCom
- Create a WeCom app in the WeCom admin console
- Copy the Corp ID, Agent ID, Secret, token, and EncodingAESKey
- Open Settings > Channels > WeCom
- 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) — 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 Gmail, Google Drive, and Google Calendar. Selecting an integration inserts an icon+name chip and sends soft routing metadata with the prompt. See Composer Mentions.
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. See Message Box Shortcuts.
Enterprise MCP Connectors (Optional)
Install enterprise connectors from Settings > Integrations > Browse Registry:
| Connector | Type | Setup |
|---|---|---|
| Salesforce | CRM | OAuth or API key |
| Jira | Issue Tracking | API token + domain |
| HubSpot | CRM | API key |
| Zendesk | Support | API key + subdomain |
| ServiceNow | ITSM | OAuth or credentials |
| Linear | Product/Issue | API key |
| Asana | Work Management | Personal access token |
| Okta | Identity | API token + domain |
| Discord | Community | Bot token + application ID |
| Google Workspace | Productivity | OAuth in-app flow |
Each connector provides tools like search, get, create, and update for its respective service. 44 connectors are available in total, including Stripe, Tavily, Grafana, Metabase, Socket, and more. See Enterprise Connectors for the full catalog.
Social Integrations (Optional)
X (Twitter)
- Open Settings > X (Twitter)
- Choose Browser Cookies or Manual Cookies
- (Optional) Enable Mention Trigger and configure:
- command prefix (default
do:) - allowlisted authors
- poll interval and fetch count
- command prefix (default
- Save and test the connection
- See X Mention Triggers for bridge/native behavior and troubleshooting.
Development Workflow
Making Changes
The app supports hot reload:
- React UI Changes: Edit files in
src/renderer/- auto-refreshes - Electron Main Changes: Edit files in
src/electron/- auto-restarts - 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\\
- macOS:
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 (gear icon) and configure at least one LLM provider.
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:
- LLM provider is configured in Settings
- API key is valid
- Workspace has proper permissions
- Network connection for API calls
- Check console for error messages
Issue: Ollama connection failed
Solution:
- Make sure Ollama is running:
ollama serve - Check URL is correct (default:
http://localhost:11434) - Make sure you've pulled a model:
ollama pull llama3.2
Tips for Best Results
- Be Specific: Clear task descriptions work better
- Start Small: Test with a few files before bulk operations
- Review Plans: Check the execution plan before it runs
- Respond Carefully: Read approval requests and structured input prompts before accepting or submitting
- Monitor Progress: Watch the timeline to understand what's happening, especially when parallel tool groups collapse into summary lanes
- Use Local Models: Ollama is free and works offline
Next Steps
Try Advanced Features
- Web Search: Configure a search provider and ask research questions
- Browser Automation: Have the agent navigate websites and extract data
- Remote Access: Set up WhatsApp, Telegram, Discord, or Slack bot for mobile/remote access
- Document Creation: Create professional Excel, Word, PDF, or PowerPoint files
- Goal Mode: Define success criteria and let the agent auto-retry until verification passes
- Custom Skills: Create reusable workflows with custom prompts in Settings > Custom Skills
- MCP Servers: Connect to external tools via MCP in Settings > MCP Servers
- Enterprise Connectors: Install from 44 connectors (Salesforce, Jira, HubSpot, Stripe, Tavily, Grafana, and more) via Settings > Connectors
- Cloud Storage: Connect Notion, Box, OneDrive, Google Workspace (Gmail/Calendar/Drive), Dropbox, or SharePoint — click their cards in Settings > Integrations
- Parallel Tasks: Run multiple tasks concurrently (configure in Settings > Task Queue)
- Guardrails: Set token/cost budgets and blocked commands in Settings > Guardrails
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