Desktop

Desktop is the dashsquad app for Mac. Use it to deploy squad members, chat with them, and connect them to Telegram and WhatsApp.

Desktop starts the HQ on your computer and supervises it. The HQ is the background process that runs your squad. For automation, the HQ also has a Management API.

Desktop appCopy Anchor Link

The sidebar has these items:

To start a new chat with a squad member, put the pointer on its row and click the new-chat icon. A squad member with no chats shows No chats yet and a New chat link. The sidebar highlights the open chat and keeps its squad member expanded. Each squad member shows its 5 newest chats. Click Show all to see more.

Archive a chatCopy Anchor Link

To archive a chat, put the pointer on its row and click Archive chat. You can also click … on the row and choose Archive chat, or press ⌘⇧A in the open chat. Desktop then shows Archived and the chat title, with Undo for 8 seconds.

Archived chats go to Archived (N) at the end of the chats of the squad member. Each archived chat shows the date when you archived it. An open archived chat shows This chat is archived. Restore it to continue. Click Restore to use the chat again. You can also choose Restore chat on its row.

Desktop does not archive a chat that has work in progress. It tells you what to do first:

If Archive chat is not there, update your HQ.

To collapse or expand the sidebar, press ⌘B. When you collapse the sidebar, it shows the first letter of each squad member. Click a letter to expand the sidebar on that squad member.

SquadCopy Anchor Link

The Squad page shows each squad member with its status, name, model, tools and registration date. Use Search agents... to find a squad member.

To add a squad member, click Deploy agent. To remove a squad member, click the trash icon (Remove) on its row, then confirm in the Remove {name}? dialog. Click a squad member to open its detail page.

Squad member detailCopy Anchor Link

The header of the detail page has these controls:

• Click the name to rename the squad member.
• Chat opens a conversation with an active squad member.
• Disable stops an active squad member. Enable starts a disabled squad member again.
• Remove deletes a disabled squad member from the HQ.

The detail page has these tabs:

The Configuration tab has one card for each part of the setup:

• Working Directory: the directory for the file and shell tools. Open in Finder shows it. Reset to auto-generated removes your change.
• Models: the primary model and the fallback models. See Agents.
• System Prompt: the instructions that tell the squad member how to behave.
• Tools: the tools that the squad member can use. See Tools.
• Connectors and Plugins: the MCP servers and plugins that this squad member can use.
• Providers: the AI providers that this squad member can use. The default is All providers (default).
• Swarm: lets the squad member start parallel workers, with limits for each run.

ChatCopy Anchor Link

Chat with an active squad member directly from Desktop. Each conversation opens in a tab. Replies stream in real time, so you see thinking, tool activity and text while the agent works.

When no conversation is open, the chat panel shows your Recent conversations and your squad members. Conversations stay on the HQ, so you can continue them later on Desktop, the web app or the iOS app.

The strip above the conversation shows the model and the work directory of the squad member. Click the model to change it. The change applies at once and has no save step. Click the directory to choose Change directory…, Open in Finder or Reset to auto-generated.

If the model supports effort levels, the strip also shows the effort control next to the model. The control shows a gauge icon and the level, for example Default. Click it and choose Default or a level for this conversation. Desktop then shows Effort set to and the level. If the change fails, Desktop shows Could not change the effort. Try again. See Extended thinking.

By default, Return sends the message and Shift+Return starts a new line. Cmd+Return always sends. To make Return start a new line, go to Settings → General → Composer.

Tool calls show as cards that you can expand to see the full input and result. See Tool activity.

To copy one code block, select Copy above it. This copies only the code and keeps its spacing. Copied shows when the copy succeeds. You can also use Tab to reach Copy code, then press Return or Space. To copy the full reply, use Copy message.

Send a message while the agent worksCopy Anchor Link

While your agent works, you can still send a message. Click Send, and dashsquad sends the message as a Steer or a Follow Up:

