Reference
Troubleshooting
Almost everything that goes wrong in Deck has a known cause and a telltale symptom. This page starts with the automatic diagnostics and moves on to the cases it does not cover.
Start with diagnostics
In Settings, under the general group, the diagnostics screen measures everything on the spot and returns five rows, each one with the detail in plain text and, where possible, a button that fixes it:
| Check | What it proves |
|---|---|
| Persistent sessions | Whether what holds the sessions is up, and which version it is. |
| Agent integration | Whether the hooks are installed in each agent, and whether the status line comes from Deck. |
| Status and cost bridge | Whether the local address the hooks look for is the one that answers. |
| Terminal | How many sessions have a terminal attached. |
| Notifications | Whether they are on and whether the system accepts them. |
Worth running before any investigation. In most cases the yellow row already says what to do, and the button beside it either fixes the problem or copies the command that fixes it.
The session did not survive
Closing the app and losing what was running has four possible causes:
- macOS without tmux. Diagnostics shows the warning and copies the install command.
- A tmux version that is too old, or a version with a known screen drawing bug. Diagnostics says which case it is and what to update.
- Windows with the Deck service down. It can take a while on the first boot on a machine with antivirus. The app keeps trying in the background, and sessions created after it comes up are persistent from the start.
- Two copies of Deck on the same data folder. They fight over state and notifications, and the last one to open steals the hooks from the other.
On macOS you can reach the sessions from outside the app, from any terminal:
tmux -L deck ls
tmux -L deck attach -t deck-<id>The agent is missing
The agent list only shows the ones that answer the version command. If your agent works in the terminal but does not show up in Deck:
- Confirm it answers the version command in the same shell you normally use.
- Reopen Deck. It reads the shell search path once, at startup.
- On Windows, after installing an agent, the new path may require reopening the app.
A broken installer, one that exists but fails to run, counts as not installed on purpose. That avoids a session that opens and dies with command not found.
State stopped updating
If sessions stop lighting up, cost disappears from the footer and notifications go quiet, the problem is the agent integration. Known causes:
- Unreadable config file. Deck does not write over an invalid file. Diagnostics shows the error.
- Codex with hooks and no trust confirmation. It ignores them silently, and the reinstall button fixes it.
- Grok with a hooks file from another source. Deck does not overwrite it, and says so.
- A third party status line. If you already had one, it is preserved, and context and cost stop showing in the footer.
- Windows with the console forced to UTF-8. That makes the hooks fail with no message at all. Removing that setting from the PowerShell profile fixes it.
With Deck closed nothing is lost: the events are recorded and come in on the next boot. More about that in Agents.
The global shortcut does not respond
Registering the global keyboard shortcut fails silently when another application has already claimed the same combination. The way out is to pick another one in Settings, under the general group. The app offers ready alternatives for each system.
macOS cases
- The update refuses because the app is translocated. This happens when Deck was opened straight from the downloads folder. Move the application to the applications folder and open it from there.
- No permission to update. A non-admin account with the app installed by someone else. Reinstalling with the install command fixes it, putting the app in your home folder.
- Microphone denied. The agent is the one recording, but the system asks Deck for the permission. The app shows the warning and opens the privacy screen in the right place.
- The scrollbar does not follow the agent. In full screen, the history the terminal keeps is not the one the agent draws. Scrolling inside the agent belongs to the agent, and the Deck control moves through the local history.
Windows cases
- Antivirus delaying the first boot. The service that holds the sessions can take more than ten seconds the first time. The app waits and keeps trying.
- Console forced to UTF-8. Breaks the hooks with no message at all, as described above.
- Pasting an image into Claude Code. Its native shortcut on Windows is not the usual paste. Deck already sends the right sequence.
- Old PowerShell. Deck prefers the newer version when it exists, because the older one mangles accents in long text.
The first prompt disappears
If you wrote a long prompt and see a short command in the terminal reading a file, everything is fine. Above a few hundred characters Deck writes the text to a file and tells the agent to read it from there, because the terminal drops a very long line without warning.
The hard limit is 64 thousand characters. Above that the app refuses and asks you to shorten it, leaving the details in a project file.
When none of this helps
Write to deck@mazeanalytics.com.br with the Deck version, the system, what you expected and what happened. The installed version is in Settings, under the advanced group, and the diagnostics result helps a lot.
If it looks like a security flaw, the path and what to include are on the security page. To check keyboard shortcuts while you investigate, ⌘/ opens the sheet inside the app.