Using the Desktop App

The desktop app is designed for managing local projects, sessions, changes, and terminal verification in a graphical interface. This page explains how to use it through a complete task flow.

From project to result

A complete task usually follows this flow:

1. Add a local workspace.
2. Create or resume a session.
3. Describe the task in the Composer and use @ to reference relevant files or directories.
4. Choose a normal task, Plan, Goal, or Swarm based on the task.
5. Handle approvals and questions from the Agent.
6. Review changes, file previews, and Git status.
7. Run verification commands in the terminal.
8. Continue, revert, or finish based on the result.

For your first session, start with a read-only task to confirm that Desktop is using the right workspace before asking the Agent to change files.

Choose a task mode

The + button in the lower-left corner of the Composer provides several task modes:

• Normal task: Use for well-scoped changes that are easy to verify.
• Plan: Use when the impact is uncertain and you want to confirm the approach first. The Agent analyzes the task and proposes a plan before changing files. See Plan mode.
• Goal: Use for a longer objective that needs multiple turns and checks. The goal appears above the Composer and can be paused, resumed, or cancelled. See Goal mode.
• Swarm: Use for investigation or modification work that can be split into independent subtasks. Progress appears in the Tasks or Subagent area. See Agents and Sub-Agents.

While a task is running, you can send follow-up input to adjust the direction, such as narrowing the scope, adding constraints, asking for an explanation, stopping the current action, or reverting changes.

Provide useful context

Useful context reduces back-and-forth:

• Use @ to reference relevant files or directories.
• Paste or drag files, images, videos, and other attachments.
• Capture part of the screen and add a comment to provide page state, design references, or error information.
• Provide error logs, reproduction steps, expected behavior, and verification commands.
• Clearly state directories, files, or behavior that must not be changed.

Review changes

The right supporting panels are used to review results and inspect information related to the current task.

• Changes: Review changes in a file list or tree view, inspect an individual file, or inspect the changes from a single turn. The Changes tab is a singleton, so the new-tab menu hides it when one is already open.
• File Preview: Preview Markdown, JSON, HTML, PDF, CSV, images, and code or text files, with actions to copy, download, reveal in the system, and open in an external app. Markdown files with frontmatter show a metadata card.
• Thinking/compaction: View thinking-related presentation and context-compaction information.
• Agent/subagent: View the status and output of the current Agent or subagent.
• Side chat: Ask a follow-up question or discuss a side issue without leaving the main session.

The Changes tab in the right panel shows the exact diff for each modified file.

Verify in the terminal

The bottom terminal panel is the native desktop terminal. Open it from the terminal button in the upper-right corner of the session. It supports multiple tabs and runs commands with the current workspace as its cwd. Use it for the project's existing build, test, formatting, and other verification commands, or to inspect Git command output.

Do not rely only on the Agent's summary. Review the changes, run the project's verification commands, and continue only after the result is confirmed.

The bottom terminal panel runs verification commands like builds and tests and shows their output.

Manage sessions and background tasks

Sessions in a workspace can be created, switched, renamed, archived, restored, deleted, forked, exported, pinned, and searched. A title is generated after the first turn and can be regenerated from the session item.

The desktop app supports Tasks, Subagent, Swarm, and background Bash or subagent work for splitting tasks, handling independent work in parallel, or running background tasks while the main session continues. Task status and output appear in the session, Tasks, or Subagent areas. Whether work runs in parallel depends on the task type and request; not every task runs in parallel automatically.

Use external apps

File Preview is used to preview files and copy, download, reveal in the system, or open in an external app. The top menu opens the current project or file in an external app, including VS Code, Cursor, Zed, Xcode, the system terminal, or system file managers such as Finder or Explorer. It can also copy the current path.

Use an external editor when you need to continue editing files. Use the bottom terminal panel or an external terminal when you need to run commands.

Review Git status and changes

The Git status area shows the current branch, ahead/behind status, file changes, and pull request status. Changes provides a file-list view and a tree view, and lets you inspect an individual file or the changes from a single turn. Use File Preview to read the file content in more detail. Verify the result through Changes and the terminal.

The top of the Changes panel shows the current branch and the number of changed files; each file in the list expands to show its diff.

Adjust settings

The Settings panel includes General, Account, Agents & Sessions, Providers, Plugins, Shortcuts, About, Lab, and Archived Sessions. It is used to manage models, providers, message folding, account, permissions, shortcuts, agreement links, and experimental options.

The Settings sidebar lists General, Account, Providers, Plugins, and other areas; the right side shows the options for the selected area.

Continue with Quick Start for the shortest path through the first session.