• A Steer changes the response in progress. dashsquad labels it Auto-steered.
• A Follow Up waits in the queue and starts after the current response. dashsquad labels it Auto-queued.

If dashsquad is not sure, it asks you to choose Steer or Follow Up. To choose yourself, press Cmd+Return.

In the chooser, press the arrow keys to move between the two options, then press Return or Space to send. You can also press S for Steer or F for Follow Up. These keys work on all keyboard layouts. Press Esc to close the chooser. The chooser shows this help: ↑↓ to choose · Enter to send · S Steer · F Follow Up · Esc to cancel.

You can edit or remove a queued Follow Up before it starts. Stop ends the current response. The reply then ends with Response cancelled.

While a Steer waits, the line below it tells you when the agent gets it: Delivered after the current step (…) with the tool and its time, or Delivered at the next step.

Stop one stepCopy Anchor Link

A tool call that runs shows its time. After 30 seconds, it also shows Stop step. Click Stop step to end that tool call, and the calls that run with it. The response continues. If you sent a Steer, the agent gets it next. Stop ends the full response.

If Stop step is not there, update your HQ.

If you stop a response or a response fails, the queue shows Follow Ups paused. Click Resume Follow Ups to continue. After a stop, the composer shows Response cancelled. Your Follow Ups wait. Resume or remove them before sending. You cannot send a new message until you resume or remove the Follow Ups. If the HQ is older than the app, the app tells you to update the HQ.

Chats that agents startCopy Anchor Link

A squad member can start a new chat or rename a chat when you ask it in the chat. Refer to Chat and name tools. A chat that a squad member started shows a first row with Started from and a link to the old chat. If the old chat is archived or deleted, the link says so. The old chat shows a note with Open chat. Click it to open the new chat.

Live browser viewCopy Anchor Link

When a squad member with the browser tool opens a browser, a globe icon (View browser) shows in the chat. Click it to see the browser of the agent in a panel next to the chat.

While the agent works, the panel shows Agent is driving. Between turns, it shows You have control. Then you can click, type, paste and scroll in the page yourself, for example to solve a CAPTCHA. See Browser → Live view.

OfficeCopy Anchor Link

Click Office in the sidebar to see your full squad at work. The Office page shows each squad member as a small pixel-art character at its own desk. It is an optional view. It changes nothing: your chats, goals and settings stay where they are. The Office is in Desktop only.

A character shows only what the HQ reports. Each character sits behind a desk that hides only its lower body, so you always see its face. Each character has a nameplate under its desk with the name of the squad member. When there is room, the nameplate also shows the state. A badge on the head of the character, at the top right, shows a state icon. A character that has more to say than its state shows a bubble above its head.

The header shows the number of squad members, how many work now, and how many need you. If the HQ does not answer, the page shows HQ unreachable. States return when it answers. While the HQ starts, the page shows HQ starting.

The Office is different from the desktop companion in Settings → General. The companion shows one decorative character. The Office shows your squad.

StatesCopy Anchor Link

The shape of the icon shows the state, not only its colour. A screen reader reads the name, the state and the bubble text of each character.

BubblesCopy Anchor Link

A bubble shows the state word and one more line. For a squad member that works, the bubble can show Thinking, Running and the name of the tool, Replying or Waiting on a sub-agent. The line can also show the last words of the reply. For a squad member that needs you because of a question, a limit or a paused thread, the line shows the sentence from the HQ. For a goal or a routine, the bubble shows only Needs you: the sentence from the HQ contains text that you typed. A bubble never shows your own messages.

A bubble with only the state word does not show by itself: the badge and the nameplate already say it. Put the pointer on a character, or move the focus to it, to see its bubble. When many squad members are busy, the page shows only some bubbles. When more than 8 squad members work at the same time, some characters show only Working on their nameplate.

The pantryCopy Anchor Link

