Desktop App Guide¶

Open Cowork is being simplified around the surfaces that users already understand and that map cleanly onto OpenCode:

• Home — start a chat, attach context, choose a model, or @mention a coworker
• Chat — the OpenCode session transcript, approvals, questions, files, and delegated coworker work
• Projects — searchable project-chat history and saved work context
• Playbooks — workflow-backed repeatable tasks created from Workflow Designer setup chats, with manual, scheduled, and webhook runs
• Team — built-in and custom OpenCode agents presented as coworkers with curated tools and skills
• Tools & Skills — MCP tools, OpenCode skills, credentials, and capability relationships
• Settings — appearance, models, permissions, storage, and workflow run behavior

Desktop is one Open Cowork surface. Cloud, Gateway, Standalone Gateway, Mobile, and Teams naming and package boundaries are defined in OSS Packaging and Gateway Migration.

Team dashboards, incident-control dashboards, and unsupervised autonomous learning controls are not part of the active app surface. User-invoked improvement work still belongs in Chat through the bundled autoresearch skill and agent.

flowchart TD
    Home["Home<br/>composer · attachments · @coworker pills"]
    Chat["Chat<br/>session UI · streamed events · approvals"]
    Projects["Projects<br/>search · facets · tags · saved context"]
    Playbooks["Playbooks<br/>setup chats · triggers · runs"]
    Team["Team<br/>built-in + custom coworkers"]
    ToolsSkills["Tools & Skills<br/>MCPs · skills · credentials"]
    Settings["Settings<br/>models · permissions · storage"]

    Home -->|submit prompt| Chat
    Home -->|open recent work| Projects
    Projects -->|open project chat| Chat
    Chat -->|@coworker| Team
    Chat -->|tool calls and artifacts| ToolsSkills
    Playbooks -->|run chat| Chat
    Playbooks -->|uses coworkers| Team
    Playbooks -->|uses tools and skills| ToolsSkills
    Settings -->|configure providers| Chat
    Settings -->|configure routing| Playbooks

Product Language And Density Standards¶

Open Cowork should read like a focused workbench, not an inventory of internal runtime kinds. Use these terms in user-facing copy:

• Chat for direct OpenCode sessions.
• Coworker for a reusable OpenCode agent profile in user-facing Studio copy.
• Tool for MCP/native capability access.
• Skill for packaged OpenCode instructions.
• Playbook for recurring or repeatable work saved from a Workflow Designer setup chat and backed by a workflow definition.
• Run for one execution of a workflow.
• Artifact for generated files, charts, reports, or delivery drafts.
• OpenCode for execution-engine details that matter to users.

Avoid presenting dormant implementation concepts such as team dashboards, incident-control dashboards, or unsupervised autonomous learning loops as current product features. If a feature does not help a user start work, delegate to a coworker, curate tools/skills, or review a playbook, it does not belong in the primary app navigation.

Shared visible statuses should stay consistent across Chat, Projects, and Playbooks: active, running, failed, paused, and archived.

Workspace copy should also stay stable:

• Local workspace means private local desktop state backed by the local OpenCode runtime.
• Cloud workspace means synced cloud state shared with web and gateway clients through Open Cowork Cloud.
• Gateway workspace means a private Standalone Gateway authority. Desktop may show the connection and support verdicts, but Gateway session operation stays deferred until the Standalone Gateway exposes a Desktop-safe session projection API.
• Paired Desktop workspace means a local outbound pairing connector. The owning Desktop remains the runtime authority; remote paths and artifact bodies stay redacted unless pairing policy explicitly allows them.
• Offline cached means cached cloud state is visible, but cloud sends and mutations are disabled until the connection recovers.
• Auth required means the desktop has a cloud connection but no usable token.
• Policy disabled means the org/profile returned a support-matrix verdict that blocks the action.
• Local-only action means the action depends on local host paths, local stdio MCPs, or machine runtime config and must not run in a remote workspace.
• Cloud-safe action means the action can be represented through the cloud control plane without implicit local file, local MCP, or secret upload.

The renderer should not infer those states from workspace ids alone. Use workspace.support() for action-level capability and policy verdicts, then show the returned reason when disabling a control.

For dense operational lists, prefer compact tables, split panes, saved filters, and bulk-safe actions. Use cards for browse/detail previews, not as the only way to manage large inventories. Empty states should offer a direct next action and avoid marketing copy.

Home¶

Home is the fastest path into useful work:

• model and reasoning controls match the in-thread composer
• file attachments use the same validation path as Chat
• coworker suggestion cards pre-fill native OpenCode agent mentions
• recent project chats let users return to active work without a separate overview page

Submitting from Home creates or activates an OpenCode session and routes directly into Chat. Home should not accumulate status dashboards or secondary workflow-monitoring cards.

Chat¶

Chat is the runtime surface. OpenCode owns execution; Open Cowork projects the events into a desktop-friendly transcript with:

• streamed assistant output
• tool calls and artifacts
• approvals and questions
• coworker task cards backed by OpenCode child-session delegation
• model, agent mode, reasoning, and attachment controls
• session inspection and export helpers

The transcript should stay faithful to OpenCode history. Do not invent a second execution model in the renderer.

Projects¶

Projects is the place to find prior project chats and saved work context. It is backed by OpenCode session/thread state and should optimize for fast recall:

• search
• project and status facets
• saved filters where they are useful
• metadata that helps users decide which project chat to reopen

Projects can link to playbook runs, but it should stay focused on recall and reopening work.

Playbooks¶

Playbooks are saved repeatable tasks created from normal OpenCode chats and stored as workflow definitions. They own:

• setup-chat creation with the Workflow Designer agent
• manual, scheduled, and webhook triggers
• local webhook URLs, authorization-header examples, and secret rotation
• run status, summaries, and linked run chats

The execution path still goes through OpenCode-native agents and approvals:

• Workflow Designer clarifies and saves the workflow through the Workflows MCP
• the selected lead coworker executes each saved run
• specialist coworkers can still be called through OpenCode-native delegation

Playbooks should feel like a simple list of saved repeatable tasks, not a separate agent runtime or operations dashboard.

Team¶

Coworkers are OpenCode-native agent configurations composed by Open Cowork. The Team surface should make it clear:

• what the coworker is for
• which tools and skills it can use
• whether it is built-in, configured, custom, or runtime-provided
• what model and reasoning settings it prefers
• where it can be used from Chat or Playbooks

Team UI can have a polished character feel, but the stats must stay grounded in real permissions, skills, tools, and runtime settings.

Tools & Skills¶

Tools & Skills is the capability catalog. It should answer:

• which MCP/native tools are available
• which skills are installed
• which coworkers and playbooks use each capability
• which credentials or permissions are required
• whether a capability is bundled, configured, or custom

Skills should be grouped and highlighted by the tools they use so users can understand the real authority behind a coworker or playbook.

Settings¶

Settings holds lower-frequency configuration:

• appearance and localization
• provider/model credentials
• shell and file-write permissions
• workflow launch, background, and notification behavior
• storage and cleanup

Settings should configure the core surfaces without introducing separate product concepts.

Cloud Web shares this Studio vocabulary and visual language for Cloud workspaces. The route/API matrix, Desktop/Cloud parity matrix, admin/settings surface matrix, and production visual QA checklist live in Cloud Web Studio. Those contracts keep Cloud Web chat-first and Desktop-aligned while preserving the OpenCode boundary: Cloud Web remains a Cloud API client, not an execution runtime.