Troubleshooting

macOS will not open Opsty

• It says Opsty is an app downloaded from the Internet. Expected, once. Choose Open.
• It says Opsty is damaged and can’t be opened, or that Apple could not verify it. The download is usually incomplete, or did not come from opsty.dev. Delete it, download it again from opsty.dev, and compare shasum -a 256 of the file with its line in SHA256SUMS. Please don’t remove macOS’s quarantine flag to get past this; the check is there to catch exactly a bad file.
• An Intel Mac. Opsty is built for Apple silicon only and does not open on a Mac with an Intel processor. Check Apple menu ▸ About This Mac.
• Operation not permitted when a command reads Desktop, Documents or Downloads. macOS protects those folders per app; Opsty’s failure card says macOS blocked access to this folder. Allow Opsty in System Settings ▸ Privacy & Security ▸ Files and Folders, or Full Disk Access. sudo does not get past this.

No notifications

• Opsty only notifies about a tab you are not looking at. The tab in front of a focused window never notifies; its lamp and words still change.
• Check Settings ▸ General ▸ When a tab needs me, then System Settings ▸ Notifications ▸ Opsty, and any Focus that is on.
• No button or reply field on the notification: the button appears only for Claude Code’s permission questions, and macOS shows buttons and reply fields only on alert-style notifications. Check System Settings ▸ Notifications ▸ Opsty, and Settings ▸ Helpers ▸ Answer from the notification.
• A command has to run for five seconds before its failure is news, and for ten before its success is.

An agent’s tab does not say what it is doing

• Opsty recognizes Claude Code, Codex and Gemini CLI. Other agents show as an ordinary program; a bell or a notification they send still reaches you.
• Codex shows its task only once the conversation has a name. Until then its tab says Codex.
• Gemini CLI shows what it is doing in its window title only while its own Dynamic Window Title setting is on, which it is by default.
• An agent run over ssh is on the server, and the tab keeps its server lamp. Claude Code is recognized there once its title has named it (✳ Claude Code); Codex and Gemini over ssh are not.

A key or a click that does nothing

• A link doesn’t open. Hold ⌘ as you click it, as in Terminal. A plain click only puts the keyboard in that pane. Hover it first to see where it goes.
• ⌥Space does nothing. Quick Terminal is off until you switch it on in Settings ▸ General. If Settings says ⌥Space is held by another app, Raycast or the ChatGPT app has it: record another chord there, or change theirs.
• ⌘K in vim or another full-screen program clears nothing, and says Not cleared: a full-screen program is in front. Leave the program first.
• ⇥ took the grey text instead of completing. While grey text follows what you typed, the first ⇥ takes it. Press ⇥ again to go back to what you typed and complete that. Settings ▸ Helpers ▸ Ghost text turns the grey text off.

Your shell

• fish. Opsty does not support fish yet, and loads nothing into it: a fish tab works as a plain terminal, with no marks beside commands, no command cards and no grey text. zsh, the macOS default, and bash are supported.
• Powerlevel10k. Its instant prompt warns about anything a startup file prints. Opsty’s shell integration prints nothing you can see while your shell starts, so if the warning appears, it is about something in your own startup files.
• For a line saying Opsty’s help did not load, see Shell integration.

Updates

• Opsty updates itself only from the Applications folder. Move it there to get updates. It is running from somewhere else, such as the disk image or Downloads. Move it to an Applications folder, yours or the Mac’s, and open it from there.
• Couldn’t reach dl.opsty.dev. Check the connection and try again. There is no connection, or a firewall blocked it. Blocking it is fine: Opsty keeps working, and simply doesn’t update.
• 0.4.1 didn’t install. Try again, or download it from opsty.dev. Opsty restarted but came back on the old version. It won’t try that version again until you press Try again in Settings ▸ Advanced; you can also download it from opsty.dev and drag it over the old copy.
• 0.4.1 wasn’t signed the way Opsty is, so it wasn’t installed. Download it from opsty.dev. The download was not Opsty’s, so it was thrown away. Download the new version from opsty.dev.
• 0.8.0 needs macOS 14 or later, so this Mac stays on 0.7.0. The new version doesn’t run on this Mac’s macOS, so Opsty doesn’t download it. Your copy keeps working; updating macOS brings the update back.

Korean input

Korean input works with the macOS 2-Set Korean input source, including in command cards and history search. The terminal engine Opsty is built on (xterm.js) has known limits with input methods, and you may meet these:

• In an agent’s own input line, the syllable being composed can land in the wrong place, or the last one can be dropped on Enter. Use ✎ Write a message (⌥⌘⏎): it is an ordinary Mac text box, and Korean composes there as it does everywhere else.
• In vim or other full-screen programs, esc or a ⌃ key pressed while a syllable is still being composed can be lost. Switch to the English input source before leaving insert mode, or press the key twice.
• The syllable being composed appears slightly out of place on some displays. Settings ▸ Advanced ▸ Renderer set to DOM draws it in place, at some cost in speed on very large output.
• Typing very fast can occasionally drop the last syllable of a word. Check the line before pressing Enter.

Wide characters line up with the grid, and search, history and copy handle Korean the same as English.

Anything else

Write to support@lonelyduck.io: what you did, what you saw, and your Opsty and macOS versions (Opsty ▸ About Opsty). Opsty is a LonelyDuck app, and that mailbox is where its mail is read.