The Pantry is a small room at the bottom of the office, with its own floor. It has a fridge, a coffee machine, a water cooler and a plant. An idle character can leave its desk, walk to the Pantry, and come back. This is only decoration. When the HQ reports new work for the squad member, its badge changes at once, and the character goes back to its desk. A character that works, waits for you or failed never leaves its desk.

Open a chat from the OfficeCopy Anchor Link

Click a character to open the chat of that squad member. Desktop opens the chat that runs now, or else the newest chat. If the squad member has no chat, Desktop starts a new one. If the squad member has no chat and Desktop cannot reach the HQ, the click opens the page of the squad member instead.

You can also use the keyboard:

The focus ring stays on the character, also while it walks. Shortcuts with ⌘, for example ⌘B or ⌘J, work as usual.

RosterCopy Anchor Link

A roster strip lists every squad member with its name and state as text. Squad members that need you or failed come first, then the ones that work, then the rest. The strip shows two rows of names; if there are more, scroll the strip. Click a name, or press Return on it, to scroll to its character. The character shows a highlight ring for a moment. While Desktop still loads chats, the roster shows Some agents have no loaded chat yet.

Reduce motionCopy Anchor Link

If Reduce motion is on in macOS (System Settings → Accessibility → Display), the characters stay at their desks and do not animate. The badges, nameplates and bubbles still change when the HQ reports a change.

SettingsCopy Anchor Link

The Settings page has these sections:

Settings → GeneralCopy Anchor Link

• Account: your dashsquad account. If you are signed in, the card shows Signed in as {email} and Sign out. If you are not signed in, it shows Not signed in and Sign in. For the sign-in steps, see Remote Access.
• If the sign-out fails, the card shows We could not sign you out. Try again.
• After you sign out, remote access continues to work. If the HQ has remote access, Settings → Devices shows Your phones stay paired. Sign in to change remote access.
• HQ card: the name of the HQ. Your phone and your web browser show this name. To change it, type a new name and click Save. Save works only after the HQ has remote access.
• If the HQ does not have remote access, the HQ card shows Set up remote access. See Remote Access.
• Details in the HQ card shows the HQ id and the Relay host.
• Reset HQ… makes a new HQ on this Mac and runs the setup wizard again. Desktop first asks Reset this HQ?. Click Reset HQ to continue. Desktop first removes the old HQ from your account. Your agents and conversations stay in the old HQ folder.
• Your account can lose this Mac's HQ, for example when you remove it on your phone. Then the HQ card shows This HQ was removed from your account. Your phone and web browser cannot reach it. Click Reset HQ… to make a new HQ on this Mac and run setup again.
• HQ section: Restart HQ asks you to confirm a restart of the selected local HQ. The restart interrupts its work and loads the HQ version included with Desktop. This can be an older version. Cancel or Escape closes the confirmation without a restart.
• Change HQ opens Choose an HQ. Use this computer runs the HQ on this Mac, which is the default. The other two options, Connect existing HQ and Self-host on a VPS, are for advanced users.
• If Desktop cannot verify the HQ version, the HQ card names the HQ and shows HQ version could not be verified. The HQ stays available. Click Restart HQ to review the restart choice.
• If a restart fails, Desktop shows Could not restart HQ. Try again. You can retry the restart. If the version check fails, click Check again to repeat only the check.
• Composer: by default, Return sends the message. To make Return start a new line, clear Pressing Return sends the message. Cmd+Return always sends, and Shift+Return always starts a new line.
• Desktop companion: select Show the companion to show an animated character on your desktop. It is only decoration. It does not show agent activity. Under Appearance, select the character.
• Usage data: if you do not want to share usage data, clear Share usage data. The data never includes your messages, files or keys. The setting applies to all your devices. This section shows only when you are signed in to dashsquad. See Usage data.

Remove an old HQ from your accountCopy Anchor Link

In Settings → General, find Other HQs on your account. The list includes old registrations and HQs that are offline. It omits HQs whose account access you revoked.

The HQ configured on this Mac is protected, even when stopped.

1. Click Remove from account next to the HQ.
2. Check the HQ name and ID in the confirmation.
3. Click Remove from account to confirm. Cancel is the default.

Removal revokes that HQ's phone and browser access through your account. Its local files stay on the computer. Removal does not stop the HQ process.

If removal fails, the list shows the error. Click Try again to retry. If the list fails to load, click Retry HQ list.

Settings → ChatCopy Anchor Link

Under While a response is running, choose how dashsquad sends a message while your agent is active:

• Route automatically: dashsquad decides if your message is a Steer or a Follow Up. When it is not sure, it asks.
• Always ask: you choose Steer or Follow Up yourself every time.

Automatic routing needs an OpenRouter key on the HQ. Without one, dashsquad asks every time, and the page tells you to add a key in AI Providers. This setting applies to all apps that support automatic routing.

AI ProvidersCopy Anchor Link

Add API keys for your AI providers in Settings → AI Providers. The built-in providers are Anthropic, OpenAI, Google, Moonshot AI and OpenRouter. You can also sign in with a Claude or ChatGPT subscription.

All squad members that use a provider share its key. The HQ keeps the keys in its encrypted secret store. See AI Providers and Secrets.

Telegram and WhatsAppCopy Anchor Link

In Settings → Messaging Apps, connect your squad to Telegram or WhatsApp. You can add a connection, set which squad member gets each message, and manage allowlists and denylists. See Telegram and WhatsApp.

ConnectorsCopy Anchor Link

In Settings → Connectors (MCP), add Model Context Protocol (MCP) servers. A connector gives your squad the tools of that server, for example Linear or GitHub. A connector can use a command (stdio), standard HTTP or SSE.

For an HTTP or SSE connector, the form also has an OAuth client (optional) group. If the service gave you an OAuth client, type its Client ID and Client secret. Type the https address of the server that issued them in Authorization server. If you leave Authorization server empty, the HQ binds the client to the first server that accepts it.

If a connector needs browser sign-in, Desktop opens an authorization dialog. This can occur when you add a connector, reconnect it, or click Re-authorize. Click Open Authorization Page → on the computer that runs the HQ. Complete sign-in within five minutes.

For a saved connector that waits for authorization, click Continue authorization to open its dialog again. If the link is unavailable, Check status refreshes the connector details. It does not start or cancel authorization.

If a status check fails, check your HQ connection, then click Check again. This checks the same request; it does not start authorization again. When the HQ requires a new sign-in, the connector shows Re-authorize. Click it to start a new request. Check again cannot restart denied or expired authorization.

Click Cancel authorization to stop the pending request on the HQ and keep the saved connector. If cancellation fails, Desktop shows an error and refreshes the current status. It does not report a successful cancellation.

Close or Escape closes the dialog and stops Desktop status checks. It does not cancel the request on the HQ. After an error, Refresh connectors reloads the connector list. See Connector authorization.

DeployCopy Anchor Link

Click + next to Agents in the sidebar. The wizard has two steps: Agent and Review.

Update DesktopCopy Anchor Link

If you have no open chat, the chat screen shows the Desktop version at the top, for example dashsquad 0.15.0. A build that is not a production build also shows its channel, for example dashsquad 0.15.0 · staging. Settings → General → About shows the same text.

Desktop 0.11.1 and later versions update automatically. Desktop looks for a new version when it starts and then every 6 hours. It downloads the new version. During the download, the window shows dashsquad {version} is downloading. If the download fails, this notice goes away. Desktop tries again at the next check.

When the download is complete, the window shows dashsquad {version} is ready. and a Restart to update button. The menu bar menu also shows Restart to update.

If you do nothing, Desktop installs the update by itself. It waits until the Mac has had no keyboard or mouse input for 10 minutes and no chat reply is in progress. Then it restarts with the new version. To install the update now, do one of these:

• Click the dashsquad icon in the menu bar and choose Restart to update. Desktop asks Restart to update?. Click Restart to update. Desktop and the HQ restart with the new version. Your phone connects again when the HQ is back.

  If Desktop verifies that its local HQ uses an older version than its bundled HQ, it restarts that HQ once. Desktop first checks the HQ identity and authentication. It keeps an HQ with the same or a newer version.

  If Desktop cannot verify the version, the HQ stays available. Review the notice in Settings → General and use Restart HQ if needed.

• Quit Desktop and the HQ: click the dashsquad icon in the menu bar, choose Quit dashsquad… and click Quit and stop HQ. Desktop installs the update when it quits. When you open dashsquad again, Desktop and the HQ use the new version.

Update an older versionCopy Anchor Link

Desktop versions before 0.11.1 do not update automatically. Install the new version one time by hand:

1. Click the dashsquad icon in the menu bar.
2. Choose Quit dashsquad HQ….
3. Click Quit HQ. Desktop stops the HQ and then quits.
4. Download dashsquad for Mac from https://www.dashsquad.ai.
5. Open the DMG file. Move DashSquad to your Applications folder and replace the old app.
6. Open dashsquad.

After this, Desktop updates automatically. The HQ is part of Desktop, so the HQ also gets the new version.

How it connectsCopy Anchor Link

Desktop connects to the HQ through two channels:

An HQ that Desktop starts does not use the fixed ports. It uses free ports, and writes them to ~/.dashsquad/<hq-id>/ports.json. The ports 9300 and 9200 apply to a standalone HQ.

Desktop keeps its data in ~/.dashsquad. The desktop folder holds the settings and the log of Desktop. Each HQ has its own folder, ~/.dashsquad/<hq-id>/. For more information, see Configuration.

Desktop connects automatically. On the first start, Desktop starts the HQ as a background process and keeps the HQ tokens in the macOS keychain. On the next start, Desktop connects to the HQ that is already active.

Close the window, keep the HQCopy Anchor Link

When you close the Desktop window, the HQ continues to work. Your phone and other devices can still chat with your squad. Desktop stays in the menu bar and hides its Dock icon.

When dashsquad quits, the HQ stops too. Your phone and web app lose this HQ until you open dashsquad again. This is also true when dashsquad restarts to update. If dashsquad stops because of an error, the HQ can stop too. Keep dashsquad open to keep your squad available.

While the HQ runs, Cmd+Q and Quit in the app menu do not stop the HQ. When you close the window or press Cmd+Q, Desktop shows Your HQ keeps running. Choose one option:

• Close the window, keep the HQ running hides the window. The HQ continues to work.
• Quit and stop HQ… shows the quit warning. Then click Quit and stop HQ to stop the HQ and quit Desktop.

To close the question and keep the window open, press Escape. To stop the question, select Do not show this again. Desktop then hides the window without the question. If you then select Quit and stop HQ… and Cancel, Desktop does not keep this choice.

The first time that Desktop hides after each start, macOS shows the notification dashsquad HQ is running with the HQ name.

Click the menu bar icon to open the menu. The first line of the menu is dashsquad HQ · {name}. The second line shows the HQ state:

To open the window again, click the menu bar icon and choose Open dashsquad Desktop. If the HQ stopped, Desktop starts it again. You can also start Desktop a second time. Desktop then shows the window that is already open.

To copy the HQ name, choose Copy HQ name in the menu bar.

To stop the HQ:

1. Click the menu bar icon.
2. Choose Quit dashsquad….
3. Read the warning Quit dashsquad?.
4. Select Quit and stop HQ. Desktop stops the HQ and then quits.

To leave the HQ on, select Cancel.

The warning says: Your phone and your web browser lose access to your squad until you open dashsquad again. Running tasks stop.

While the HQ stops, the window shows Stopping the HQ…. This can take some seconds.

When you log out of macOS, Desktop quits and the HQ continues to work.

To use your squad from other devices, see Remote Access.

Next stepsCopy Anchor Link